lyseocuonglauthingai-sketch/generate2dsprite

生成 2D 精靈圖 (Generate 2D Sprite)

製作遊戲所需的最小資產包，以其實際顯示尺寸、鏡頭和風格呈現。 遊戲邏輯（碰撞、傷害、時序）保持與美術獨立。

使用時機

• 需要角色、生物、道具、物品、圖示或特效作為主靜態圖、圖表或片段。
• 已存在影格（已生成、繪製、程式碼繪製），需要片段、調色板或引擎匯出。

不使用時機

• 地圖、圖塊、地形、視差或場景圖版：請參閱 generate2dmap。
• 動畫角色：在此批准一個主靜態圖，然後由 video2dsprite 為每個動作製作一個片段（video-handoff.md）。
• 使用者要求的程式碼繪製美術：請參閱 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 金鑰已配置（是或否）、本地就緒狀態以及解析順序。如果 encoding.stdout 失敗，請設定 PYTHONUTF8=1。

美術來源

影像生成是角色、生物、道具、圖示和特效的預設美術來源。將其記錄為 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）時使用。然後說「程式碼繪製，無影像模型」。

HiBit 特效是唯一例外：fx_pixelfx.py check 會在使用者安裝了 pixelfx 時將其發送到 pixelfx（路由 A，第三方程式碼繪製特效，需註明來源並揭露），否則發送到影像路由（路由 B）。請參閱 hibit.md。

每個影像都透過一個指令處理：python "<skill-dir>/../generate2dmedia/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1024x1024 --out-dir <new>。它會按該順序選擇路由，並輸出一行 JSON，包含 route、artifact、sha256 和 estimateUsd；resolve --kind image 會說明將執行哪個路由。使用者提供的現有美術始終受歡迎。切勿聲稱未發生的生成；保留提示和合約，並報告缺少的能力。

• 完成風格： HD 是預設值：全彩、清晰的 Alpha、一個註冊點和一個預乘面積縮小至遊戲高度。像素完成風格（一個共享調色板、二元 Alpha、無抖動）是當使用者要求像素美術時的選項；HiBit 完成風格（來自模型的扁平無線條美術，然後一個角色調色板、多數決縮小和從影像中提取的輪廓顏色）是當他們想要 HiBit 外觀時（hibit.md）。切勿提示影像模型建立邏輯像素網格；像素外觀來自完成風格。
• 角色： 為每個角色批准一個主靜態圖，然後使用 video2dsprite 對其進行動畫處理：每個動作一個從該主靜態圖（sprite_set.py）生成的影像到影片片段。保持每個動作的身體高度與主靜態圖的休息姿勢一致。
• 圖表 適用於特效、圖示和道具（以及使用者提供的影格），不適用於角色動畫。

主靜態圖（每個角色動畫從這裡開始）

為每個角色批准一個主靜態圖，然後從中為每個動作製作一個影像到影片片段（video2dsprite）；圖表適用於特效、圖示和道具。措辭：prompt-rules.md；指令、取景和 master.json：master-still.md。

1. 規格（--spec <json> 和/或旗標）：--name、--subject、--identity（長且精確）、--facing left|right|front|back、--class hero|mob|boss|prop、--finish hd|pixel|hibit（HD 預設；僅在要求時使用 pixel 或 hibit；hibit 會使靜態圖扁平且無線條）、--identity-ref（第一個影像，完全複製）、--style-ref（第二個：一個已批准的同伴精靈，僅風格和取景）、--key（預設 #FF00FF；紫色和粉色設計使用綠色或藍色）。
2. 生成：python "<skill-dir>/scripts/master_still.py" generate --spec <json> --takes 3 --output-dir <new>。每個嘗試都透過 generate2dmedia route_media.py（首先是 API 金鑰，然後是本地守護行程）進行；takes.png 會並排顯示它們。退出碼 3 表示無路由：請說明；codeart2d 是備用方案（「程式碼繪製，無影像模型」）。使用宿主自己的影像工具時：執行 master_still.py prompt 並按順序附加列出的參考。
3. 透過觀察選擇：身份、朝向、無任何部分觸碰邊緣、無文字。
4. 透過編輯修復接近的失敗，切勿重新生成：master_still.py edit --run <dir> --take N --change "<一個更改>" --output-dir <new>（或 --master <dir>）。
5. 批准：master_still.py approve --run <dir> --take N --output-dir <new>（來自其他地方的靜態圖：--still <png> --route <製作它的來源>）。它會為靜態圖設定按鍵顏色，以 6 像素邊距裁剪，使用 LANCZOS 縮放至類別取景（1024x1024 中英雄高度 788 像素，頂部邊距 138 像素），並寫入 master.png（不透明，純按鍵色）、master_rgba.png 和 master.json（generate2dsprite.master.v1）。
6. 動作步驟讀取 master.json（identity_recap、facing、finish、class、framing、key、files、transform、route），並且永不重新測量靜態圖；每個片段提示都以「相同的 <identity_recap>」開頭。

