春节合成闯关 是一款基于 HTML5 Canvas 和 原生 JavaScript 开发的横版合成类竞技游戏。玩家操控主角小马，在富有春节氛围的场景中通过碰撞同等级或低等级的马匹进行俘获与进化，最终组建强大的马队，击退年兽，保卫村庄。

本项目采用现代游戏开发架构（ECS），在保证代码高度解耦的同时，实现了极高的运行效率和扩展性。

• 合成进化机制：11 个等级的进化链条，每一级都有专属的外观、颜色和能力加成。
• 多样化关卡设计：
  • 得分模式：达到指定团队规模或积分。
  • 收集模式：寻找散落在地图上的“福”字、红包、灯笼等春节物资。
  • 生存模式：在密集的障碍物和陷阱中坚持指定时间。
  • Boss 战模式：终极决战，使用鞭炮道具击败年兽（Nian）。
• 动态环境系统：包括冰面（物理惯性）、大雾（视距受限）、暴风雪（随机风力干扰）等挑战。
• 实时性能监控：内置 Profiler 工具，实时展示 FPS、DrawCalls、实体数量等关键性能指标。
• 完善的存档系统：基于 LocalStorage 的本地保存机制，支持关卡进度、道具库存及能力升级的持久化。

---

项目核心逻辑采用 ECS (Entity Component System) 架构，实现了数据与逻辑的彻底分离。

• Entity (实体)：轻量级容器，通过唯一的 UUID 标识。
• Component (组件)：纯数据结构，如 Transform, Physics, Health, Sprite, AI, Collision。
• System (系统)：负责处理具有特定组件组合的实体。
  • AISystem: 处理敌人巡逻与追逐逻辑。
  • MovementSystem: 负责物理位移、边界检查。
  • CollisionSystem: 基于空间索引的快速碰撞检测。
  • RenderSystem: 处理批量渲染。
  • ParticleSystem: 管理粒子特效。

• Texture Atlas (纹理图集)：在初始化阶段将所有程序化生成的 Canvas 纹理合并至一张 2048x2048 的图集中，渲染时只需单次纹理绑定，极大降低了 DrawCalls。
• 程序化美术资源：所有角色与道具均通过 Canvas API 动态生成，支持 PBR 式的光晕（Aura）和材质效果，减少了美术资源包的体积。

• Spatial Grid (空间网格)：将游戏世界划分为网格，仅对相邻单元格的实体进行碰撞检测，将 O(n²) 的复杂度降低至接近 O(n)。
• Object Pooling (对象池)：针对粒子、飘字（Toast）、敌人等高频创建/销毁的实体进行复用，避免垃圾回收造成的卡顿。

---

1. 克隆或下载本项目到本地。
2. 本项目为纯前端应用，无需安装复杂的服务器环境。
3. 直接使用现代浏览器打开根目录下的 index.html 即可运行。

为了获得最佳开发体验（如自动刷新、路径解析），建议使用以下工具之一：

• VS Code + Live Server 扩展。
• Python: python -m http.server 8000。
• Node.js: npx serve .。

---

核心配置文件位于 constants.js。

参数名	说明	默认值
PLAYER_SPEED	玩家基础移动速度	200
ENEMY_SPEED	普通敌人移动速度	100
SPAWN_INTERVAL	敌人生成基础间隔 (ms)	2000
MAX_ENEMIES	同屏最大敌人数量	15
NIAN_MAX_HP	年兽最大生命值	12
RADIUS_PLAYER	玩家碰撞半径	25
ATLAS_SIZE	纹理图集尺寸	2048

---

spring-festival-game/
├── index.html          # 游戏入口，UI 结构定义
├── style.css           # 游戏界面样式与动画
├── js/
│   ├── ecs.js          # ECS 核心框架类定义
│   ├── ecs_systems.js  # 所有的 ECS 系统实现 (AI, Render, etc.)
│   ├── entities.js     # 组件定义与实体工厂 (Pony, Nian, Item)
│   ├── assets.js       # 资源加载器与纹理图集生成逻辑
│   ├── constants.js    # 全局平衡参数配置
│   ├── game.js         # 游戏核心类，管理生命周期与系统调度
│   ├── level_config.js # 11 个关卡的详细数据配置
│   ├── spatial_grid.js # 空间索引优化算法
│   ├── item_system.js  # 道具触发逻辑与策略
│   ├── event_system.js # 天气系统与动态难度调整
│   ├── profiler.js     # 性能剖析 HUD 工具
│   ├── save_manager.js # 存档与排行榜管理
│   ├── tests.js        # 自动化测试套件
│   └── main.js         # 脚本启动点

---

• startGame(mode): 启动指定模式（STORY/ENDLESS）。
• addEntity(entity): 向 ECS 系统注册实体。
• removeEntity(entity): 销毁实体并从系统中注销。
• handleCollision(other): 全局碰撞分发器。

• init(): 初始化资源并生成图集。
• get(key): 获取指定资源的 Canvas 缓存。
• getUV(key): 获取资源在图集中的 UV 坐标。

---

本项目内置了自动化测试套件 tests.js。

• 运行方式：游戏启动后，在浏览器控制台查看 [PASS] 或 [FAIL] 日志。
• 测试覆盖：资源完整性校验、ECS 系统初始化、对象池压力测试（100 个实体并发）、启动稳定性测试（10 次连续启动）。

1. 组件化原则：严禁在实体类中直接编写复杂逻辑，逻辑应收敛于 System。
2. 性能意识：避免在 update 或 draw 循环中进行 DOM 操作或创建新对象。
3. 命名约定：组件类以 Component 结尾，系统类以 System 结尾。

---

Q: 游戏加载后黑屏或资源缺失？ A: 请确保浏览器支持 HTML5 Canvas 且未开启极高强度的隐私拦截脚本。查看控制台输出，确认 AssetManager 是否初始化成功。

Q: 如何重置存档？ A: 在游戏主菜单点击“重置进度”按钮，或在控制台运行 localStorage.clear(); location.reload();。

Q: 帧率不稳或卡顿？ A: 开启左上角的 Profiler 查看 Jitter 值。如果实体数量过多，建议在 constants.js 中调低 MAX_ENEMIES。

---

• 重大更新：重构核心架构为 ECS 模式。
• 优化：引入 Texture Atlas 批量渲染。
• 功能：新增 Profiler 性能分析工具与自动化测试套件。

• 基础版本发布，实现核心合成玩法。

---

本项目遵循 MIT License。

Copyright (c) 2021-2026 合肥市小桂子网络科技有限公司