2dx

2dx 是一个 Codex 插件，用于在用户指定目录中生成可继续开发的 2D 游戏模板项目。Codex skills 负责把游戏概念转成设计、素材、基础场景和核心运行所需的结构化文件，并按用户选定的引擎类型组织项目；本地 Web 面板只读取落盘 artifacts，用于预览、QA 证据、试玩证据、设置和模板状态展示。

项目定位

2dx 的核心产物是“按选定引擎类型组织好的 2D 游戏模板项目”，不是一次性生成完整可发行游戏。一个项目只面向一种引擎，engineTarget 在 Codex 对话、项目创建、brief 和设计阶段前置确定，并持续约束后续素材、场景、runtime metadata 和 starter 项目结构；模板结构不是最后一步才生成，而是从项目初始化后就作为后续生产的组织方式。

目标产物不只是 map.png、单张角色图或离散素材包，而是一套可以继续迭代成完整游戏的项目目录：

• 项目设计数据包含 world bible、art direction、game design、production plan 和 asset backlog
• 地图由 Codex 通过 $2dx-production-orchestrator 调用 $generate2dmap 生成，并以 map-package.json 作为工程入口
• 2dx 直接消费 generate2dmap 的原生 preview / base / objects / props / collision / zones / scene hooks 等产物，不再维护旧的 blueprint-first 地图流水线
• 场景详情保留 Access Point Editor 与 Region / Element Bounds Editor，修正结果写入 scene revision，不再回写地图 edited outputs
• 角色包含设定板、设定稿、方向/装备 reference、sprites/<action>/sprite-action.json、透明 spritesheet、sprite visual review 和可选 portrait/emotion 图片集
• 道具、物品、特效和 UI 由 $2dx-production-orchestrator 直接路由到底层 $generate2dmap / $generate2dsprite，再包装成 2dx runtime/review artifacts
• 基础场景包含 scene package、角色/出生点/交互物 placement、access points、scene lifecycle、quest/dialogue/trigger 种子和 preview/playtest evidence
• 核心运行材料包含 runtime manifest、scene/gameplay 数据、基础 controller/camera、scene loading、trigger/dialogue runtime 和目标引擎适配文件
• 项目创建和 brief/design 阶段由 Codex 对话确定 gameProfile、engineTarget 和 templateLevel；Web 面板只展示这些状态，不承担生产选择入口
• production plan 和 asset backlog 会继承目标引擎信息，后续素材从一开始就按目标引擎项目会消费的 runtime paths、metadata、collision、anchor、cue 和 UI/audio 约束组织
• Web 面板是 read-only data surface：可以导航、筛选、查看素材、试玩预览和刷新只读数据；创建/登记项目、修改设置、验收、修复、重生成和模板推进都必须从 Codex 对话触发
• 项目工作区同时保留 review 结果、生成日志和 QA 证据，便于后续继续由 Codex 或人工开发迭代

完整任务逻辑、经济系统、战斗、复杂 UI 流程、存档、平衡性和发布构建，仍应在这个模板项目之上继续开发。

项目模板产物

2dx 的交付目标由项目级字段控制：

• gameProfile：游戏形态，例如 topdown_adventure、topdown_3_4_adventure、isometric_adventure、side_scroller、card_battler
• engineTarget：下游目标，例如 generic、phaser 或 godot
• templateLevel：交付深度，例如 runtime_package、starter_project、starter_project_with_modules

这些字段由 Codex 生产对话询问或从用户描述中推断，并在项目 shell / brief / design 阶段写入 project.json、production-state.json 和项目 runtime metadata。面板不提供这些选项。用户未特别指定引擎时默认使用 phaser，未特别指定 templateLevel 时默认使用 starter_project；只有明确要求引擎中立数据时才使用 generic + runtime_package。

generic + runtime_package 会在项目目录中组织一套干净的 runtime 数据：

