NES Game Creator — 红白机游戏生成器 v3.0

使用 HTML5 Canvas + 面向对象 ES6 JavaScript 架构，根据用户自然语言描述生成完整可玩的 NES/FC 风格复古游戏。输出单个 HTML 文件，可在任何现代浏览器中直接运行。

When to Use

当用户满足以下任意条件时激活本技能：

• 要求创建复古游戏、NES 游戏、FC 游戏、红白机游戏或 8-bit 风格游戏
• 描述了一个游戏概念并希望得到可运行的结果
• 提到经典游戏名（马里奥、魂斗罗、坦克大战、双截龙、赤色要塞、冒险岛、炸弹人等）作为灵感
• 要求"做一个游戏"且带有像素或复古风格

项目结构

nes-game-creator/
├── SKILL.md                          # 技能说明（本文件）
├── assets/
│   └── template.html                 # 完整游戏模板（引擎 + 占位符，生成时内联为单文件）
├── scripts/                          # 引擎源码模块（按职责拆分，供参考和维护）
│   ├── nes-constants.js              # NES 常量、调色板、Vec2 向量工具
│   ├── input-manager.js              # InputManager 输入管理器
│   ├── renderer.js                   # Renderer 像素渲染器
│   ├── audio-manager.js              # AudioManager 音效管理器
│   ├── music-player.js               # MusicPlayer BGM 播放器 + NOTE/SONGS 预设乐曲库
│   ├── game-systems.js               # ObjectPool、SpriteAnimator、ParticleSystem、Camera、Tilemap、Physics、TimerManager、TransitionManager、StateMachine
│   └── engine.js                     # NESEngine 引擎核心 + 全局快捷引用
└── references/                       # 参考文档
    ├── engine_api.md                 # 引擎完整 API 文档
    └── nes_design_guide.md           # NES 游戏设计规范

scripts/ 与 template.html 的关系：

• scripts/ 下的 7 个 JS 文件是引擎源码的模块化拆分，按职责分离，便于阅读、维护和理解各子系统
• template.html 是这些模块内联合并后的完整模板，用于最终游戏生成
• 生成游戏时仍使用 template.html 作为基础，输出单个自包含 HTML 文件
• 修改引擎代码时，应同步更新 scripts/ 下对应模块和 template.html
• 加载顺序：nes-constants.js → input-manager.js → renderer.js → audio-manager.js → music-player.js → game-systems.js → engine.js

引擎架构概览

模板文件 assets/template.html 提供了一套完整的面向对象游戏引擎（源码模块化拆分于 scripts/ 目录），包含以下核心子系统：

全局快捷引用（直接使用，无需 engine. 前缀）：

• engine — 引擎实例
• input — 输入管理器
• renderer — 渲染器
• audio — 音频管理器（音效 SFX）
• music — 芯片音乐播放器（BGM）
• camera — 相机
• particles — 粒子系统
• timers — 计时器管理器
• transition — 场景过渡管理器
• SONGS — 预设乐曲库（title/stage/boss/gameOver/victory/dungeon/shop/fight/sports/town/intense/heroic/training/festival/chase）
• NOTE — MIDI 音高常量表（含完整半音 + 等音别名）
• n(note, duration, volume?) — 音符创建快捷函数

Game Creation Workflow

Step 1: 分析用户描述

从用户描述中提取：

1. 游戏类型 — 平台跳跃、射击、RPG、益智、格斗、体育等
2. 核心玩法 — 玩家做什么？目标是什么？
3. 主题/世界观 — 角色、场景、故事元素
4. 特殊机制 — 独特玩法、道具系统、关卡设计

如果描述模糊，以经典 NES 游戏为灵感做出合理的创意决策，偏向有趣和可玩性。不要过度询问。

Step 2: 设计游戏

参阅 references/nes_design_guide.md 获取 NES 技术规格、各类型游戏设计模式、视觉风格规范、精灵设计模板库、配色方案速查表、音效设计和代码架构指导。

参阅 references/engine_api.md 获取引擎所有类的完整 API 文档。

关键设计决策：

