threejs-objects

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.

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 and Core in three.js 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: 部署上线

完成开发后进行部署和监控。