• runtime/manifest.json：运行时入口 manifest，全部路径为项目相对路径
• runtime/scenes/ 和 runtime/gameplay/：场景包与玩法脚本
• runtime/assets.json：地图、角色和文件索引
• runtime/media/：可直接交给下游引擎加载的地图、角色、道具、特效、UI 和音频文件

phaser + starter_project 会在项目目录中组织可运行的 Vite + Phaser 模板项目，并直接消费同一套 runtime metadata 和素材文件。

godot + starter_project 会复用同一套 runtime metadata，并通过 Godot adapter 生成 project.godot、scene 和 GDScript runtime loader。

模板目录、runtime manifest、Phaser/Godot adapter 和 validation 契约已经落入实现；后续流程、上下文和 readiness 优化方向见 Flow And Readiness Optimization。

角色生产使用完整 reference package 与 action sprite package 契约。角色资产在 2dx 工作区中必须包含：

design-board.png
references/front.png
references/side.png
references/back.png
references/equipment.png
character-design.json
design-board-review.json
sprites/<action>/sprite-action.json
sprites/<action>/sprite-review.json
sprites/<action>/sheet-transparent.png
sprites/<action>/frames/*.png

角色动作规划、prompt 编写、生图、sprite processor 编排和修复循环由 Codex 通过 $2dx-production-orchestrator、$2dx-character-design、$2dx-character-emotion 和 $generate2dsprite 推进。2dx 只消费写回的 artifacts，并在 preview、质量证据和项目模板 readiness 中校验这些文件。运行时模板只消费经过清理的 sprite-action.json、透明 spritesheet、必要 frame PNG 和 portrait PNG。

references/front.png、references/side.png 和 references/back.png 由设定板三视图区裁剪生成。默认使用 deterministic 前景 bbox 裁剪；如果裁剪诊断发现贴边或异常尺寸，并且 ~/.2dx/config.json 中配置了 vision.adapter: "custom"、vision.custom.apiKey 和 vision.custom.model，会启用 vision fallback 只返回方向 bbox，实际裁剪、clamp 和 manifest 记录仍由本地流程完成。

当角色请求 portraitRequired 时，生成器会额外产出 portrait-set.json 和 portraits/*.png。portrait-set.json 中的图片引用会被 template validation 校验，缺图会报错。

Phaser 模板项目会读取 sprite-action.json，按每个 action spritesheet 创建动画，并使用 scene package 中的 origin、collision、交互半径和排序信息。进入对应项目目录后执行：

npm install
npm run dev

可本地同步并校验某个项目模板。这里的 materialize:template 不是后置导出或最后才开始组织引擎项目，而是把当前已验收 artifacts 刷新到既定的 runtime/ 和目标引擎 starter 文件中：

npm run materialize:template -- <projectId>
npm run inspect:readiness -- <projectId>
npm run validate:template -- <projectId>
npm run validate:adapter -- <projectId>

运行方式

面向普通使用者，推荐通过 npm 安装 2dx Codex 插件：

当前已发布的 npm 包是 @shawnxie666/[email protected]。

npm install -g @shawnxie666/2dx
2dx codex install
2dx config init

如果需要固定到当前版本，可使用：

npm install -g @shawnxie666/[email protected]

2dx codex install 会把插件安装到用户目录并注册到 Codex：

~/.2dx/codex-plugin/
~/.codex/plugins/2dx
~/.codex/config.toml

2dx config init 会创建用户级 JSON 配置文件：

~/.2dx/config.json

如果只使用 Codex Desktop 内置 $imagegen / image_gen，可以不填写图片 API key。安装或修改插件 metadata 后需要重启 Codex Desktop。

源码开发时使用：

npm install
npm run build
npm run codex:install-plugin

安装插件后，所有生产交互在 Codex Desktop 对话中完成。进入一个希望作为项目工作区的空目录，直接描述项目即可，例如：

用 2dx 创建 2D 游戏模板项目：勇者冒险村，放置类游戏，玩家在看板娘处发布任务，勇者接任务后去地下城完成。像素风，可爱女孩子角色。目标用 Phaser，先生成 brief 和项目设计。

如果当前目录没有 project.json，2dx-production-orchestrator 会先在当前目录初始化 2dx 项目壳，再继续生成 brief、设计和后续素材批次。后续可以继续在同一目录中说：

继续推进这个 2dx 项目，先生成主地图和主角色设定稿。

推荐的对话推进方式如下。每一步完成后，Codex 会给出下一句可直接继续的指令；用户不需要记住内部 skill 名称或去面板点击生产按钮。

接受 brief，继续生成项目设计。
接受这个设计和素材范围，继续推进。
接受这一批，继续生成角色动作。
接受这一批，继续生成核心交互素材和反馈素材。
接受这一批，组装场景并生成玩法脚本。
接受场景和玩法脚本，检查预览、QA 和模板 readiness。
预览已接受，刷新并校验当前引擎模板项目。

在项目接近可用时，Codex 会按当前 engineTarget 和 templateLevel 刷新既定模板结构：先确认 active scene、gameplay script、accepted preview 和 QA decision，再运行模板同步与校验。materialize:template 只刷新 runtime/ 和目标引擎 starter 文件，不会把项目改成另一个引擎，也不会生成独立导出包。

npm run dev 只用于启动本地 2dx Web 面板服务。面板是查看 artifacts、素材、QA 证据、预览、设置和项目模板状态的只读辅助界面，不是创建项目或推进生产的入口。需要查看当前项目时，可在项目目录中让 Codex 使用 $2dx-panel 打开面板。

npm run codex:install-plugin 等价于从源码运行 2dx codex install。安装器会生成用户级插件外壳，而不是要求 Codex 直接依赖源码仓库路径。插件按 Codex marketplace 结构登记，manifest 位于 plugins/2dx/.codex-plugin/plugin.json。

如需检查或修复本地 skill 软链，可使用维护命令：

npm run codex:install-skills

正常对话式使用不应要求用户先手工执行这个命令；2dx codex install 会准备底层 generate2dmap / generate2dsprite 缓存并暴露给插件。项目可以放在任意目录。面板 registry 只记录明确登记过、且包含 project.json 的项目目录。

模型配置

默认未配置 image provider 时，2dx 会使用 Codex Desktop 内置 $imagegen / image_gen 能力生成可见素材，不需要配置图片 API key。

如果需要改用外部 image provider，可编辑 ~/.2dx/config.json。rightcodes 示例：

{
  "image": {
    "adapter": "rightcodes",
    "rightcodes": {
      "baseUrl": "https://www.right.codes/draw/v1",
      "apiKey": "",
      "model": "google/gemini-3.1-flash-image-preview",
      "timeoutMs": 180000,
      "maxRetries": 2
    }
  }
}

OpenAI 官方 Images API 示例：

{
  "image": {
    "adapter": "openai-official",
    "openai": {
      "apiKey": "",
      "baseUrl": "https://api.openai.com/v1",
      "model": "gpt-image-1.5",
      "quality": "auto",
      "background": "auto",
      "timeoutMs": 180000
    }
  }
}

视觉 Review 默认使用 Codex Desktop 当前可用视觉能力。需要自定义视觉模型时再配置：

{
  "vision": {
    "adapter": "custom",
    "custom": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "",
      "model": "google/gemini-3.1-pro-preview",
      "timeoutMs": 180000,
      "imageMaxWidth": "",
      "imageQuality": "",
      "temperature": 0
    }
  }
}

创建项目时只会创建轻量级 project shell。后续生产在 Codex Desktop 对话中由 2dx-production-orchestrator 推进；通常不需要用户显式输入 skill 名称，只要在项目目录中描述“用 2dx 创建/继续/生成素材”。面板不会启动外部 agent bridge，不保存 Codex runs，不承担写状态的生产控制，只消费已经写入磁盘的 artifacts。