• 游戏状态流转（使用 StateMachine 管理）
• 实体继承体系（玩家、敌人、道具的类设计）
• 子弹/特效等高频对象使用 ObjectPool
• 精灵动画状态（使用 SpriteAnimator）
• 需要卷轴的游戏使用 Camera + Tilemap
• 场景切换使用 TransitionManager
• 难度曲线和计分系统
• 使用 NES_PALETTE 数组索引设计精灵

Step 3: 编写游戏代码

使用 assets/template.html 作为基础，替换 {{GAME_TITLE}} 和 {{GAME_CODE_PLACEHOLDER}}。

强制代码架构

所有生成的游戏必须使用面向对象架构。以下为必须遵守的代码结构模式：

// ─── 游戏常量 ───────────────────────
const GRAVITY = 400;        // 像素/秒²
const PLAYER_SPEED = 120;   // 像素/秒

// ─── 精灵数据 ───────────────────────
// 【重要】精灵必须有：黑色轮廓(13) + 3层明暗 + 清晰的眼睛(2×2)
const SPRITES = {
  playerIdle: [ /* 2D palette index array */ ],
  playerRun1: [ /* ... */ ],
  playerRun2: [ /* ... */ ],
  // ...
};

// ─── 实体基类 ───────────────────────
class Entity {
  constructor(x, y, w, h) {
    this.x = x; this.y = y;
    this.w = w; this.h = h;
    this.vx = 0; this.vy = 0;
    this.active = true;
  }
  update(dt) {}
  render() {}
  getBounds() { return { x: this.x, y: this.y, w: this.w, h: this.h }; }
}

// ─── 玩家类 ─────────────────────────
class Player extends Entity {
  constructor(x, y) {
    super(x, y, 14, 16);
    this.hp = 3;
    this.score = 0;
    this.facing = 1; // 1=右, -1=左
    this.onGround = false;
    this.invincible = 0;
    this.animator = new SpriteAnimator({
      idle: { frames: [SPRITES.playerIdle], speed: 0.5 },
      run:  { frames: [SPRITES.playerRun1, SPRITES.playerRun2], speed: 0.15 },
      jump: { frames: [SPRITES.playerJump], speed: 1 },
    });
  }
  update(dt) {
    // 输入处理
    this.vx = input.dirX * PLAYER_SPEED;
    if (this.vx !== 0) this.facing = this.vx > 0 ? 1 : -1;
    // 跳跃
    if (input.pressedA && this.onGround) {
      this.vy = -250;
      this.onGround = false;
      audio.sfxJump();
    }
    // 重力
    this.vy += GRAVITY * dt;
    // 移动 + 碰撞
    this.x += this.vx * dt;
    this.y += this.vy * dt;
    // 动画
    if (!this.onGround) this.animator.play('jump');
    else if (this.vx !== 0) this.animator.play('run');
    else this.animator.play('idle');
    this.animator.update(dt);
    // 无敌帧
    if (this.invincible > 0) this.invincible -= dt;
  }
  render() {
    const flash = this.invincible > 0 && Math.floor(this.invincible * 8) % 2;
    renderer.drawSpriteEx(this.animator.frame, this.x, this.y, 1, this.facing < 0, {
      alpha: flash ? 0.5 : 1,
      whiteFlash: flash,
      outlineColor: '#000000',
    });
  }
  takeDamage() {
    if (this.invincible > 0) return;
    this.hp--;
    this.invincible = 1.5;
    audio.sfxHit();
    camera.startShake(0.3, 6);
  }
}

// ─── 敌人类 ─────────────────────────
class Enemy extends Entity {
  constructor(x, y, type) {
    super(x, y, 16, 16);
    this.type = type;
    this.hp = 1;
    // 状态机驱动AI...
  }
  update(dt) { /* 巡逻/追踪逻辑 */ }
  render() { /* 渲染精灵 */ }
}

// ─── 使用 StateMachine 管理游戏状态 ──
let player, enemies, score;
let blinkTimer = 0;

