architecture.md

架构概览

分层结构

┌─────────────────────────────────────────────────────────────┐
│                        入口 main.py                          │
├──────────────┬──────────────┬──────────────┬────────────────┤
│   src.core   │ src.resource │  src.game    │    src.ui      │
│  配置 / 碰撞  │  纹理 / 精灵  │  游戏逻辑     │  HUD / 菜单    │
├──────────────┴──────────────┴──────┬───────┴────────────────┤
│                              src.render                      │
│                             渲染管线                          │
├──────────────────────────────────────────────────────────────┤
│                        game_content/                          │
│                    关卡内容（弹幕脚本）                         │
└──────────────────────────────────────────────────────────────┘

引擎和内容通过 StageContext 桥接——内容脚本只能通过 ctx 调用引擎能力，不能直接 import 引擎内部模块。

模块说明

src/core — 基础设施

模块	职责
config.py	游戏配置常量（分辨率、游戏区域、帧率）
collision.py	碰撞检测（Numba JIT 加速，支持判定点和擦弹）
interfaces.py	核心接口定义
sprite_registry.py	全局精灵注册表

src/resource — 资源管理

模块	职责
texture_asset.py	纹理图集加载、精灵定义、UV 坐标计算
unified_texture.py	统一纹理管理器（跨图集查找精灵）
sprite/	精灵管理
asset_manager.py	资产加载和缓存

src/game — 游戏逻辑

模块	职责
bullet/optimized_pool.py	高性能子弹池（结构化 NumPy 数组 + Numba）
player/	玩家系统（移动、射击、动画、子机）
stage/	关卡系统核心——下面单独说
boss/	Boss 管理器
laser.py	激光系统（直线 / 曲线，池化管理）
item.py	道具系统
audio.py	音频系统（双层：全局 + 关卡私有）
background_render/	3D 背景渲染（透视投影、雾效）

src/game/stage — 关卡系统（核心）

这是内容开发者最需要理解的部分：

模块	职责
stage_base.py	StageScript 基类——关卡主脚本继承它
context.py	StageContext——引擎与内容的桥梁
spellcard.py	SpellCard / NonSpell 基类
wave_base.py	Wave 基类
enemy_script.py	EnemyScript 基类
boss_base.py	BossBase——管理符卡阶段序列
preset_enemy.py	预设敌人系统（JSON 配置驱动）
dialog_manager.py	对话管理
practice.py	练习模式

src/render — 渲染

模块	职责
renderer.py	主渲染器（协调所有子渲染器）
optimized_bullet_renderer.py	子弹批量实例化渲染
laser_renderer.py	激光渲染（直线/曲线几何体构建）
player_renderer.py	玩家精灵渲染
item_renderer.py	道具渲染

src/ui — 界面

模块	职责
hud.py	HUD（残机、符卡、分数、Power）
bitmap_font.py	位图字体渲染
dialog_gl_renderer.py	对话框 OpenGL 渲染
main_menu_renderer.py	主菜单
loading_renderer.py	加载画面

数据流

一帧的执行顺序

输入处理 → 玩家更新 → 关卡协程推进 → 子弹更新 → 激光更新 → 碰撞检测 → 道具更新 → 渲染

关卡系统内部

StageScript.run()
  │
  ├── run_wave(WaveClass)        → 实例化 Wave，执行其 run() 协程
  │
  ├── play_dialogue([...])       → 阻塞式对话，完成后继续
  │
  └── run_boss(BossDef)          → 进入 Boss 战
        │
        └── 按顺序执行 phases:
              ├── NonSpell.run()   → 非符弹幕循环
              └── SpellCard.run()  → 符卡弹幕循环

每个协程（run()）内部通过 await self.wait(N) 控制时间，引擎每帧推进一步。

子弹生命周期

脚本调用 self.fire() → StageContext → BulletPool.spawn()
                                          │
                                    结构化 NumPy 数组
                                    (x, y, speed, angle, ...)
                                          │
                              每帧 Numba JIT 批量更新位置
                                          │
                              出界 / 碰撞 → 标记为 dead → 回收槽位

StageContext：引擎与内容的桥梁

内容脚本（SpellCard、Wave、EnemyScript）不直接操作 BulletPool 或 Player。 它们通过 self.fire() / self.fire_circle() 等方法，最终委托给 StageContext，由 Context 调用引擎内部 API。

内容脚本                    StageContext                     引擎
──────────                 ────────────                    ──────
self.fire(...)         →   ctx.create_bullet(...)      →   BulletPool.spawn()
self.fire_circle(...)  →   ctx.create_bullet() × N     →   BulletPool.spawn() × N
self.play_se(...)      →   ctx.audio_manager.play_se() →   AudioManager
self.clear_bullets()   →   ctx.clear_bullets()         →   BulletPool.clear()
self.boss.move_to(...) →   BossProxy.move_to()         →   协程驱动的平滑移动

这样做的好处：

• 内容脚本不依赖引擎实现细节
• 引擎内部重构不影响已有关卡
• 可以对 Context 做 mock 进行单元测试

渲染管线

渲染按层级从后到前：

背景层 → 敌人层 → 敌弹层 → 激光层 → 自机弹层 → 自机层 → 道具层 → UI 层 → 对话层

子弹渲染使用 OpenGL 实例化绘制（instanced rendering），一次 draw call 绘制所有同类型子弹。

音频系统

双层查找机制：

play_se("shoot")
    │
    ├── 先找 StageAudioBank（关卡私有，可选）
    │     └── game_content/stages/stageN/audio/se/
    │
    └── 再找 GameAudioBank（全局）
          └── assets/audio/se/

关卡私有音效可以覆盖全局同名音效。BGM 同理。

激光系统

两种激光类型：

类型	说明
直线激光 Laser	三段式（头/身/尾），支持展开→持续→收缩动画
曲线激光 BentLaser	沿路径弯曲，记录历史位置形成轨迹

通过 LaserPool 统一管理，渲染由 LaserRenderer 处理，支持 16 种预设颜色。