codeart2d

代码绘制 2D 美术

你用文本编写美术内容（PixelSpec JSON、可移植 SVG、骨架、特效、材质、布局或视差规格）；脚本负责渲染、检查和打包。不涉及图像模型。这是声明式美术源（art_source: "code"），而非占位内容。

适用场景

• 用户明确要求用代码绘制美术：PixelSpec 或 SVG 精灵、用代码绘制的调色板变体、代码骨架、代码特效、缝合验证通过的自动拼接图块集、代码制作的布局、风格化视差或环境循环动画。
• route_media.py 打印 no-route（退出码 3）：未配置 API 密钥，且没有可用的本地图像或视频路由。请说明这一点，并同时提出添加密钥或 CLI 的选项。
• 可帮助图像模型的姿势和布局指南（辅助素材，非最终美术）。

不适用场景

• 存在图像或视频路由，且用户未要求代码绘制美术时提出的任何美术请求：generate2dsprite、generate2dmap 或 video2dsprite 会生成美术。
• 绘画风格、有机形态或具有鲜明辨识度的美术、肖像、HD-2D 场景图或带纹理的地形；写实火焰、烟雾或水体。
• 切勿将受许可保护的角色描摹成规格。

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

运行 python "<skill-dir>/../generate2dmedia/scripts/route_media.py" resolve --kind image（或 --kind video）：如果输出了路由，除非用户要求代码绘制美术，否则应由图像或视频技能处理请求。同一文件夹中的 forge_doctor.py 会显示完整信息。如果 encoding.stdout 失败，请设置 PYTHONUTF8=1。处理 SVG 时，每台机器还需运行一次 svg_render.py doctor --report <new.json>。

美术源

此技能是路由顺序中仅在明确要求时使用的最后手段：先是配置了密钥时使用的 API，然后是本地图像工具，最后才是代码绘制美术；仅当用户要求或不存在其他路由时使用。切勿静默地用它替代生成式美术。开始绘制前，请查看 style-envelope.md，了解代码绘制美术的能力边界（其中的表格描述能力，不代表路由顺序）；如果请求需要图像模型，请告知用户。每次都要披露结果的来源：“代码绘制，未使用图像模型”（codeart-meta.json 会记录 "art_source": "code"）；切勿将其冒充为图像模型的输出。

宿主说明