const game = new StateMachine({
  TITLE: {
    enter() { blinkTimer = 0; music.play(SONGS.title); },
    update(dt) {
      blinkTimer += dt;
      if (input.pressedStart) {
        audio.sfxStart();
        // 使用场景过渡效果切换
        transition.start(() => game.transition('PLAYING'), 'fade', 0.4);
      }
    },
    render() {
      renderer.clear('#000');
      renderer.drawPixelTextCenteredShadow('GAME TITLE', 80, '#F8F8F8', '#000000', 2);
      if (Math.floor(blinkTimer * 2) % 2 === 0) {
        renderer.drawPixelTextCentered('PRESS START', 160, '#F8B800');
      }
      renderer.drawScanlines();
    }
  },
  PLAYING: {
    enter() {
      player = new Player(128, 200);
      enemies = [];
      score = 0;
      music.play(SONGS.stage);
    },
    update(dt) {
      player.update(dt);
      enemies.forEach(e => e.update(dt));
      particles.update(dt);
      camera.follow(player, 8, 8);
      camera.update(dt);
      // 碰撞检测...
      if (player.hp <= 0) {
        transition.start(() => game.transition('GAME_OVER'), 'iris', 0.6, { cx: player.x, cy: player.y });
      }
    },
    render() {
      renderer.clear('#000');
      // 背景视差层
      renderer.renderBgLayers(camera);
      player.render();
      enemies.forEach(e => e.render());
      particles.render(renderer);
      // HUD — 使用像素字体
      renderer.drawPixelTextShadow(`SCORE ${score}`, 8, 8);
      renderer.drawHpBar(8, 20, 40, 4, player.hp, 3);
      renderer.drawScanlines();
    }
  },
  GAME_OVER: {
    enter() { blinkTimer = 0; music.play(SONGS.gameOver, false); },
    update(dt) {
      blinkTimer += dt;
      if (input.pressedStart) {
        transition.start(() => game.transition('TITLE'), 'fade', 0.5);
      }
    },
    render() {
      renderer.clear('#000');
      renderer.drawPixelTextCenteredShadow('GAME OVER', 100, '#F83800', '#000000', 2);
      renderer.drawPixelTextCentered(`SCORE: ${score}`, 130);
      if (Math.floor(blinkTimer * 2) % 2 === 0) {
        renderer.drawPixelTextCentered('PRESS START TO RETRY', 170, '#F8B800');
      }
      renderer.drawScanlines();
    }
  }
}, 'TITLE');

// ─── 覆写引擎主循环 ─────────────────
engine.update = (dt) => game.update(dt);
engine.render = () => game.render();

核心编码规则

1. 面向对象 — 所有游戏实体必须是 ES6 class，继承 Entity 基类
2. 组合优于继承 — 使用 SpriteAnimator、StateMachine 等组件组合行为
3. 使用引擎子系统 — 不得重新实现已提供的功能（渲染用 renderer、音效用 audio 等）
4. 对象池 — 子弹、粒子等高频创建的对象必须用 ObjectPool
5. dt 时间步进 — 所有移动/物理计算使用 dt（秒），速度单位为 像素/秒
6. NES 调色板 — 所有颜色必须来自 NES_PALETTE，不得使用任意 hex 值
7. 状态机 — 游戏状态流转通过 StateMachine 管理
8. 相机系统 — 需要卷轴的游戏使用 Camera，配合 renderer.drawSpriteCam() / renderer.fillRectCam()
9. 瓦片地图 — 关卡数据使用 Tilemap 加载，配合 Physics.resolveMapCollisionX/Y() 做碰撞解析
10. 背景音乐 — 使用 music.play(SONGS.xxx) 播放 BGM，状态切换时切换对应乐曲
11. 场景过渡 — 使用 transition.start() 实现场景切换时的渐变效果，不要直接切换

精灵设计强制规则（极重要，直接影响画面质量）

每个角色/敌人/道具精灵必须满足以下全部条件：

