Generate2dsprite
在 app-builder 沙盒(TanStack Start + 瀏覽器遊戲)中,使用此技能處理自包含的 2D 精靈或動畫資源。
當較大的遊戲或可玩原型需要精靈時,請使用此技能處理可見的精靈資源,並將執行時期/遊戲組合分開處理(匯出後接入 Phaser / Canvas / DOM)。請勿以程式繪製的佔位符取代要求的精靈資源。
App-builder / Grok 環境
| 項目 | 值 |
|---|---|
| 技能目錄 | .grok/skills/generate2dsprite/ |
| 腳本 | python3 .grok/skills/generate2dsprite/scripts/<script>.py … |
| 影像工具 | imagine_text_to_image / imagine_image_to_image(基於路徑;提示詞撰寫請參閱 imagine 技能) |
| 檢查影像 | 使用 read_file 讀取 PNG 路徑(非 Codex view_image) |
| 生成影像路徑 | imagine_text_to_image 回傳沙盒中的 file_path;在處理前將該路徑複製到你的執行目錄 |
| Python 依賴 | Pillow + numpy(影像環境已預先安裝) |
| 輸出根目錄 | 偏好 /workspace 下的 assets/sprites/<name>/,以便應用程式導入 |
| 引擎目標 | 瀏覽器:Canvas 2D、Phaser 或 DOM/<img> — 除非使用者要求,否則非 Godot/Unity |
相關技能:imagine(影像工具使用)、game-asset-core(+ game-animation-frames / game-character-consistency,用於品質控制與引擎就緒預設值)、generate2dmap(地圖/道具)、video2dsprite(透過 imagine_image_to_video 實現更密集的動作)、building-games(遊戲循環/整合)。
參數
從使用者請求中推斷出這些參數:
asset_type:player|npc|creature|character|spell|projectile|impact|prop|summon|fxaction:single|idle|cast|attack|shoot|jump|hurt|combat|walk|run|hover|charge|projectile|impact|explode|deathview:topdown|side|3/4sheet:auto|2x2|2x3|2x4|3x3|3x4|4x4|5x5|custom_grid|strip_1x3|strip_1x4frames:auto或明確的幀數bundle:single_asset|unit_bundle|spell_bundle|combat_bundle|line_bundle|hero_action_bundle|engine_atlaseffect_policy:all|largestanchor:center|bottom|feetmargin:tight|normal|safeart_style:pixel_art | clean_hd | pixel_inspired | retro_pixel | map_style | project-nativereference:none|attached_image|generated_image|local_filelayout_guide:none|optional|recommendedprompt:使用者的主題或視覺方向role:僅當資源明顯是 NPC 角色時使用name:可選的輸出縮寫名稱
當請求不明確時,請閱讀 references/modes.md。
代理規則
- 自行決定資源計劃。當請求已暗示工作表大小、幀數或捆綁結構時,不要強迫使用者明確指定。
- 不要僅僅為了滿足
4x4、5x5或自訂引擎圖集,而將不相關的動作打包到一個原始生成的工作表中。一個原始生成的工作表應代表一個動作系列、一個連續序列、一個標準的方向性移動工作表,或一個道具/資源包。 - 對於可控制的英雄、主要角色以及具有多種動作的高價值玩家資源,首先分別生成每個動作的網格工作表,對每個動作進行品質控制,然後僅在網格通過視覺審查後,再確定性地組裝引擎所需的圖集。
- 對於可控制的英雄、主要角色以及高價值玩家身體動作,預設將攻擊/射擊/施法身體工作表設定為僅包含身體。不要在身體工作表中包含大型斬擊弧線、槍口閃光、投射物、衝擊爆發、分離的灰塵、長拖尾或寬大的分離特效。將這些作為獨立的
fx、projectile或impact工作表生成,並在遊戲中分層渲染。 - 僅當目標執行時期明確支援更寬的逐動作儲存格以及逐動作原點/錨點元資料時,才將寬大的攻擊特效包含在同一個原始身體工作表中。否則,寬大的特效邊界框將迫使身體在固定儲存格內縮小。
- 自行撰寫美術提示詞。不要預設使用提示詞建構腳本。
- 對每個原始影像使用內建的
imagine_text_to_image。 - 不要使用 Three.js、Canvas、SVG、HTML/CSS 繪圖、PIL 形狀繪圖、程序化幾何圖形、佔位符基本圖元或程式渲染的螢幕截圖來建立原始精靈美術。執行時期程式碼可以顯示已完成的生成資源,腳本可以製作佈局指南或後處理生成的影像,但請求的精靈美術必須源自內建的
imagine_text_to_image。 - 當使用者提供或暗示視覺參考時,將該參考的沙盒
file_path傳遞給imagine_image_to_image(該工具會讀取檔案)。同時使用read_file讀取本地參考,以便你能看到它;僅在提示詞中提及的路徑不是視覺輸入。 - 當資源是
$generate2dmap的地圖道具,或使用者/專案請求不同風格時,不要強制使用像素藝術。首先匹配地圖或參考的風格。 - 僅將腳本用作確定性處理器:洋紅色去背、影格分割、元件過濾、縮放、對齊、品質控制元資料、透明工作表匯出以及 GIF 匯出。
- 不要使用腳本來生成創意影像提示詞。如果存在舊的提示詞建構命令,僅將其視為歷史相容性,而非正常的技能工作流程。
- 佈局指南僅允許作為影像生成的確定性幾何參考。它們可以顯示插槽數量、間距、置中與安全邊距,但絕不能定義創意美術方向。
- 將腳本標誌視為由代理選擇的執行基本元素,而非使用者面向的硬編碼工作流程。
- 如果生成的工作表觸及儲存格邊緣、比例發生偏移、或破壞投射物/衝擊循環,請使用更好的原始設定重新處理,或重新生成原始工作表。
- 不要對角色、玩家、可控制英雄、生物、NPC、敵人、召喚物、動畫道具或任何需要主體/主題保持置中的資源,使用原始的單行工作表,如
1x4、1x6、1x8或1xN。單行原始生成太容易發生水平偏移和不一致的裁剪。 - 對於動畫身體資源,預設使用多行網格:4 幀 ->
2x2,6 幀 ->2x3,8 幀 ->2x4,9 幀 ->3x3,12 幀 ->3x4或4x3,16 幀 ->4x4。 - 如果遊戲引擎需要最終的單行條帶或混合圖集,首先生成並品質控制多行網格的動作,然後確定性地組裝交付條帶/圖集。
- 在每個動畫身體網格提示詞中,要求主體身體在每個儲存格中保持置中,完整身體位於中央 60% 到 70% 的安全區域內,各儲存格間比例一致,適用時保持穩定的腳底/底部錨點線,並且沒有肢體、武器、頭髮、斗篷、灰塵、槍口閃光或分離特效跨越儲存格邊緣。
- 對於英雄攻擊身體提示詞,明確要求身體高度和身體比例與已接受的靜止/奔跑工作表匹配,穩定的腳底/底部錨點,武器保持足夠近以免擴大身體邊界框,並且沒有分離的斬擊弧線或螢幕空間攻擊特效。
- 對於地圖道具包,在選擇網格前先對道具進行分類。方形
2x2、3x3和4x4包僅適用於緊湊型道具。不要將平台、地板、橋樑、牆壁、梯子、大門、門、長形障礙物、寬/高道具、碰撞承載物體或圖塊集/條帶片段放入方形道具包中;應使用逐一生成、1x3/1x4條帶、自訂寬儲存格或類似圖塊集的圖集。 - 保持純色
#FF00FF背景規則,除非使用者明確要求不同的處理工作流程。
工作流程
1. 推斷資源計劃
選擇最小的有用輸出。
範例:
- 可控制英雄,四個方向 ->
player+player_sheet - 側視可控制英雄,包含 idle/run/shoot/jump ->
player+hero_action_bundle- idle 網格工作表,通常 4 幀用
2x2 - run 網格工作表,通常根據所需幀數用
2x2或2x3 - shoot 網格工作表,僅包含身體/武器,通常用
2x2 - jump 網格工作表,通常用
2x2 - 投射物 / 槍口閃光作為獨立資源(必要時)
- 可選的引擎圖集,在逐動作品質控制後組裝
- idle 網格工作表,通常 4 幀用
- 側視可控制英雄,包含近戰攻擊 ->
player+hero_action_bundle- 攻擊身體網格工作表,通常用
2x2或2x3,僅身體 - 斬擊弧線 / 武器軌跡作為獨立的
fx工作表(當攻擊需要寬大的視覺效果時) - 衝擊火花作為獨立的
impact工作表(當命中需要反饋時)
- 攻擊身體網格工作表,通常用
- 治療師世界 NPC ->
npc+single_asset或unit_bundle - 大型 Boss 待機循環 ->
creature+idle+3x3 - 巫師投擲魔法球 ->
spell_bundle- 施法者施法工作表
- 投射物循環
- 衝擊爆發
- 怪物系列請求 ->
line_bundle- 規劃 1-3 種型態
- 每種型態,製作請求實際需要的工作表
2. 手動撰寫提示詞
使用 references/prompt-rules.md。
在撰寫提示詞之前選擇 art_style:
- 對於經典精靈、16 位元 RPG 角色以及明確要求像素藝術的請求,使用
pixel_art或retro_pixel。 - 對於地圖道具或旨在匹配乾淨手繪 HD 地圖的資源,使用
clean_hd。 - 僅當使用者想要像素相鄰的外觀但沒有復古的厚重感時,使用
pixel_inspired。 - 當現有的地圖、遊戲或參考應定義風格時,使用
map_style或project-native。
如果涉及參考:
- 將參考接入呼叫:將其沙盒
file_path傳遞給imagine_image_to_image— 或將路徑列表傳遞給imagine_reference_to_image(用於 2 個以上參考;生成的影像已經有file_path;本地檔案使用其沙盒路徑)。同時使用read_file讀取本地參考,以便你能看到它們。 - 明確說明參考的角色:保留身份/風格、為相同主題建立動畫工作表、建立演化/變體、或推導出匹配的道具/特效。
- 保留參考中的穩定身份標記:輪廓、調色板、臉部/眼部特徵、服裝標記、主要配件以及材質語言。
- 僅允許請求的動作或演化發生變化。除非使用者要求,否則不要重新設計主題。
- 仍然要求精確的工作表形狀、純色洋紅色背景、幀包含以及各幀間比例一致。
保留嚴格的部分:
- 純色
#FF00FF背景 - 精確的工作表形狀
- 各幀間相同的角色或資源身份
- 各幀間相同的邊界框與像素比例
- 明確的包含:任何東西都不能跨越儲存格邊緣
混合動作圖集護欄:
- 不要要求
imagine_text_to_image在一個原始工作表中生成不相關的動作行,例如對於可控制英雄或主要角色:「第 1 行 idle,第 2 行 run,第 3 行 shoot,第 4 行 jump」。 - 不要要求
imagine_text_to_image為可控制英雄、角色、生物、NPC、敵人、召喚物或動畫道具生成原始的單行動作條帶,例如1x4 idle、1x4 run、1x4 shoot或1x4 jump。 - 如果引擎需要組合的
4x4、5x5、自訂圖集或行條帶交付格式,請分別生成動作網格,分別處理和品質控制,然後確定性地組裝交付圖集。 - 例外情況是標準的方向性移動工作表、一個連續的長動作序列、道具包、類似圖塊集的圖集以及低風險的緊湊型敵人戰鬥工作表。這些仍然需要一個連貫的提示詞和視覺品質控制。
- 將投射物、槍口閃光、衝擊、灰塵軌跡以及分離的特效保留在單獨的工作表中,除非它們有意成為相同動作輪廓的一部分並保持緊密附著。
- 對於可控制英雄和主要角色,「緊密附著」在效果的動作邊界框遠比 idle/run 寬或高時是不夠的。預設將寬大的斬擊弧線、槍口閃光、長武器軌跡、灰塵雲和衝擊爆發拆分到獨立的 FX 工作表中。
動畫身體網格護欄:
1x4和其他原始單行工作表不是動畫身體的有效預設值。這包括玩家、可控制英雄、生物、NPC、敵人、召喚物、動畫道具以及身體附著的戰鬥動作。- 對於 4 幀身體動作,使用
2x2。這是 idle、短攻擊、射擊身體、跳躍、受傷、懸浮以及緊湊側視行走/跑步動作的預設值。 - 對於 6 幀身體動作(如施法、攻擊、召喚、奔跑、衝鋒或變身),使用
2x3。 - 對於更長的身體動作,使用
2x4、3x3、3x4或4x4。優先使用緊湊網格而非長行。 - 對於 4 方向俯視行走,
4x4可以保留為原始生成形狀,因為它是標準的方向性移動工作表,而非四個不相關的動作行。 - 如果最終執行時期需要行條帶,請在品質控制後從已處理的多行網格幀中組裝。
- 保持角色在每個儲存格中置中。身體中心線應保持在儲存格中心附近,可見時腳底/底部錨點應保持在相同的 Y 位置,且主題應僅佔據中央安全區域,並留有充足的洋紅色邊距。
- 對於攻擊、射擊、施法、衝鋒和其他身體動作,身體高度應接近已接受的 idle/run 身體高度。如果使用固定儲存格執行時期,即使
edge_touch_frames為空,當身體看起來比 idle/run 小約 10-15% 以上時,應拒絕身體動作輸出。
地圖道具包護欄:
- 僅將方形
2x2、3x3和4x4原始道具包用於緊湊型道具,例如岩石、灌木、桶子、板條箱、燈具、小標誌、花盆、碎片和小裝飾品。 - 不要將方形道具包用於寬大或碰撞關鍵的地圖物體:地板、平台、壁架、地形塊、橋樑、牆壁延伸、梯子、道路、軌道、管道、長形尖刺陷阱、大門、門、建築物、大樹、檢查點、出口或建築墊。
- 對於獨特、大型、重要、高、不規則或碰撞對齊的道具,使用逐一生成。
- 對於可重複的平台/地板資源,使用
1x3或1x4條帶,包含左蓋、中間重複、右蓋,以及可選的斜坡/角落/末端變體。 - 對於多個相同類型的…
…(原文截斷,為避免遺漏,此處為已翻譯的完整內容)