threejs-image-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Three.js Image Generator

Three.js 图像生成工具

Purpose

用途

Create game-useful 2D assets and references for Three.js projects. This skill is the image-generation layer for the Three.js game system: it produces concepts, textures, decals, UI art, and 2D inputs that can be handed to

threejs-3d-generator

for image-to-3D model creation.

Provider: Google's Gemini image API.

Resolve

<this-skill-dir>

in the commands below in this order:

~/.claude/skills/threejs-image-generator

~/.codex/skills/threejs-image-generator

~/.agents/skills/threejs-image-generator

, or repo

skills/threejs-image-generator

为Three.js项目创建可用于游戏的2D资产和参考素材。该技能是Three.js游戏系统的图像生成层：它生成概念图、纹理、贴花、UI美术资源，以及可提交给

threejs-3d-generator

用于将图像转换为3D模型的2D输入素材。

提供方：Google的Gemini图像API。

按以下顺序解析命令中的

<this-skill-dir>

：

~/.claude/skills/threejs-image-generator

、

~/.codex/skills/threejs-image-generator

、

~/.agents/skills/threejs-image-generator

，或仓库路径

skills/threejs-image-generator

。

When To Use

使用场景

Use this skill before procedural-only fallback when a Three.js game needs:

2D-to-3D reference images for
```
threejs-3d-generator
```
: characters, creatures, buildings, ships, cars, weapons, props, pickups, terrain modules.
Texture and material references: terrain, road, rock, sand, metal, sci-fi panels, trim sheets, decals, hazard labels, signs.
Environment images: skies, backdrops, city horizons, nebula plates, menu backgrounds, parallax layers.
UI art: logos, faction marks, icons, item cards, ability badges, cockpit decals, GUI panels, title art.
Existing-image edits, style variants, cleanup, palette alignment, or concept sheet refinements.

For premium/AAA/showcase graphics work, generate at least one relevant image for high-value 2D surfaces or image-to-3D inputs unless the credential probe or a real generation attempt shows a blocker.

当Three.js游戏需要以下资源时，优先使用该技能，而非仅依赖程序化生成的备选方案：

用于
```
threejs-3d-generator
```
的2D转3D参考图像：角色、生物、建筑、飞船、车辆、武器、道具、可拾取物品、地形模块。
纹理与材质参考图：地形、道路、岩石、沙地、金属、科幻面板、装饰板、贴花、警示标识、标牌。
环境图像：天空、背景、城市天际线、星云图、菜单背景、视差图层。
UI美术资源：标志、阵营标识、图标、物品卡片、技能徽章、驾驶舱贴花、GUI面板、标题美术图。
现有图像的编辑、风格变体制作、清理、调色统一或概念图优化。

对于高品质/AAA级/展示级图形工作，除非凭证探测或实际生成尝试显示存在障碍，否则应为高价值的2D表面或图像转3D输入素材至少生成一张相关图像。

API Key

API密钥

Never store API keys in skill files or browser/game code, and never paste a key value into a report. The script reads

--api-key

GEMINI_API_KEY

Step 0, before declaring the key unavailable: run this skill's own probe and paste its literal output into the report.

bash

uv run <this-skill-dir>/scripts/generate_image.py probe   # prints GEMINI_API_KEY=SET|MISSING

GEMINI_API_KEY=MISSING

is only a valid skip/blocker reason when this output is shown. Keys defined only in a shell profile can be absent from the process env; if the plain probe prints MISSING unexpectedly, wrap it:

zsh -lc 'source ~/.zprofile 2>/dev/null || true; source ~/.zshrc 2>/dev/null || true; uv run <this-skill-dir>/scripts/generate_image.py probe'

. When the director skill is loaded, prefer

threejs-game-director/scripts/probe_asset_credentials.sh

, which probes all three asset keys at once.

切勿将API密钥存储在技能文件或浏览器/游戏代码中，也切勿将密钥值粘贴到报告中。脚本会读取

--api-key

参数或

GEMINI_API_KEY

环境变量。

在声明密钥不可用之前，请先执行步骤0：运行该技能的探测脚本，并将其输出原样粘贴到报告中。

bash

uv run <this-skill-dir>/scripts/generate_image.py probe   # 输出 GEMINI_API_KEY=SET|MISSING

只有当探测输出显示

GEMINI_API_KEY=MISSING

时，才是有效的跳过/阻塞理由。仅在shell配置文件中定义的密钥可能不会出现在进程环境中；如果探测意外输出MISSING，请用以下命令包裹执行：

zsh -lc 'source ~/.zprofile 2>/dev/null || true; source ~/.zshrc 2>/dev/null || true; uv run <this-skill-dir>/scripts/generate_image.py probe'

。当加载了主管技能时，优先使用

threejs-game-director/scripts/probe_asset_credentials.sh

，它可以一次性探测所有三个资产密钥。

Tool Script

工具脚本

Run from the user's current project directory so output lands in the game project:

bash

uv run <this-skill-dir>/scripts/generate_image.py --prompt "your image description" --filename assets/concepts/output.png --resolution 2K

Edit an existing image:

bash

uv run <this-skill-dir>/scripts/generate_image.py \
  --input-image assets/concepts/ship.png \
  --prompt "turn this into a battle-worn red racing livery with clearer material zones" \
  --filename assets/concepts/ship-red-livery.png \
  --resolution 2K

Resolution mapping:

```
1K
```
: quick concepts, icons, draft sheets.
```
2K
```
: default production reference for image-to-3D, textures, backgrounds, UI panels. This is also the script default when
```
--resolution
```
is omitted.
```
4K
```
: hero splash/title art, high-detail texture references, large sky/background plates.