1. 黑色轮廓线（索引13）：精灵最外圈可见像素必须是黑色(13)，形成清晰边界
2. 3层明暗：每个物体至少使用亮色+中间色+暗色3个色阶，禁止纯色填充
3. 清晰眼睛：角色眼睛至少2×2像素，使用高对比色（白底+黑瞳）
4. Q版比例：头部占比≥身体的1/3，大头小身才有NES感
5. 配色限制：每个精灵不超过4色（不含透明-1和轮廓黑13）
6. 尺寸规范：8×8, 16×16, 16×24 等8的倍数
7. 动作帧差异：走路帧之间至少3-4个像素位置不同

精灵模板示例（16×16 高质量角色）：

// 红色帽子角色 — 注意轮廓线(13)、明暗层次、大头比例
const heroIdle = [
  [-1,-1,-1,-1,-1,13,13,13,13,13,-1,-1,-1,-1,-1,-1],
  [-1,-1,-1,-1,13,22,22,22,22,22,13,-1,-1,-1,-1,-1],
  [-1,-1,-1,13,22,22, 5, 5, 5,22,22,13,-1,-1,-1,-1],
  [-1,-1,-1,13,54,54,54,54,54,54,54,13,-1,-1,-1,-1],
  [-1,-1,13,54,54,13,48,32,54,13,48,32,13,-1,-1,-1], // 眼睛：白(48)+灰(32)
  [-1,-1,13,38,54,13,13,54,54,13,13,38,13,-1,-1,-1],
  [-1,-1,-1,13,54,54,38,38,38,54,54,13,-1,-1,-1,-1],
  [-1,-1,-1,-1,13,13,13,13,13,13,13,-1,-1,-1,-1,-1],
  [-1,-1,-1,13,17,17,22,22,22,17,17,13,-1,-1,-1,-1],
  [-1,-1,13,17,17,22,40,22,40,22,17,17,13,-1,-1,-1],
  [-1,-1,13,17,17,22,22,22,22,22,17,17,13,-1,-1,-1],
  [-1,-1,-1,13,17,17,17,17,17,17,17,13,-1,-1,-1,-1],
  [-1,-1,-1,13,17, 2,17,-1,17, 2,17,13,-1,-1,-1,-1],
  [-1,-1,-1,13, 6, 6, 6,-1, 6, 6, 6,13,-1,-1,-1,-1],
  [-1,-1,13, 6,24, 6, 6,-1, 6, 6,24, 6,13,-1,-1,-1],
  [-1,-1,-1,13,13,13,-1,-1,-1,13,13,13,-1,-1,-1,-1],
];
// 走路帧1 — 右脚前迈
const heroRun1 = [
  [-1,-1,-1,-1,-1,13,13,13,13,13,-1,-1,-1,-1,-1,-1],
  [-1,-1,-1,-1,13,22,22,22,22,22,13,-1,-1,-1,-1,-1],
  [-1,-1,-1,13,22,22, 5, 5, 5,22,22,13,-1,-1,-1,-1],
  [-1,-1,-1,13,54,54,54,54,54,54,54,13,-1,-1,-1,-1],
  [-1,-1,13,54,54,13,48,32,54,13,48,32,13,-1,-1,-1],
  [-1,-1,13,38,54,13,13,54,54,13,13,38,13,-1,-1,-1],
  [-1,-1,-1,13,54,54,38,38,38,54,54,13,-1,-1,-1,-1],
  [-1,-1,-1,-1,13,13,13,13,13,13,13,-1,-1,-1,-1,-1],
  [-1,-1,-1,13,17,17,22,22,22,17,17,13,-1,-1,-1,-1],
  [-1,-1,13,17,17,22,40,22,40,22,17,17,13,-1,-1,-1],
  [-1,-1,13,17,17,22,22,22,22,22,17,17,13,-1,-1,-1],
  [-1,-1,-1,13,17,17,17,17,17,17,17,13,-1,-1,-1,-1],
  [-1,-1,13, 6, 6,13,-1,-1,-1,13,17,17,13,-1,-1,-1], // 腿部交叉
  [-1,13, 6,24, 6,13,-1,-1,-1,-1,13, 2,17,13,-1,-1],
  [-1,-1,13,13,13,-1,-1,-1,-1,-1,-1,13, 6,13,-1,-1],
  [-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,13,13,-1,-1],
];