報告來自 master.json route 的路由。FORGE_ROUTE_MEDIA_FAKE 警告表示該影像非真實生成。

宿主筆記

• Codex： image_gen 是您自己的影像工具；若無配置金鑰請使用它並透過 view_image 查看結果。此會話中製作的、不在專案中的影像：python "<skill-dir>/../generate2dmedia/scripts/cli_media.py" adopt --codex-thread <thread-id> --output-dir <new>，然後處理 generated.png。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>/../video2dsprite）。將輸入和輸出保留在專案內。每個工具都會寫入一個新的 --output-dir：它會拒絕已存在的目錄，在其旁邊暫存，並僅在檢查通過後才發布（--strict-qc / --strict 在失敗時不發布任何內容）。成功時輸出一行 JSON；錯誤時輸出 error: ... 並退出碼 1；使用錯誤時退出碼 2。需要 Python 3.10+、numpy 和 Pillow（建議使用 scipy）。--help 列出所有旗標。

規劃資產

記錄身份和參考、攝影機和朝向、風格、遊戲顯示尺寸、完成風格（預設 HD，按需求使用 pixel）、動作清單和階段、循環或一次性、運動範圍、共享根和輸出格式。為每個角色保留一個已接受的主靜態圖和一個來源到顯示的縮放比例；除非已規劃，否則小怪不應比英雄高。網格不等於平滑度：姿勢間距、時序、循環接縫和地面接觸更重要。姿勢、近/遠腿和時序：animation-planning.md。

• Alpha：native_alpha 保留真實透明度（繪製的棋盤格不是 Alpha）；chroma_key 僅在主體沒有 Alpha 時使用純洋紅色；opaque 保留完整影像（assemble_frames.py）。
• 取樣：對生成的影像使用 lanczos 或預乘區域縮放；僅對已驗證的像素網格使用 nearest。高解析度類像素繪畫不是乾淨的 32 像素美術。
• 共享根不是每幀 Alpha 邊界框底部：保留意圖性的飛行、跳躍、彈跳和後座力。

生成（影像路由）

自行撰寫提示（prompt-rules.md；網格、階段和預設值在 action-recipes.md 中）。透過 --reference（或您工具的實際影像輸入）附加參考；散文中的路徑不是參考。在每次生成中保留已批准的主靜態圖，並描述絕對階段，而非鏈式編輯；修復是對已批准靜態圖的編輯，僅命名更改。一次生成一個動作系列，並將寬闊的揮砍、軌跡和投射物保留在身體圖表之外。驗證實際路由、模型和返回尺寸；切勿僅根據提示聲稱這些資訊。

管線

圖表（特效、圖示、道具）：在原始圖表上執行 sheet_qc.py spill，然後 generate2dsprite.py process，然後 sheet_qc.py frames，然後 scale_frames.py，然後 build_animation_clips.py，然後 export_engine.py。角色動作從 video2dsprite 作為打包的片段返回。

