threejs-objects

---
name: "threejs-objects"
description: "ALWAYS use this skill when the user mentions:"
license: "BSD-2-Clause"
---

## When to use this skill

**ALWAYS use this skill when the user mentions:**

- Parent/child relationships, `position/rotation/scale`, `matrixAutoUpdate`, `updateMatrixWorld`
- Choosing mesh types: static vs instanced vs skinned vs batched LOD
- **Picking**: `Raycaster.setFromCamera`, `intersectObjects`, recursive flag, face/uv results
- **Layers**: selective visibility for cameras/lights/objects

**IMPORTANT: objects vs math**

| Need | Skill |
|------|--------|
| Scene graph + picking | **threejs-objects** |
| Box/ray math only | **threejs-math** |

**Trigger phrases include:**

- "Object3D", "InstancedMesh", "SkinnedMesh", "Raycaster", "layers"
- "父子节点", "射线拾取", "图层"

## How to use this skill

1. **Compose** scenes with `Group` and transforms; minimize deep hierarchies where possible.
2. **Instancing**: set per-instance matrices; understand `count` and frustum culling behavior.
3. **SkinnedMesh**: bind skeleton; clips in **threejs-animation**; skinning material flags in **threejs-materials**.
4. **Picking**: normalize device coords, set ray from camera, filter by layers, sort intersections.
5. **Events**: `EventDispatcher` on custom objects—patterns only, not DOM frameworks.
6. **Clipping**: `ClippingGroup` usage per docs when user needs sectional cuts.
7. **Dispose**: geometries/materials/textures when removing objects permanently.

See [examples/workflow-raycaster-pick.md](examples/workflow-raycaster-pick.md).

## Doc map (official)

| Docs section | Representative links |
|--------------|----------------------|
| Core | https://threejs.org/docs/Object3D.html |
| Objects | https://threejs.org/docs/Mesh.html |
| Objects | https://threejs.org/docs/InstancedMesh.html |
| Core | https://threejs.org/docs/Raycaster.html |

## Scope

- **In scope:** Object3D graph, renderable object types, raycasting, layers, dispatcher basics.
- **Out of scope:** Physics engines; XR input mapping (**threejs-webxr**).

## Common pitfalls and best practices

- Forgetting `updateMatrixWorld` before world-space ray tests on moved objects.
- Raycaster without `layers` set picks unintended objects—set masks consistently on camera and objects.
- InstancedMesh raycast hits need per-instance handling—check docs for your version.

## Documentation and version

`Object3D`, mesh types, `Raycaster`, and `Layers` are documented under [Objects](https://threejs.org/docs/#Objects) and [Core](https://threejs.org/docs/Raycaster.html) in [three.js docs](https://threejs.org/docs/). Behavior of picking and layers can shift slightly—link the exact page for the user’s three.js line.

## Agent response checklist

When answering under this skill, prefer responses that:

1. Link `Object3D`, `Mesh`, `InstancedMesh`, `Raycaster`, or `Layers` as needed.
2. Pair skeletal animation with **threejs-animation** and skinned mesh setup.
3. Route pure linear-algebra questions without a scene graph to **threejs-math**.
4. Route XR input to **threejs-webxr** when sessions/controllers are involved.
5. Mention `dispose()` for geometries/materials when removing objects permanently.

## References

- https://threejs.org/docs/Object3D.html
- https://threejs.org/docs/Raycaster.html
- https://threejs.org/docs/Layers.html
- https://threejs.org/docs/InstancedMesh.html

## Keywords

**English:** object3d, mesh, instancedmesh, skinnedmesh, raycaster, layers, scene graph, three.js

**中文：** 场景图、Object3D、Mesh、实例化、骨骼网格、射线拾取、图层、three.js

## 能力边界

### ✅ 适用场景
- 当你需要使用此技能对应的技术栈时
- 当项目需要遵循最佳实践时
- 当需要快速上手或深入理解核心概念时

### ⚠️ 需要注意
- 复杂业务逻辑需要结合具体场景调整
- 性能优化需要根据实际数据量评估

### ❌ 不适用场景
- 不相关的技术栈或框架
- 需要完全自定义的特殊场景

## 常见陷阱 (Gotchas)

1. **版本兼容性**：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
2. **配置文件格式**：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
3. **环境变量**：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
4. **依赖冲突**：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
5. **性能陷阱**：大数据量场景下注意性能优化，避免 N+1 查询等常见问题

## 使用流程

### Step 1: 环境准备
确保开发环境已安装必要的依赖和工具。

### Step 2: 配置初始化
根据项目需求进行基础配置。

### Step 3: 核心功能使用
按照示例代码实现核心功能。

### Step 4: 测试验证
运行测试确保功能正常。

### Step 5: 部署上线
完成开发后进行部署和监控。