8×8 小型精灵模板（道具/子弹/UI元素）：

// 金币 — 旋转动画2帧
const coinFrame1 = [
  [-1,13,40,40,40,13,-1,-1],
  [13,40,56,56,40,40,13,-1], // 56=#F8D878 亮金, 40=#F8B800 金
  [13,40,56,40,40,40,13,-1],
  [13,40,40,40,40,40,13,-1],
  [13,40,40,40,40,24,13,-1], // 24=#AC7C00 暗金
  [13,40,40,40,24,24,13,-1],
  [-1,13,40,24,24,13,-1,-1],
  [-1,-1,13,13,13,-1,-1,-1],
];
// 心形（生命值图标）
const heartSprite = [
  [-1,22,22,-1,22,22,-1,-1],
  [22, 5,22,22,22, 5,22,-1], // 亮暗层次
  [22,22,22,22,22,22,22,-1],
  [22,22,22,22,22,22,22,-1],
  [-1,22,22,22,22,22,-1,-1],
  [-1,-1,22,22,22,-1,-1,-1],
  [-1,-1,-1, 5,-1,-1,-1,-1],
  [-1,-1,-1,-1,-1,-1,-1,-1],
];

NES 调色板配色方案速查

角色-红系: 亮红(22)→中红(5)→暗红(6)    轮廓(13)
角色-蓝系: 亮蓝(33)→中蓝(17)→暗蓝(2)   轮廓(13)
角色-绿系: 亮绿(41)→中绿(42)→暗绿(10)   轮廓(13)
角色-肤色: 亮肤(54)→中肤(38)→暗肤(7)    轮廓(13)
金币/道具: 亮金(56)→金(40)→暗金(24)     轮廓(13)
天空/水面: 亮天(49)→中天(33)→暗天(17)
草地/树木: 亮绿(41)→中绿(42)→暗绿(25)
砖块/地面: 亮棕(38)→中棕(7)→暗棕(8)
岩石/金属: 亮灰(32)→中灰(16)→暗灰(0)
粉色系:   亮粉(52)→中粉(36)→暗粉(4)
紫色系:   亮紫(35)→中紫(19)→暗紫(3)
橙色系:   亮橙(39)→中橙(23)→暗橙(7)
文字-白:  纯白(48) 或 亮白(32)
文字-黄:  金黄(40)
背景-黑:  纯黑(13)

Title Screen 要求

• 游戏标题使用 renderer.drawPixelTextCenteredShadow() 大号像素字体居中（带阴影更立体）
• "PRESS START" 使用 renderer.drawPixelTextCentered() 以 0.5 秒间隔闪烁
• 可选：动画背景或角色预览（标题画面应有视觉吸引力）
• 按 Enter（input.pressedStart）进入游戏，使用 transition.start() 过渡
• BGM：music.play(SONGS.title) 播放标题曲

Gameplay 要求

• 流畅 60fps，所有移动基于 dt
• 精灵绘制优先使用 renderer.drawSpriteEx() 支持描边/闪白/透明度效果
• 受伤无敌帧使用 renderer.drawSpriteEx() 的 whiteFlash + alpha 参数实现闪烁
• HUD 使用 renderer.drawPixelText() 像素字体显示分数/生命值
• 生命值条使用 renderer.drawHpBar() 或 renderer.drawHearts() 绘制
• 关键动作有音效：跳跃(sfxJump)、得分(sfxCoin)、受伤(sfxHit)、死亡(sfxDeath)、开始(sfxStart)
• BGM：music.play(SONGS.stage) 播放关卡曲；Boss 战切换 music.play(SONGS.boss)
• 难度随时间或关卡递增
• 爆炸/消灭使用 particles.emit() 发射粒子，敌人死亡使用多色爆炸
• 每帧末尾调用 renderer.drawScanlines() 添加扫描线效果
• 需要卷轴的游戏使用 renderer.addBgLayer() 注册视差背景层
• 场景切换使用 transition.start()，不要直接transition

Game Over Screen 要求

