add-3d-assets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add 3D Assets

添加3D资源

Replace basic geometric shapes (BoxGeometry, SphereGeometry) with real 3D models. The player gets an animated character with idle/walk/run animations. World objects get GLB models from free libraries.

将基础几何形状（BoxGeometry、SphereGeometry）替换为真实3D模型。玩家将拥有一个包含 idle/walk/run 动画的角色。世界对象将使用来自免费库的GLB模型。

Instructions

操作步骤

Analyze the game at

$ARGUMENTS

(or the current directory if no path given).

First, load the game-3d-assets skill for the full model pipeline, AssetLoader pattern, and integration patterns.

分析

$ARGUMENTS

路径下的游戏（如果未指定路径则分析当前目录）。

首先，加载game-3d-assets技能以获取完整的模型流水线、AssetLoader模式和集成模式。

Step 1: Audit

步骤1：审计

Read
```
package.json
```
to confirm this is a Three.js game (not Phaser — use
```
/add-assets
```
for 2D games)
Read
```
src/core/Constants.js
```
for entity types, sizes, colors

Read entity files (

src/gameplay/*.js

src/entities/*.js

) — find

BoxGeometry

SphereGeometry

, etc.

Read
```
src/level/LevelBuilder.js
```
for environment primitives
List every entity using geometric shapes
Identify which entity is the player character (needs animated model)

读取
```
package.json
```
确认这是一个Three.js游戏（如果是Phaser游戏，请使用
```
/add-assets
```
处理2D游戏）
读取
```
src/core/Constants.js
```
获取实体类型、尺寸、颜色信息
读取实体文件（
```
src/gameplay/*.js
```
、
```
src/entities/*.js
```
）——查找
```
BoxGeometry
```
、
```
SphereGeometry
```
等基础形状的使用
读取
```
src/level/LevelBuilder.js
```
查看环境基础形状
列出所有使用几何形状的实体
确定哪个实体是玩家角色（需要动画模型）

Step 2: Plan

步骤2：规划

Split entities into two categories:

Animated characters (player, enemies with AI) — use pre-built GLBs from

3d-character-library/

Entity	Character	Reason
Player	Soldier	Military/action theme
Enemy	RobotExpressive	Sci-fi theme, 13 animations

Available characters in

3d-character-library/manifest.json

Soldier — realistic military (Idle, Walk, Run) — best default
Xbot — stylized mannequin (idle, walk, run + additive poses)
RobotExpressive — cartoon robot (Idle, Walking, Running, Dance, Jump + 8 more)
Fox — low-poly animal (Survey, Walk, Run) — scale 0.02

World objects (buildings, props, scenery, collectibles) — search free libraries:

Entity	Search Query	Source	Notes
Tree	"low poly tree"	Sketchfab	Environment
House	"medieval house"	Poly Haven	Background
Barrel	"barrel"	Poly Haven	Obstacle
Coin	"gold coin"	Sketchfab	Collectible

将实体分为两类：

动画角色（玩家、带AI的敌人）——使用

3d-character-library/

中的预构建GLB模型：

实体	角色	原因
玩家	Soldier	军事/动作主题
敌人	RobotExpressive	科幻主题，包含13种动画

3d-character-library/manifest.json

中可用的角色：

Soldier — 写实风格军事角色（Idle、Walk、Run）——最佳默认选择
Xbot — 风格化人体模型（idle、walk、run + 附加姿态）
RobotExpressive — 卡通风格机器人（Idle、Walking、Running、Dance、Jump + 另外8种动画）
Fox — 低多边形动物（Survey、Walk、Run）——缩放比例0.02

世界对象（建筑、道具、场景、可收集物品）——在免费库中搜索：

实体	搜索关键词	来源	说明
树木	"low poly tree"	Sketchfab	环境元素
房屋	"medieval house"	Poly Haven	背景元素
木桶	"barrel"	Poly Haven	障碍物
金币	"gold coin"	Sketchfab	可收集物品

Step 3: Download

步骤3：下载

Characters — copy from library (no auth, instant):

bash

undefined

角色模型——从库中复制（无需授权，即时获取）：

bash

undefined

Find the plugin root (where 3d-character-library/ lives)

找到插件根目录（3d-character-library/所在位置）

cp <plugin-root>/3d-character-library/models/Soldier.glb public/assets/models/


**World objects** — search and download:
```bash

cp <plugin-root>/3d-character-library/models/Soldier.glb public/assets/models/


**世界对象模型**——搜索并下载：
```bash

Use --list-only first to review results

先使用--list-only参数查看结果

node <plugin-root>/scripts/find-3d-asset.mjs --query "barrel" --source polyhaven --list-only

Download the best match

下载最匹配的模型

node <plugin-root>/scripts/find-3d-asset.mjs --query "barrel" --source polyhaven
--output public/assets/models/ --slug barrel

Poly Haven = no auth, CC0 (best for props)

Poly Haven = 无需授权，CC0协议（最适合道具）

Sketchfab = search free, download needs SKETCHFAB_TOKEN

Sketchfab = 免费搜索，下载需要SKETCHFAB_TOKEN

undefined

undefined

Step 4: Integrate

步骤4：集成

Create

src/level/AssetLoader.js

— use
SkeletonUtils.clone()
for animated models (import from

three/addons/utils/SkeletonUtils.js

). Regular

.clone()

breaks skeleton → T-pose.

Add
```
CHARACTER
```
to Constants.js with
```
path
```
,
```
scale
```
,
```
facingOffset
```
,
```
clipMap
```
Add
```
ASSET_PATHS
```
and
```
MODEL_CONFIG
```
for static models

Update

Player.js

```
THREE.Group
```
as position anchor
```
loadAnimatedModel()
```
+
```
AnimationMixer
```
```
fadeToAction()
```
for idle/walk/run crossfade
Camera-relative WASD via
```
applyAxisAngle(_up, cameraAzimuth)
```

Model facing:

atan2(v.x, v.z) + CHARACTER.facingOffset

model.quaternion.rotateTowards(targetQuat, turnSpeed * delta)

Update
```
Game.js
```
:
- Add
```
OrbitControls
```
  — third-person camera orbiting player
- Camera follows: move
```
orbitControls.target
```
  +
```
camera.position
```
  by player delta
- Pass
```
orbitControls.getAzimuthalAngle()
```
  to Player for camera-relative movement
Replace environment primitives with
```
loadModel()
```
calls +
```
.catch()
```
fallback
Add
```
THREE.GridHelper
```
for visible movement reference
Preload all models on startup with
```
preloadAll()
```
for instant loading

创建
```
src/level/AssetLoader.js
```
——对于动画模型，请使用
SkeletonUtils.clone()
（从
```
three/addons/utils/SkeletonUtils.js
```
导入）。常规的
```
.clone()
```
会破坏骨骼结构，导致角色呈T字姿势。
在Constants.js中添加
```
CHARACTER
```
配置，包含
```
path
```
、
```
scale
```
、
```
facingOffset
```
、
```
clipMap
```
为静态模型添加
```
ASSET_PATHS
```
和
```
MODEL_CONFIG
```
配置

更新

Player.js

：

使用
```
THREE.Group
```
作为位置锚点
实现
```
loadAnimatedModel()
```
+
```
AnimationMixer
```
使用
```
fadeToAction()
```
实现idle/walk/run动画的平滑过渡
通过
```
applyAxisAngle(_up, cameraAzimuth)
```
实现基于相机视角的WASD移动

模型朝向：

atan2(v.x, v.z) + CHARACTER.facingOffset

model.quaternion.rotateTowards(targetQuat, turnSpeed * delta)

更新
```
Game.js
```
：
- 添加
```
OrbitControls
```
  ——围绕玩家的第三人称相机
- 相机跟随：根据玩家的位移量更新
```
orbitControls.target
```
  +
```
camera.position
```
- 将
```
orbitControls.getAzimuthalAngle()
```
  传递给Player，实现基于相机视角的移动
使用
```
loadModel()
```
调用替换环境基础形状，并添加
```
.catch()
```
作为回退方案
添加
```
THREE.GridHelper
```
作为可见的移动参考
在启动时使用
```
preloadAll()
```
预加载所有模型，实现即时加载

Step 5: Tune & Verify

步骤5：调整与验证

Run
```
npm run dev
```
— walk around with WASD, orbit camera with mouse
Confirm character animates (Idle when stopped, Walk when moving, Run with Shift)
Adjust
```
MODEL_CONFIG
```
values (scale, rotationY, offsetY) per model
Run
```
npm run build
```
to confirm no errors
Generate
```
ATTRIBUTION.md
```
from
```
.meta.json
```
files

运行
```
npm run dev
```
——使用WASD移动，鼠标拖动旋转相机
确认角色动画正常（静止时为Idle，移动时为Walk，按住Shift时为Run）
根据每个模型调整
```
MODEL_CONFIG
```
中的值（scale、rotationY、offsetY）
运行
```
npm run build
```
确认无错误
从.meta.json文件生成
```
ATTRIBUTION.md
```

Next Step

下一步

Tell the user:

Your 3D game now has animated characters and real models! The player walks, runs, and idles with smooth animation crossfading. World objects are loaded from GLB files.

Files created:
src/level/AssetLoader.js
— model loader with SkeletonUtils
public/assets/models/
— character and world GLB models
OrbitControls third-person camera
Controls: WASD to move, Shift to run, mouse drag to orbit camera, scroll to zoom. Run the game to see everything in action. Adjust
MODEL_CONFIG
in Constants.js to fine-tune scale and orientation.

告知用户：

你的3D游戏现在拥有动画角色和真实模型了！玩家可以通过平滑的动画过渡实现行走、奔跑和 idle 状态。世界对象均从GLB文件加载。

创建的文件：
src/level/AssetLoader.js
— 集成SkeletonUtils的模型加载器
public/assets/models/
— 角色和世界对象的GLB模型
第三人称相机OrbitControls
操作方式： WASD移动，Shift奔跑，鼠标拖动旋转相机，滚轮缩放。运行游戏查看效果。可在Constants.js中调整
MODEL_CONFIG
来优化模型的缩放和朝向。