需求	路由
為影像工具規劃圖表（長寬比、網格、指南、提示）	plan_guide.py --frames N --cycle run --output-dir <new>；附加 guide.png，貼上 prompt.txt。固定縮放和腳線：make_anchor_layout.py；空白安全幀：make_layout_guide.py
在切片前檢查原始圖表	sheet_qc.py spill --input <sheet> --rows R --cols C --output-dir <new>；交錯的部分表示需要以更大邊距重新生成或按所有權切片，切勿使用最大組件濾鏡
為圖表設定按鍵、切片和註冊	generate2dsprite.py process --input <sheet> --target asset --mode <mode> --rows R --cols C --output-dir <new> --strict-qc（幾何 v2；processing.md）
以 M 個來源像素/美術像素繪製的像素美術	process --resampler nearest --logical-pixel M --pixel-scale N（僅整數縮放）
在一個註冊點上進行跳躍、彈跳或後座力	process --scale-strategy registered（或 --anchor-px X,Y）
一個角色在不同動作間的縮放	在接地參考上執行 process --write-scale-profile <p.json>，然後 --scale-profile <p.json> --max-profile-scale-drift 0.08
畫布無法整除網格；其他行順序	process --grid-rounding nearest 或 --pad-to-grid；--direction-order down,up,left,right（modes.md）
身份、近/遠交替、漂移、基線	sheet_qc.py frames --sheet <sheet> --rows R --cols C --cycle run --output-dir <new>；重複的半循環表示需重新生成第二部分。在程式碼繪製的影格上（art_source=code），identity_residual 和 torso_drift 僅供參考
遊戲尺寸在一個畫布和根上，永不裁剪	scale_frames.py --frames <pngs> --root-lock torso-x --row-baseline --emit-clips --ticks N --output-dir <new>；後續動作添加 --profile <first>/scale-frames.json --action-padding L,T,R,B
帶有時序、事件、過渡的片段	build_animation_clips.py --manifest clips.json --output-dir <new>；閱讀 lint 和 review/（frames-and-clips.md）
完整影格或場景循環（無按鍵）	assemble_frames.py（--key chroma、--slice ownership；僅環境循環使用 --loop-overlap K --ambient）
共享調色板、鎖定、變體、閃爍（像素完成風格）	palette_tool.py build、apply、lock、quantize-seq、variants、luts；嚴格邏輯網格：pixel_reduce.py（palette-and-pixels.md）
引擎匯出	export_engine.py --clips <animation-clips.json> --target all --output-dir <new>；Sprite3D：--target godot-sprite3d --world-height <units>（engine-export.md）
在遊戲中播放片段（步態、擊停、過渡）	runtime-integration.md
程式碼繪製的精靈、骨架或特效，僅按需求	codeart2d render_pixelspec.py、rig_animate.py 或 fx_build.py 搭配 --build-clips（切勿使用 process），然後 export_engine.py；將其揭露為程式碼繪製
HiBit 遊戲的特效	fx_pixelfx.py check 選擇路由（使用者命名的路由優先）。A, pixelfx 已安裝（推薦）：fx_pixelfx.py render --pixelfx <checkout> --id <effect> --ramp ... --snap <palette.json>，pixelfx 由 Patch 開發（MIT 授權，使用者克隆的獨立專案），附帶 CREDITS.txt 並揭露為 pixelfx 的程式碼繪製。B, 否則：來自影像路由的 2x2 特效圖表，使用 process --scale-strategy registered --cell-size 512，然後 hibit_fx.py pixelize --palette <palette.json>（hibit.md）

驗收

• 在遊戲尺寸下審查：輪廓和身份、接觸和飛行、循環接縫或一次性恢復、淺色和深色背景上的 Alpha、肢體、跨動作的縮放、根和碰撞體。
• 引用數字以證明品質聲明：pipeline-meta.json 中的 matte.qa（key_ring_spill 警告：添加 --despill-radius 1 或 --key-quality soft）、sheet-qc.json、片段建構器的 lint。數字化 QC 能發現症狀；但從未批准解剖學或運動。
• 逐字報告每個已發布 QA 信封中的 WARN 或 FAIL 檢查（ID、值、閾值、檔案）；當任何已發布的信封有警告時，切勿說「所有檢查通過」。
• 交付已接受的來源美術、運行時影格或片段、預覽、提示和來源證明（路由、模型、estimateUsd）、QA 和剩餘限制。在修訂時保留最後一個接受的套件。

參考資料

processing.md （處理旗標、舊版開關）、modes.md、prompt-rules.md、action-recipes.md、frames-and-clips.md、palette-and-pixels.md、animation-planning.md、engine-export.md、runtime-integration.md、master-still.md、video-handoff.md、hibit.md