简介：一份用Python重制的经典魂斗罗小游戏完整程序包，适合对游戏开发感兴趣的初中级开发者学习Python与Pygame实战项目。压缩包共247个文件、约2.67MB，其中228个png为游戏角色、场景等图像素材，9个py为源码模块，8个pyc为已编译文件，另含1个md说明文档和1张jpeg预览图，整体结构简洁清晰，便于按图索骥。游戏主程序名为Contra.py，采用WASD加J键的标准操作：A/D控制左右移动、W跳跃、S趴下、J射击、P退出，覆盖了完整的人机交互与游戏逻辑。目前已有1809人学习下载。通过阅读和调试这份源码，可以系统掌握游戏循环、输入处理、碰撞检测、动画切换等游戏开发基础；从初始化窗口到精灵动画，均可对照源码逐步拆解，也能在此基础上继续扩展关卡与角色，是一份兼具学习与娱乐价值的Python项目。
1. 用 Python 复刻魂斗罗，到底在复刻什么
“Python版魂斗罗完整程序包”这个标题，很多人第一反应是去搜源码、下载、运行，然后发现满屏报错就关掉了。实际上，真正有价值的不在于那几千行代码能不能一次跑通，而在于它把 FC 时代的横版射击游戏拆成了几个现代游戏开发依然在用的核心系统：基于像素的碰撞检测、状态机驱动的角色控制、瓦片地图渲染、对象池管理的子弹与敌人。这些系统放在今天做任何 2D 游戏都绕不开。
Python 本身不是游戏开发的主流语言，性能上限摆在那里，但它的优势在于表达力强、生态成熟，Pygame 社区积累了大量的实战代码。拿魂斗罗这种动作密集、判定严格的项目来练手，比做贪吃蛇和俄罗斯方块能学到的东西多一个量级。适合的人群很明确：已经掌握 Python 基础语法，想进入游戏开发领域但不想一上来碰 Unity 或 Godot 的开发者；以及想理解横版动作游戏内部机制的初中级程序员。
这篇文章不打算逐行讲解某个不可考的源码包，而是顺着“完整程序包”该有的模块，把地图、角色、子弹、敌人、关卡切换这几块的实现思路和代码骨架讲清楚。你拿到的任何一份实现，大概率也能对号入座。
2. Pygame 程序包的最小骨架与游戏循环拆分
2.1 为什么 Python 复刻魂斗罗几乎都选 Pygame
在 Python 生态里做 2D 游戏，可选项其实有限：Pygame、Arcade、Panda3D、Cocos2d-Python。Arcade 更现代，API 设计比 Pygame 友好，但社区存量和网上能搜到的横版射击范例远不如 Pygame 多。Pygame 用的是 SDL 底层，图像加载、输入事件、音频播放都封装好了，性能对于像素风游戏绰绰有余。
选择 Pygame 做魂斗罗类复刻，还有一个实际原因：SDL 的 Surface 和 Rect 类型天然适合做矩形碰撞检测。魂斗罗的角色、子弹、敌人判定框绝大多数是矩形，不需要像素级 mask，Pygame 的Rect.colliderect()直接覆盖了这个需求。而楼梯攀爬、掉落判定这些复杂交互，核心也是基于矩形与地图瓦片的坐标运算。
程序包的结构通常会按功能拆模块，而不是把所有代码塞进一个main.py。常见布局是一个main.py做入口，settings.py存常量，sprites.py放角色和敌人，map.py处理关卡数据，weapons.py管理子弹。这种拆法方便调试，也方便后续改参数。
2.2 游戏循环的固定节奏不能乱
横版射击游戏对帧率敏感，角色移动速度和动画播放都依赖稳定的时钟。Pygame 的Clock.tick(fps)控制循环速度，但这里有个容易被忽略的问题：直接用帧率控制移动速度，在不同性能机器上会导致角色跑得快慢不一。
正确的做法是让移动速度和帧率解耦。设定一个基准帧率（比如 60 FPS），角色速度写成“像素/秒”，每帧位移用速度 / FPS计算。Clock.tick(60)返回上一帧到这一帧的真实耗时（毫秒），用它来修正位移是最稳的。
import pygame FPS = 60 MOVE_SPEED = 200 # 像素/秒 clock = pygame.time.Clock() dt = 0.0 while running: dt = clock.tick(FPS) / 1000.0 # 转换为秒 keys = pygame.key.get_pressed() if keys[pygame.K_RIGHT]: player.rect.x += MOVE_SPEED * dt if keys[pygame.K_LEFT]: player.rect.x -= MOVE_SPEED * dtMOVE_SPEED * dt的意思是每秒移动 200 像素，而不是每帧移动 2 像素。dt通常在 0.016 到 0.02 之间浮动，乘以 200 后每帧位移约为 3.3 像素。如果不用dt修正，游戏在 30 FPS 和 144 FPS 的显示器上会是截然不同的体验。这个习惯在做任何 Pygame 游戏时都值得养成。
2.3 事件循环与按帧轮询的边界
Pygame 有两种输入获取方式：pygame.event.get()和pygame.key.get_pressed()。前者适合跳跃、开火这类“按下触发一次”的事件，后者适合左右移动这种“按住持续生效”的状态。魂斗罗需要两者混合使用，跳跃和射击必须用事件队列，因为短暂的单帧按键很容易被get_pressed()漏掉。
import pygame # 事件循环，处理单次触发 for event in pygame.event.get(): if event.type == pygame.KEYDOWN: if event.key == pygame.K_SPACE: player.jump() # 只触发一次 elif event.key == pygame.K_j: weapons.fire(player.direction, player.rect.center) # 按帧轮询，处理持续状态 keys = pygame.key.get_pressed() if keys[pygame.K_RIGHT]: player.move_right()很多初学者把KEYDOWN写在get_pressed()的if里，结果跳跃变得阻尼感明显，因为按键按住超过一帧就会重复触发。程序包里通常会在Player类里做一个jump_pressed标志位，事件循环里仅置位，物理更新里消费后立即清零，避免同一帧内重复触发跳跃。
3. 角色系统：状态机、碰撞盒与自由方向射击
3.1 用状态机管理站立、跑动、跳跃、攀爬
魂斗罗的角色不是简单贴图移动，它至少要包含站立、跑动、跳跃、站立射击、蹲下、攀爬六种状态。如果再用if-else堆状态，代码会迅速腐烂。程序包里的常见做法是用一个简单的枚举加状态切换方法，update()里根据当前状态走不同的逻辑分支。
from enum import Enum, auto class PlayerState(Enum): STAND = auto() RUN = auto() JUMP = auto() CROUCH = auto() CLIMB = auto() class Player: def __init__(self, x, y): self.state = PlayerState.STAND self.state_time = 0.0 self.rect = pygame.Rect(x, y, 28, 44) def set_state(self, new_state): if new_state != self.state: self.state = new_state self.state_time = 0.0 # 切换动画帧 self.frame_index = 0 def update(self, dt, colliders): self.state_time += dt if self.state == PlayerState.STAND: self.velocity.x = 0 elif self.state == PlayerState.RUN: self.velocity.x = self.facing * 200 elif self.state == PlayerState.JUMP: self.velocity.y += GRAVITY * dt # 更新位置并处理碰撞 self.rect.x += self.velocity.x * dt self.resolve_collisions(colliders)state_time除了统计当前状态持续时间，还用于动画帧切换。比如跑动动画每隔 0.1 秒切换一帧，state_time对0.1整除取余就能算出帧号，不需要单独维护计数器。状态切换的边界也很关键：跳跃状态下不能切到跑动，只能等落地；攀爬状态下禁用射击。
3.2 碰撞盒与视觉贴图分离的架构
角色贴图在魂斗罗里是有透明背景的，不同动作帧尺寸还不一样。如果直接用贴图矩形做碰撞判定，跳跃帧左右偏宽的贴图会让角色“被空气墙挡住”。程序包一般会把视觉矩形（image_rect）和碰撞矩形（hit_rect）分开管理，碰撞矩形固定在角色脚部和躯干的核心位置。
原版魂斗罗的角色判定框约为 16×24 像素（FC 分辨率下），复刻版本通常按比例放大。给一个具体参数参考：如果角色贴图缩放成 50×50 像素，碰撞盒设置成 20×40，左右各留 15 像素空隙。子弹可以碰不到贴图边缘，但碰撞盒一定要给出足够宽容的判定，否则玩家会抱怨子弹“明明打到了却穿透”。
class Player(pygame.sprite.Sprite): def __init__(self, x, y): super().__init__() self.image = pygame.image.load("assets/player_stand.png").convert_alpha() self.rect = self.image.get_rect() self.rect.x, self.rect.y = x, y # 碰撞盒：比视觉矩形窄，底部对齐 self.hit_rect = pygame.Rect(0, 0, 20, 40) self.hit_rect.midbottom = self.rect.midbottom def update(self, dt): # 每帧更新后，让碰撞盒跟随视觉位置 self.hit_rect.midbottom = self.rect.midbottomhit_rect.midbottom对齐到rect.midbottom是关键写法，保证角色跳跃和下蹲时，碰撞盒底部始终踩在地面上，不会出现头部越过平台但脚还悬空的判定错乱。
3.3 八方向射击的数学换算
魂斗罗的射击方向不止左右两向，还包括斜上、斜下、正上、正下。实现的核心是把玩家按下的方向键组合转换成角度，再换算成速度向量。角度取值是 45 度的倍数，不需要精确计算，映射到固定的方向向量数组即可。
import math def get_fire_direction(keys, facing): dx, dy = 0, 0 if keys[pygame.K_UP]: dy = -1 elif keys[pygame.K_DOWN]: dy = 1 if keys[pygame.K_LEFT] and facing == -1: dx = -1 elif keys[pygame.K_RIGHT] and facing == 1: dx = 1 if dx == 0 and dy == 0: dx = facing # 默认朝面对方向平射 # 归一化，确保斜方向速度不变成根号2倍 length = math.sqrt(dx*dx + dy*dy) return (dx / length, dy / length)这里最容易踩坑的是斜方向速度未归一化：dx=1, dy=-1时向量长度为 √2，子弹会比其他方向快 41%。物理上 45 度角射击的合速度应该保持 1，所以必须除模长。实际程序包里通常直接预计算一个方向查表：{(-1,-1): (-0.707, -0.707), (0,-1): (0,-1), ...}，每帧查表省去开平方运算。子弹只需要存储(vx, vy)和起始坐标，每帧原速移动。
4. 地图、碰撞与关卡切换的实现
4.1 瓦片地图的加载与渲染性能
魂斗罗的地图是典型的瓦片地图，背景由固定尺寸的瓷砖拼接，长度为屏幕宽度的 8 到 16 倍。Python 版复刻最常见的数据结构是二维数组，每个数字代表一种瓦片类型：0 表示空白，1 表示可立地面，2 表示砖块（子弹可破坏），3 表示楼梯，4 表示水（掉落即死）。
地图文件的存储通常用 CSV 或 JSON，程序包里一般有一个load_map(path)函数读入二维数组并缓存成 Surface 列表。
import json import pygame TILE_SIZE = 32 def load_map(json_path): with open(json_path) as f: data = json.load(f) rows = data["height"] cols = data["width"] tiles = data["tiles"] # 一维数组或二维数组 solid_tiles = {} for row in range(rows): for col in range(cols): tile_id = tiles[row][col] if tile_id != 0: solid_tiles[(col, row)] = tile_id return { "width": cols, "height": rows, "solid_tiles": solid_tiles }渲染性能是 Python 版最现实的问题。如果整张地图每帧都blit，一段 200 瓦片长的关卡就是 6400 次绘制调用，Pygame 会明显掉帧。标准做法是只渲染摄像头可视范围内的瓦片：计算start_col = camera.x // TILE_SIZE到end_col = (camera.x + screen_width) // TILE_SIZE，循环只跑这一段。
def render_map(screen, camera_x, map_data, tileset): start_col = max(0, int(camera_x // TILE_SIZE)) end_col = min(map_data["width"], int((camera_x + SCREEN_WIDTH) // TILE_SIZE) + 1) for row in range(map_data["height"]): for col in range(start_col, end_col): tile_id = map_data["solid_tiles"].get((col, row)) if tile_id: screen.blit(tileset[tile_id], (col * TILE_SIZE - camera_x, row * TILE_SIZE))这里的camera_x负责把世界坐标换算成屏幕坐标。玩家向右移动时camera_x增加，瓦片绘制时减去camera_x，视觉上就是镜头跟随。地图高度一般只有屏幕两倍高，所以垂直方向不用裁剪，直接全画。
4.2 角色与瓦片的碰撞解析顺序
横版游戏里最经典的物理问题是角色掉进砖缝。原因是同时解析 X 轴和 Y 轴碰撞时，角色矩形同时压到两个瓦片边缘，位置校正产生冲突。程序包里的做法是分轴解析：先移动 X 轴、检测碰撞并反弹；再移动 Y 轴、检测碰撞并落地。
def move_and_collide(entity, colliders, dt): # X 轴移动与碰撞 entity.rect.x += entity.velocity.x * dt for tile_rect in colliders: if entity.rect.colliderect(tile_rect): if entity.velocity.x > 0: entity.rect.right = tile_rect.left elif entity.velocity.x < 0: entity.rect.left = tile_rect.right entity.velocity.x = 0 # Y 轴移动与碰撞 entity.rect.y += entity.velocity.y * dt for tile_rect in colliders: if entity.rect.colliderect(tile_rect): if entity.velocity.y > 0: entity.rect.bottom = tile_rect.top entity.on_ground = True elif entity.velocity.y < 0: entity.rect.top = tile_rect.bottom entity.velocity.y = 0注意on_ground标志：只有在 Y 轴向下碰撞时才设为True，这决定了角色能否起跳。很多 bug 的根源在于跳跃键检测时直接检查velocity.y == 0，但角色在平台边缘下落时velocity.y可能恰好为 0，导致空中跳了一下。
4.3 镜头边界、出生点与关卡切换触发
魂斗罗关卡有明确长度，镜头不能无限往右滚。程序包里通常维护一个Camera类，x的取值范围是 0 到map_width * TILE_SIZE - screen_width。低于 0 截断在 0，高于上限截断在上限。
class Camera: def __init__(self, map_width_pixels, screen_width): self.x = 0 self.max_x = map_width_pixels - screen_width self.screen_width = screen_width def update(self, target_x): # 跟随玩家，但限制在关卡边界内 self.x = max(0, min(target_x - self.screen_width // 3, self.max_x))镜头跟随点不是玩家屏幕中心，而是放在屏幕左侧 1/3 处，这样玩家能看到右侧更远的敌人和地形。关卡切换的触发方式有三种：走到地图末端的出口标记、击杀特定敌人掉落旗子、到达某个坐标范围。程序包里最常见的是用碰撞盒定位“过关区域”，角色hit_rect与之重叠后加载下一关。
if player.hit_rect.colliderect(level.exit_zone): current_level_index += 1 init_level(levels[current_level_index]) player.rect.topleft = levels[current_level_index].spawn_point切关时要重置的不只是玩家位置，还包括敌人列表、子弹列表、镜头偏移以及计时器。直接重新调用关卡初始化函数比手动清场干净得多。
5. 敌人与武器的对象池设计
5.1 子弹缓存池的必要性
Python 程序包里性能最大短板不是绘制，而是对象频繁创建和销毁导致的内存分配和 GC 停顿。玩家连续开火时，如果每发子弹Bullet()生成一个实例，打空一梭子后所有子弹kill()，Pygame 的 sprite group 内部列表不断增删，垃圾回收器压力很大。
对象池的思路是预分配固定数量（比如 128 个）的子弹实例，用active标志区分是否在场。发射时从池中取一个active=False的实例，碰撞或出界后置回active=False，实例本身不销毁。
class BulletPool: def __init__(self, size=128): self.pool = [Bullet() for _ in range(size)] def fire(self, x, y, vx, vy): for bullet in self.pool: if not bullet.active: bullet.reset(x, y, vx, vy) return bullet return None # 池满，本次射击不生效 def update(self, dt, colliders): for bullet in self.pool: if bullet.active: bullet.update(dt) if bullet.rect.right < 0 or bullet.rect.left > MAP_WIDTH_PX: bullet.active = False # 碰撞检测 for tile in colliders: if bullet.rect.colliderect(tile): bullet.active = False breakpool列表在初始化时创建全部对象，后续循环只做遍历和标志判断。这种做法牺牲了一点代码优雅性，换来的帧率稳定性非常明显。子弹数量少时无所谓，但魂斗罗里一排炮台齐射时对象数很容易过百，池化能有效避免帧生成时间的尖刺。
5.2 敌人的状态与行为模式
魂斗罗敌人分三类：固定炮台、巡逻兵、Boss。每类敌人可以用状态机管理行为。炮台只有休眠和射击两态；巡逻兵有巡逻、追击、攻击三态；Boss 按血量比例切状态。程序包里的常见设计是把行为函数作为属性传入，而不是为每个敌种写一个子类。
class Enemy(pygame.sprite.Sprite): def __init__(self, x, y, behavior): super().__init__() self.behavior = behavior # 传入行为函数 self.health = behavior.max_health self.state = "idle" self.rect = pygame.Rect(x, y, 32, 32) def update(self, dt, player_rect, bullets): # 行为函数决定敌人该干什么 self.state = self.behavior.act(self, dt, player_rect) # 被子弹命中检测 for bullet in bullets: if bullet.active and self.rect.colliderect(bullet.rect): self.health -= bullet.damage bullet.active = False if self.health <= 0: self.kill()行为函数是一个接收enemy、dt、player_rect参数并返回新状态的函数，这样新增敌人种类只需要写一个新的行为函数，不用改Enemy类的代码。巡逻行为里有一个容易犯的错误：方向切换时检测到前方 1 格有障碍物，但撞到的是低于角色膝盖的小台阶，原版魂斗罗敌人能自动上下台阶。处理方案是检测障碍物时用敌人前方的两个探测点，一个在脚下、一个在膝盖高度，只有上方有碰撞才转向。
5.3 掉落物管理
拾取武器、炸弹、生命值补充需要使用独立的掉落物逻辑。掉落物和子弹不同，它不参与碰撞判定，而是用distance < 阈值判断吸引或拾取。常见的 Python 实现是把掉落物放进独立 sprite group，拾取检测用pygame.sprite.spritecollide配合自定义collided回调。
def pickup_collide(player, pickup): # 缩小拾取判定范围，避免隔空拿道具 player_core = player.hit_rect.inflate(-10, -10) return player_core.colliderect(pickup.rect) pickups_hit = pygame.sprite.spritecollide( player, pickup_group, True, collided=pickup_collide ) for pickup in pickups_hit: if pickup.type == "weapon": player.weapon = Weapons.MACHINE_GUN elif pickup.type == "life": player.lives += 1pickup_collide里的inflate(-10, -10)把玩家的拾取判定矩形向内缩小 5 像素每边，这样玩家必须真正走到道具附近才能捡到，而不会因为碰撞盒偏大而隔墙拾取。
6. 关卡 Replay 与调试辅助工具
6.1 录制与回放输入序列
调试一个横版射击关卡，最烦的是每次都要手动跳到某个位置才能复现 bug。程序包里可以加一个简单的输入录制功能：每一帧把按键状态和鼠标事件追加到列表，回放时按帧索引取出的数据喂给事件队列。
class InputRecorder: def __init__(self): self.frames = [] # 每帧的按键状态快照 self.recording = False self.replaying = False self.replay_index = 0 def record_frame(self, keys): if self.recording: state = tuple(keys) # 按键状态不可变快照 self.frames.append(state) def get_replay_keys(self, current_keys): if self.replaying: if self.replay_index < len(self.frames): keys = self.frames[self.replay_index] self.replay_index += 1 return keys else: self.replaying = False return current_keystuple(keys)是关键：pygame.key.get_pressed()返回的是可变的 ScancodeWrapper，直接存引用会覆盖掉上一帧的数据。转成 tuple 后每帧的键位状态就固定了。回放时把录制数据替换get_pressed()的结果，就能精确复现同一段操作。这个工具对于验证碰撞修复、或者对比不同参数的跳跃手感极其实用。
6.2 碰撞盒可视化与事件日志
调试碰撞问题，最直接的手段是把所有hit_rect画在屏幕上。可以定义一个调试绘制常量，为True时不加载背景贴图，只渲染矩形框和网格线。
DEBUG_HITBOX = True def draw_debug(screen, sprites, camera_x): for sprite in sprites: hit_rect = sprite.hit_rect.move(-camera_x, 0) pygame.draw.rect(screen, (255, 0, 0), hit_rect, 2) # 底部地面判定线 ground_y = hit_rect.bottom pygame.draw.line(screen, (0, 255, 0), (hit_rect.left, ground_y), (hit_rect.right, ground_y), 1)红色矩形是实际判定区域，底部绿色横线是on_ground的判定点。看回放录像时重点观察：角色跳跃到最高点时绿色横线是否低于平台顶部 1 像素导致落地误判；斜向射击时子弹碰撞盒是否超出视觉模型。把DEBUG_HITBOX做成命令行参数而不是硬编码，方便运行时切换：
python main.py --debug-hitbox --replay level3.pklPygame 的画线函数draw.rect的最后一个参数是线条宽度，为 0 表示填充整个矩形，调试时用大于 0 的数值画边框。线条宽度大于 2 时某些驱动会有锯齿，推荐固定用 2 或 1。
6.3 用性能计数器定位卡顿点
Python 游戏最常见的卡顿来源有三种：全地图渲染、大规模碰撞检测、音频加载。定位方法是使用time.perf_counter()给关键函数计时，输出耗时排名前五的函数，而不是靠猜。
import time def profile_func(func, *args, **kwargs): start = time.perf_counter() result = func(*args, **kwargs) elapsed_ms = (time.perf_counter() - start) * 1000 if elapsed_ms > 1.0: # 只打印超过 1ms 的热点 print(f"[profile] {func.__name__}: {elapsed_ms:.2f}ms") return result如果发现渲染函数耗时超过 5ms（60 FPS 下总帧预算约 16.6ms），说明可视区域瓦片裁剪没生效或者贴图在每帧被重复转换格式。检查是否在加载后调用了convert_alpha()，未转换的 PNG 每帧blit时都要做像素格式转换，开销翻倍。BulletPool.update耗时过高则检查是否把无效子弹也进行矩形碰撞检测，一个if bullet.active的提前 continue 能省掉大量无效计算。
本文还有配套的精品资源，点击获取