从用户当前的项目目录运行脚本，以便输出文件保存到游戏项目中：

bash

uv run <this-skill-dir>/scripts/generate_image.py --prompt "你的图像描述" --filename assets/concepts/output.png --resolution 2K

编辑现有图像：

bash

uv run <this-skill-dir>/scripts/generate_image.py \
  --input-image assets/concepts/ship.png \
  --prompt "将其转换为带有清晰材质区域的战损风格红色赛车涂装" \
  --filename assets/concepts/ship-red-livery.png \
  --resolution 2K

分辨率对应关系：

```
1K
```
：快速概念图、图标、草稿图。
```
2K
```
：图像转3D、纹理、背景、UI面板的默认生产级参考图。当省略
```
--resolution
```
参数时，脚本默认使用此分辨率。
```
4K
```
：主角展示/标题美术图、高细节纹理参考图、大型天空/背景板。

Prompt Patterns

提示词模板

Image-to-3D reference:

text

Create a clean 3D-generation reference image of [asset]. Centered single object, full object visible, plain light background, readable silhouette, clear material zones, game-ready [genre/style], no motion blur, no cropped parts, no text.

Riggable character/creature reference:

text

Create a full-body [T-pose/A-pose/side-view creature] reference for 3D rigging: [details]. Symmetric stance, visible hands/feet/limbs, plain background, readable costume/anatomy layers, no weapon fused to hands.

Texture/material reference:

text

Create a seamless game texture reference for [surface]. Orthographic/top-down, PBR-friendly albedo, clear material variation, no perspective, no baked strong shadows, [style/material details].

Logo/icon/UI art:

text

Create a crisp game UI [logo/icon/badge/panel] for [faction/item/ability]. Transparent-friendly silhouette, high contrast at small size, [genre styling], no tiny unreadable text.

Sky/background:

text

Create a wide game background plate of [environment]. Layered depth, readable horizon, [time/weather/style], suitable behind a real-time Three.js scene, no foreground subject.

图像转3D参考图：

text

创建一张用于3D生成的清晰参考图：[资产名称]。居中单个物体，完整显示，浅色纯色背景，轮廓清晰，材质区域分明，符合游戏就绪的[风格/流派]，无运动模糊，无裁切部分，无文字。

可绑定骨骼的角色/生物参考图：

text

创建一张用于3D绑定的全身[T字姿势/A字姿势/侧面视图生物]参考图：[细节描述]。姿势对称，手部/脚部/肢体可见，纯色背景，服装/解剖层次清晰，武器未与手部融合。

纹理/材质参考图：

text

创建一张用于[表面类型]的无缝游戏纹理参考图。正交/俯视图，符合PBR标准的基础色，材质变化清晰，无透视效果，无强烈烘焙阴影，[风格/材质细节]。

标志/图标/UI美术资源：

text

创建一张用于[阵营/物品/技能]的清晰游戏UI[标志/图标/徽章/面板]。适合透明背景的轮廓，小尺寸下对比度高，[流派风格]，无难以辨认的微小文字。

天空/背景：

text

创建一张用于[环境]的宽幅游戏背景板。层次分明，地平线清晰，[时间/天气/风格]，适合作为实时Three.js场景的背景，无前景主体。

Three.js Integration Rules

Three.js 集成规则

Save concepts and image-to-3D sources under
```
assets/concepts/
```
.
Save textures, decals, icons, and GUI source images under
```
assets/textures/
```
,
```
assets/decals/
```
, or
```
assets/ui/
```
.
For image-to-3D, hand the saved image path to
```
threejs-3d-generator
```
and record the chain in the external asset ledger.
Do not call the image API from client-side game code.
Convert generated PNGs into runtime formats deliberately: PNG for alpha/UI, JPG/WebP/KTX2 for larger opaque textures where the project pipeline supports it.
Verify how the image appears in game, not only that the file exists.

将概念图和图像转3D源文件保存到
```
assets/concepts/
```
目录下。
将纹理、贴花、图标和GUI源图像保存到
```
assets/textures/
```
、
```
assets/decals/
```
或
```
assets/ui/
```
目录下。
对于图像转3D任务，将保存的图像路径提交给
```
threejs-3d-generator
```
，并在外部资产台账中记录该流程。
切勿从客户端游戏代码中调用图像API。
有意将生成的PNG转换为运行时格式：PNG用于带透明通道的UI资源，JPG/WebP/KTX2用于大型不透明纹理（若项目流水线支持）。
验证图像在游戏中的显示效果，而不仅仅是确认文件存在。

Required Report

必需报告内容

Report:

Credential probe output or command blocker.
Prompt and purpose.
Output path.
Resolution.
Whether the image was used directly, edited further, or handed to
```
threejs-3d-generator
```
.
Any remaining integration work such as compression, UV assignment, alpha cleanup, or atlas packing.

Do not mark a premium graphics phase complete if the needed image outputs are missing and the only justification is "procedural is enough" for high-value UI, texture, sky, decal, logo, or image-to-3D surfaces.

报告需包含：

凭证探测输出或命令阻塞原因。
提示词及用途。
输出路径。
分辨率。
图像是直接使用、进一步编辑，还是提交给
```
threejs-3d-generator
```
。
任何剩余的集成工作，例如压缩、UV分配、透明通道清理或图集打包。

如果高价值的UI、纹理、天空、贴花、标志或图像转3D表面所需的图像输出缺失，且唯一理由是“程序化生成足够用”，则不得标记高品质图形阶段完成。