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 - 侧视可控制英雄,具有待机/奔跑/射击/跳跃 ->
player+hero_action_bundle- 待机网格表,通常 4 帧的
2x2 - 奔跑网格表,根据所需帧数通常是
2x2或2x3 - 射击网格表(仅身体/武器),通常是
2x2 - 跳跃网格表,通常是
2x2 - 需要时,投射物/枪口闪光作为单独资产
- 每个动作质量检查后,可选组装的引擎图集
- 待机网格表,通常 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。 - 对于地图道具或旨在匹配干净手绘高清地图的资产,使用
clean_hd。 - 仅当用户希望获得类似像素的外观但避免复古粗犷感时,使用
pixel_inspired。 - 当现有地图、游戏或参考应定义风格时,使用
map_style或project-native。
如果涉及参考:
- 将参考接入调用:将其沙箱
file_path传递给imagine_image_to_image— 如果有两个以上参考,则传递给imagine_reference_to_image(生成的图像已有file_path;本地文件使用其沙箱路径)。同时使用read_file读取本地参考,以便你能看到它们。 - 明确说明参考的角色:保持身份/风格不变、为同一主题创建动画表、创建演化/变体,或推导出匹配的道具/特效。
- 保留参考中稳定的身份标记:轮廓、调色板、面部/眼睛特征、服装标记、主要配饰和材质语言。
- 仅允许请求的动作或演化改变。除非用户要求,否则不要重新设计主题。
- 仍然要求精确的表形状、纯品红色背景、帧包含性以及跨帧相同比例。
保持严格部分:
- 纯
#FF00FF背景 - 精确的表形状
- 跨帧相同的角色或资产身份
- 跨帧相同的边界框和像素比例
- 明确的包含性:不得有任何内容跨越单元格边缘
混合动作图集防护栏:
- 不要要求
imagine_text_to_image在一张原始表中生成无关的动作行,例如对于可控制英雄或主角的“第1行待机,第2行奔跑,第3行射击,第4行跳跃”。 - 不要要求
imagine_text_to_image为可控制英雄、角色、生物、NPC、敌人、召唤物或动画道具生成原始单行动作条带,如1x4 idle、1x4 run、1x4 shoot或1x4 jump。 - 如果引擎需要组合的
4x4、5x5、自定义图集或行条带交付格式,分别生成动作网格,分别处理和检查质量,然后确定性地组装交付图集。 - 例外情况是标准方向移动表、一个连续的长动作序列、道具包、类似瓦片集的图集和低风险的紧凑敌人战斗表。这些仍然需要一个连贯的提示词和视觉检查。
- 除非投射物、枪口闪光、撞击、灰尘轨迹和独立特效有意成为同一动作轮廓的一部分且保持紧密连接,否则将它们保留在单独的表中。
- 对于可控制英雄和主角,当效果使动作边界框比待机/奔跑宽或高得多时,“紧密连接”是不够的。默认将宽挥砍弧线、枪口闪光、长武器轨迹、灰尘云和撞击爆炸拆分为单独的特效表。
动画身体网格防护栏:
1x4和其他原始单行表不是动画身体的有效默认值。这包括玩家、可控制英雄、生物、NPC、敌人、召唤物、动画道具和身体相关的战斗动作。- 4 帧身体动作用
2x2。这是待机、短攻击、射击身体、跳跃、受伤、悬停和紧凑侧视行走/奔跑动作的默认值。 - 6 帧身体动作用
2x3,例如施法、攻击、召唤、奔跑、冲锋或变形。 - 对于更长的身体动作,使用
2x4、3x3、3x4或4x4。优先选择紧凑网格而非长行。 - 对于 4 方向俯视行走,
4x4可以作为原始生成形状保留,因为它是一个标准的方向移动表,而不是四个不相关的动作行。 - 如果最终运行时需要行条带,在质量检查后从处理后的多行网格帧中组装。
- 保持角色在每个单元格中居中。身体中心线应靠近单元格中心,可见时脚/底部锚点应保持在相同 y 位置,主体应仅占据中央安全区域,并带有充足的品红色内边距。
- 对于攻击、射击、施法、冲锋和其他身体动作,身体高度应接近已接受的待机/奔跑身体高度。如果使用固定单元格运行时,即使
edge_touch_frames为空,当身体比待机/奔跑小 10-15% 以上时,也要拒绝身体动作输出。
地图道具包防护栏:
- 仅对紧凑型道具使用方形
2x2、3x3和4x4原始道具包,例如岩石、灌木、桶、板条箱、灯、小标志、罐子、碎片和小装饰品。 - 不要将方形道具包用于宽大或碰撞关键的地图对象:地板、平台、壁架、地形块、桥梁、墙壁边栏、梯子、道路、轨道、管道、长钉陷阱、大门、门、建筑物、大树、检查点、出口或建造平台。
- 对独特、大型、重要、高大、不规则或碰撞对齐的道具使用逐个生成。
- 对可重复的平台/地板资产使用
1x3或1x4条带,包括左端、中间重复、右端,以及可选的斜坡/角落/末端变体。 - 对多个大小和比例的道具使用自定义宽单元格。
...
[因翻译而截断]