generate2dmap

生成 2D 地图

根据请求构建所需的最小场景包，并遵循游戏的美术、摄像机、渲染器和数据规范。 背景图片不需要游戏系统；可玩的地图则需要绘画之外的明确几何结构和数据。

适用场景

• 需要碰撞和出口的可玩地图、关卡、房间组、瓦片地图、地形或道具套件。
• 视差背景、战斗、标题或剧情背景，或带有灯光和动态效果的 HD-2D 场景图。
• 需要验证、预览或导出到 Tiled、Godot 或 LDtk 的地图数据。

不适用场景

• 角色、物品和攻击特效：generate2dsprite。根据视频制作角色动作：video2dsprite。
• 用户要求使用代码绘制的瓦片、布局或视差效果：codeart2d。仅调用 API 或 CLI：generate2dmedia。

能力检查（每个会话一次）

运行 python "<skill-dir>/../generate2dmedia/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json，其中 <tools> 列出你自己的工具列表中的媒体工具（image_gen、image_edit、image_to_video）或 none。其 ROUTES 区块会显示已配置的 API 密钥（yes 或 no）、本地就绪状态和解析后的顺序。如果 encoding.stdout 失败，请设置 PYTHONUTF8=1。

美术来源

地图美术默认使用图像生成：地形和瓦片集、道具套件、HD-2D 场景图、绘制背景和视差图层。地图数据（布局、碰撞、出口、出生点）是你编写并验证的数据，不属于美术。记录每个素材的 art_source（api、host_image、existing，只有在用户要求时才用 code），并在回复中注明所用路线。用户明确指定的路线优先。

1. API，在已配置密钥时使用：OpenAI（OPENAI_API_KEY）、Google Gemini（GEMINI_API_KEY）、xAI（XAI_API_KEY）、BytePlus Seedream（ARK_API_KEY）或 fal.ai（FAL_KEY），密钥可以在环境变量中，也可以在用户配置文件中（route-media.md）。已配置的密钥即代表所有者已同意，因此无需逐次询问。
2. 本地：使用你自己的图像工具（Codex image_gen、Grok 的原生工具）；如果没有，则依次使用用户已登录的 Codex CLI 和 Grok CLI。
3. codeart2d（自动拼接瓦片、布局、风格化视差效果、环境循环动画），仅当用户明确要求代码绘制美术，或 route_media.py 输出 no-route（退出码 3）时使用。然后注明“代码绘制，无图像模型”。

每张图像都通过一个命令生成：python "<skill-dir>/../generate2dmedia/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1536x1024 --out-dir <new>；带遮罩的场景图动态效果使用 route_media.py video。每条命令都会输出一行 JSON，包含 route、artifact、sha256 和 estimateUsd。欢迎使用用户提供的现有美术素材。绝不要声称完成了实际未进行的生成；保留提示词和约定，并报告缺少的能力。

宿主环境说明

• Codex：image_gen 是你自己的图像工具；如果没有配置密钥，请使用它，并通过 view_image 查看结果。本会话生成但不在项目中的图像：python "<skill-dir>/../generate2dmedia/scripts/cli_media.py" adopt --codex-thread <thread-id> --output-dir <new>。codeart2d 和 generate2dmedia 仅在明确指定时使用：当本说明要求走这两条路线时，打开其 SKILL.md。
• **Claude Code：**没有内置图像生成器：route_media.py 会使用 API 或本地 CLI。使用 Read 查看你生成的每个 PNG（调试叠加层、预览）；使用 Bash 运行工具；<skill-dir> 为 ${CLAUDE_SKILL_DIR}。
• **Grok：**其原生图像和视频工具就是你自己的工具；请使用其真实架构。

命令

从用户的项目根目录运行每个工具，每条命令占一行：python "<skill-dir>/scripts/<tool>.py" ...。<skill-dir> 是此技能的文件夹；同级技能位于其旁边（<skill-dir>/../codeart2d）。输入和输出均保留在项目内。每个工具都会写入新的 --output-dir（或新的 --output 文件）：如果目标已存在，工具会拒绝执行；它会在目标旁暂存内容，并仅在通过检查后发布（--strict-qc / --strict 在失败时不会发布任何内容）。成功时会打印一行 JSON；出错时会打印 error: ... 并以 1 退出；用法错误时以 2 退出。需要 Python 3.10+、numpy 和 Pillow（建议安装 scipy）；场景动效需要 ffmpeg 5.1+；浏览器运行时需要 node。--help 会列出所有标志。

绘制前先规划

记录视口和逻辑分辨率、世界范围、原点、摄像机和缩放、角色比例与占地范围、路线、地标、交互、出口和渲染顺序。源像素不等于世界单位：测量返回的尺寸，并声明统一缩放比例和锚点。根据行为选择（map-strategies.md；各类型的起始值见 map-presets.md）：

• scene_mode：手绘区域、城镇或竞技场；由地形、道具和显式几何构成。
• tile_mode / grid_mode：重复或可编辑的地形，或单元格规则；由图块和图层数据构成。
• room_chunk_mode：使用共享组件包和门插槽连接房间。
• side_scroll_mode：侧视场景，或带移动几何的可玩平台关卡。
• baked_scene_mode：完整的战斗、标题或剧情画面，可选热点或受限动效。