• **Codex：**此技能仅在明确要求时使用；除非用户要求代码绘制美术，否则由 image_gen 和 route_media.py 生成美术。使用 view_image 查看审核图。
• **Claude Code：**仅在用户要求或出现 no-route 后使用。汇报前使用 Read 查看每个 preview-*.png 和 review/*.png；使用 Bash 运行工具；<skill-dir> 为 ${CLAUDE_SKILL_DIR}。
• **Grok：**运行相同的 Python 工具；除非用户要求代码绘制美术，否则由其原生图像工具生成美术。

命令

从用户的项目根目录开始，将每个工具作为一行命令运行：python "<skill-dir>/scripts/<tool>.py" ...。<skill-dir> 是此技能的文件夹；同级技能位于其旁边（--build-clips 会调用 <skill-dir>/../generate2dsprite/scripts/build_animation_clips.py）。请将规格和输出保存在项目内。每个工具都会写入一个新的 --output-dir：如果目录已存在，则会拒绝写入；只有在结果完整时才会发布；使用 --strict-qc 时，检查失败则不会发布任何内容。成功时会打印一行 JSON；出错时会打印 error: ... 并以退出码 1 退出；用法错误以退出码 2 退出。可直接复制的示例见：examples/。

依赖项：所有功能均需 numpy 和 Pillow；PixelSpec 渲染和 pixel_qa.py 无需其他依赖。SVG 美术还需要一个光栅化器：resvg-py（python -m pip install "resvg-py>=0.5,<0.6"，首选）、PATH 中的 resvg-js CLI，或 Chrome/Edge（设置 CHROME_PATH）（rasterizers.md）。切勿使用 PyMuPDF、skia-python 或 cairosvg：它们会悄悄忽略 crispEdges、<style>、clipPath 或渐变。fx_verify.mjs 需要 node。

Hello sprite

1. 编写 gem.pixelspec.json（pixelspec.md 中的“Hello sprite”区块）。
2. python "<skill-dir>/scripts/render_pixelspec.py" --spec gem.pixelspec.json --output-dir out/gem-v1 --preview-scale 8 --strict-qc
3. 打开 out/gem-v1/preview-x8.png；各帧位于 out/gem-v1/<variant>/frames/。
4. 告知用户，这是用代码绘制的（未使用图像模型）。

流程

需求	方案
带调色板变体的像素角色、道具或特效	PixelSpec（pixelspec.md），然后运行 render_pixelspec.py --spec <spec> --output-dir <new> --build-clips --strict-qc；使用 pixel_qa.py 检查
扁平矢量角色、道具、UI 或图标集	使用调色板类的可移植 SVG（svg-profile.md），然后运行 svg_render.py render --svg <svg> --palette <palette.json> --output-dir <new> --zoom N
使用 SVG 形状绘制的清晰像素艺术	svg_render.py render --crisp --zoom N --strict-qc
渲染前检查 SVG	svg_render.py lint --svg <svg> --profile portable（添加 --compile --palette <p>）
能行走、待机或攻击且脚步落地的小型角色	Rig SVG 加上 rig_anim.v1 文件（rig-animation.md），然后运行 rig_animate.py --rig <svg> --anim <json> --output-dir <new> --build-clips --strict-qc；查看 review/*.png
斩击、火花、冲击环、受击闪光、尘土、投射物	fx.v1 规格（fx-language.md），然后运行 fx_build.py --spec <json> --output-dir <new> --build-clips --export-runtime；像素游戏使用烘焙帧，按游戏玩法时序触发的特效使用 fx-runtime.mjs（fx-runtime-contract.md）
检查 fx.v1 运行时	node "<skill-dir>/scripts/fx_verify.mjs" <module.mjs> --report <file>
地形过渡、道路与水域交接、地面上的路径、墙壁和平台边缘	材质规格，然后运行 autotile_build.py --material-spec <json> --output-dir <new> --strict-qc（Wang-16、三种材质、blob-47、斜面；tiles-and-maps.md）
在精确图块蒙版内使用图像工具生成的纹理	autotile_build.py --material-texture NAME=PATH --quantize-textures（一个可无缝循环的图块）
可游玩的俯视地图：道路、道具、出口、碰撞、可达性	layout_build.py --spec <layout.json> --output-dir <new> --preview --strict-qc（使用真实图块时添加 --tiles <tileset manifest>）；打开 debug.png（layouts-and-parallax.md）
风格化视差背景	parallax_build.py --spec <parallax.json> --output-dir <new> --validate --sweep-frames 49；检查 sweep-sheet.png
静态底图上的环境动态效果	ambient_bake.py --plate <png> --spec <effects.json> --output-dir <new> --preview --strict-qc；使用 generate2dmap scene_motion.py 编码
对任意像素帧进行 QA	pixel_qa.py --input "<glob>" --palette <palette, spec or codeart-meta.json> --review <new.png> --onion --strict --report <new.json>

交接流程：片段交给 generate2dsprite export_engine.py（切勿使用 generate2dsprite.py process）；布局的 map_bundle.v2 交给 generate2dmap map_bundle.py validate、map_nav.py check 以及 export_tiled.py / export_godot.py / export_ldtk.py。

规则

• SVG（可移植配置文件，由 lint 强制执行）：根元素的宽度和高度等于整数 viewBox（1 个单位 = 1 个逻辑像素）；颜色使用 class="c-NAME"；骨骼使用 transform="rotate(a cx cy)" 旋转；不得使用 <text>、<image>、feTurbulence、feDisplacementMap 或 mix-blend-mode；像素艺术须添加 shape-rendering="crispEdges"，且不得使用渐变、蒙版、滤镜或不透明度。
• 图块集发布前须通过接缝验证：将从图集组装的图块与独立的全局渲染进行逐像素比较，覆盖该图块集允许的每种相邻组合。没有此验证，--strict-qc 永远不会通过。
• 构建动画片段前，先折叠 FX 尾部的空帧；构建器会拒绝完全透明的帧。
• 侧视行走和奔跑循环：让近侧腿与远侧腿有明显的明暗对比（远侧腿至少暗两个色阶，不能让两个暗色看起来相同），并确保手臂或前腿清晰可见（不要藏在围巾、披风或包下面）。当步行／奔跑动画片段的第 i 帧与第 i+n/2 帧轮廓相同（IoU >= 0.95）时，render_pixelspec.py 会警告 half_cycle_duplicates；请修正腿部，或仅在审核表确认步幅效果明确后，传入 --allow-duplicate-half-cycle。
• 对代码绘制的帧（art_source=code）运行 generate2dsprite sheet_qc.py frames：由于头部和根节点由代码固定，identity_residual 和 torso_drift 仅供参考，应通过目测判断；near_duplicates 和 leg_alternation 则应视为实际问题。

验收

提交报告前，请以游戏尺寸和 1x 查看预览和审核表（审核流程见 style-envelope.md）。引用 JSON 摘要中的 QA 状态和失败检查项。 逐字报告每个已发布 QA 包络中的所有 WARN 或 FAIL 检查项（id、value、threshold、files）；只要有任何已发布包络包含警告，就不得声称“所有检查均已通过”。交付规格、渲染帧或图块、动画片段或资源包、codeart-meta.json 和披露行。数据约定见 references/schemas/codeart.schema.json。