• "GAME OVER" 居中大字
• 显示最终分数
• "PRESS START TO RETRY" 闪烁
• BGM：music.play(SONGS.gameOver, false) 播放结束曲（不循环）
• 重启时完全重置所有状态

Step 4: 输出与交付

1. 输出完整游戏为单个 HTML 文件，完全自包含
2. 文件名使用描述性英文命名：如 space-shooter.html、pixel-adventure.html
3. 创建后启动本地 HTTP 服务器：

cd <project_directory> && python3 -m http.server 8080

提供 URL: http://localhost:8080/.html

Quality Checklist

交付前必须验证：

• [ ] 单个自包含 HTML 文件，无外部依赖
• [ ] NES 分辨率 (256×240) + 像素完美缩放
• [ ] 所有颜色来自 NES_PALETTE
• [ ] 像素风精灵（无平滑图形）
• [ ] 精灵有黑色轮廓线（索引13，每个角色/敌人精灵外围必须有）
• [ ] 精灵有3层明暗（亮/中/暗，禁止纯色方块）
• [ ] 精灵不是纯色方块（角色可辨识，有头部/身体/四肢等细节）
• [ ] 角色有清晰的眼睛（至少2×2像素，白底黑瞳）
• [ ] 走路动画帧有明显差异（至少3个像素变化）
• [ ] 方波音效（芯片音风格）
• [ ] BGM 背景音乐（使用 music.play() + SONGS 预设或自定义乐曲）
• [ ] 不同游戏状态播放不同 BGM（标题/关卡/Boss/结束）
• [ ] 面向对象架构（Entity 基类 + 子类）
• [ ] StateMachine 管理游戏状态
• [ ] Title 画面使用像素字体 + 闪烁 "PRESS START"
• [ ] 场景切换使用 transition.start() 过渡效果
• [ ] 可运行的游戏玩法 + 计分系统
• [ ] Game Over 画面带重试
• [ ] 键盘 + 移动端触控均可操作
• [ ] 无 console 错误
• [ ] 高频对象使用 ObjectPool
• [ ] 移动/物理基于 dt（像素/秒）
• [ ] 每帧调用 renderer.drawScanlines() 添加扫描线效果
• [ ] 文字使用 drawPixelText 系列像素字体（非系统字体）
• [ ] 背景有层次感（至少天空色 + 地面，推荐使用视差背景层）
• [ ] 敌人死亡有粒子爆炸效果（多色彩粒子+屏幕震动）

Style Guidelines

• 所有视觉必须呈现正宗 8-bit 风格，禁止渐变、抗锯齿、现代 UI 元素
• 调色板严格使用 NES_PALETTE，不得使用任意 hex 颜色
• 精灵以 2D 数组 + 调色板索引定义，最小 8×8 或 16×16 能辨识
• 精灵必须有轮廓线：角色/敌人/道具精灵的外围使用深色（索引13黑色）作为轮廓描边
• 精灵必须有3层明暗：同一物体至少使用3个色阶（亮/中/暗），避免纯色填充的扁平感
• 头部比例放大：角色头部占比≥身体的1/3（Q版大头风格更有NES经典感）
• 眼睛要清晰：至少2×2像素，使用白底(48)+黑瞳(13)，确保角色辨识度
• 动画 2-4 帧循环，通过 SpriteAnimator 管理
• 音效使用 AudioManager 的预设方法 + playTone()/playSweep()
• BGM 使用 music.play(SONGS.xxx) 播放预设乐曲，或自定义乐曲数据传入 music.play()
• 文字优先使用像素字体 drawPixelText/drawPixelTextCentered 系列方法
• 标题使用带阴影像素字体 drawPixelTextCenteredShadow() 增加立体感
• 每帧末尾调用 renderer.drawScanlines() 添加CRT扫描线效果
• 背景使用多层次设计：天空+远景+近景+地面，推荐使用 renderer.addBgLayer() 视差层
• 场景切换必须有过渡效果：使用 transition.start() 实现 fade/wipe/blinds/iris
• 整体感觉应唤起 1980-1990 年代主机游戏的怀旧感