只有在交互、景深、复用、编辑或动效有需要时，才拆分对象。像素艺术需要有意设计逻辑像素并采用最近邻缩放；HD-2D 则将像素角色与绘制背景板和光照结合。

流程

规划导航，制作美术资源和素材包，放置资源，验证数据，预览，然后导出。可游玩的地图是一个 map_bundle.v2（layered-map-contract.md）。

需求	路径
从图集提取道具	extract_prop_pack.py --input <sheet> --rows R --cols C --labels a,b --output-dir <new>（--grid-rounding nearest、--auto-boxes、--boxes-file <json> --keep-canvas、--world-scale 3/8、--suggest-footprint ellipse）；按 anchor_px 放置（prop-pack-contract.md）
地形填充、叠加层、等距或六边形、Wang 行	extract_terrain_tiles.py --strict-qc（--layer overlay、--shape iso-diamond、--wang NAME=A/B:MASKS；仅对旨在拼接的美术使用 --edge-policy seamless）
平台顶部和中段	extract_platform_strip.py --strict-qc（side-scroll-scenes.md）
仅按需生成代码绘制的自动图块	codeart2d autotile_build.py（接缝验证通过的图块集清单），然后使用导出器
仅按需生成代码绘制的可玩地图	codeart2d layout_build.py（写入 map_bundle.v2），然后运行 map_nav.py check 并使用导出器
绘制顺序、接触锚点、放置审核	compose_layered_preview.py --base <png> --placements <json> --output <png> --report <json>；使用 --bundle <map_bundle.json> --debug-overlay --audit-out <json> 时，请同时查看两者
验证可玩地图	map_bundle.py validate --bundle <b>（map_bundle.py hash 会填入 sha256），然后运行 map_nav.py check --bundle <b> --output-dir <new>（为每个相邻位置添加 --link）；检查 nav-debug.png；map_nav.py query 用于测试一个位置或移动
在地图中行走，检查所有路线	build_scene_preview.py --bundle <b> --output-dir <new> --verify；附上 scene-snapshot.json（scene-preview.md）
导出	export_tiled.py export --bundle <b> --output-dir <new>（用于 Phaser 的 --embedded-variant）；export_godot.py --bundle <b> --output-dir <new>；export_ldtk.py --bundle <b> --output-dir <new>（engine-maps.md）
房间块；横版场景语法	validate_chunks.py --chunks <json> --output-dir <new>；validate_layout.py --layout <json> --output-dir <new>
视差	validate_parallax.py --spec <plan> --report <qa.json>（声明 camera.pivot 和你要发布的 aspects）；按需生成代码绘制的图层：codeart2d parallax_build.py（parallax-backgrounds.md）
将绘画调整为游戏尺寸或地面尺寸	conform_background.py conform --mode cover 或 --mode ground-fit；要确保主体适用于每种屏幕宽高比：conform_background.py validate-crops
HD-2D 场景图	hd2d-plates.md：规划 stage.json，运行 scene_layout_guide.py，附上 guide.png 生成，然后运行 validate_stage.py --stage <json> --output-dir <new>；检查每个 layout-*.png
灯光、阴影、氛围	hd2d-presentation.md：运行 extract_scene_lights.py extract --stage <json>，整理 lights.json
场景图的夜间、打光或损坏变体	edit_locality_check.py --before <master> --after <variant> --stage <json> --edit-box <box>；未通过时重新生成
静态场景图中的水、火、雾或布料	background-scenes.md：运行 build_motion_mask.py --envelope-from <clip>、scene_motion.py build，然后对解码后的文件运行 scene_motion.py qa；按需生成代码绘制的涟漪或辉光：codeart2d ambient_bake.py
全帧场景循环	generate2dsprite assemble_frames.py（--static-regions、--loop-overlap K --ambient）
网页游戏中的碰撞和路径	references/runtime/map-runtime.mjs（规则与 map_nav.py 相同）

验收

• 只有在 map_bundle.py validate 和 map_nav.py check 均通过，且 build_scene_preview.py 的路线检查对每条路线都显示 ok: true 后，地图才算可玩。map_nav 根据数据验证可达性，但不能证明碰撞区域与绘制的美术内容一致。
• 在游戏比例下使用有代表性的角色进行合成；检查出生点净空、碰撞体与树冠、传送门双向抵达、接合处、重复拼接处和摄像机覆盖范围。
• 使用图块时，最佳阶段状态为 needs-visual-review。在称循环无缝之前，先引用 scene_motion.py qa 的数值（解码后的拼接处、帧数、fps、keyint、字节数）。
• 原生 alpha 必须保留紫色；RGB 棋盘格不代表透明。声称移动端性能良好之前，先在设备上测试。
• 交付原始素材和提示词及其来源信息（路线、模型、estimateUsd）、运行时素材和数据、预览和已运行的检查，并说明剩余限制。
• 逐字报告每个已发布 QA 信封中的所有 WARN 或 FAIL 检查（id、值、阈值、文件）；只要任何已发布信封中存在警告，就绝不能说“所有检查均已通过”。

参考资料

map-strategies.md、map-presets.md、layered-map-contract.md、prop-pack-contract.md、side-scroll-scenes.md、parallax-backgrounds.md、background-scenes.md、hd2d-plates.md、hd2d-presentation.md、scene-preview.md、engine-maps.md；数据契约见 references/schemas/map.schema.json。