threejs-materials

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用本技能

ALWAYS use this skill when the user mentions:

Choosing among built-in mesh materials, map slots (albedo, normal, roughness, metalness, ao, emissive),
```
envMap
```
Transparency sorting issues,
```
alphaTest
```
,
```
depthWrite
```
, blending modes, side/double-sided rendering
```
ShaderMaterial
```
/
```
RawShaderMaterial
```
uniforms, includes, and compatibility with lights pipeline
Line, points, sprite materials for vector overlays and particles

IMPORTANT: classic materials vs node-tsl

Need	Skill
Standard PBR with maps, physical clearcoat/sheen	threejs-materials
TSL nodes, `NodeMaterial` , WebGPU-first shading, compute-style graph	threejs-node-tsl
Migrating ShaderMaterial → TSL	threejs-node-tsl (conceptual), keep ShaderMaterial here until cutover

Trigger phrases include:

"MeshStandardMaterial", "MeshPhysicalMaterial", "ShaderMaterial", "transparent", "alphaTest"
"PBR", "物理材质", "透明", "自定义着色器"

当用户提到以下内容时，务必使用本技能：

在内置网格材质、贴图槽位（albedo、normal、roughness、metalness、ao、emissive）、
```
envMap
```
之间做选择
透明度排序问题、
```
alphaTest
```
、
```
depthWrite
```
、混合模式、单面/双面渲染
```
ShaderMaterial
```
/
```
RawShaderMaterial
```
的uniforms、includes以及与光照管线的兼容性
用于矢量叠加层和粒子的Line、points、sprite材质

重要提示：经典材质 vs node-tsl

需求	对应技能
带贴图的标准PBR、物理清漆/光泽效果	threejs-materials
TSL节点、 `NodeMaterial` 、WebGPU优先的着色、计算式着色图	threejs-node-tsl
从ShaderMaterial迁移到TSL	threejs-node-tsl（概念层面），切换前仍在此处处理ShaderMaterial相关问题

触发关键词包括：

"MeshStandardMaterial"、"MeshPhysicalMaterial"、"ShaderMaterial"、"transparent"、"alphaTest"
"PBR"、"物理材质"、"透明"、"自定义着色器"

How to use this skill

如何使用本技能

Select class by lighting model:
```
MeshBasic
```
(unlit), Lambert/Phong (legacy lit), Standard/Physical (PBR).
Assign maps and ensure color space correctness for albedo vs data maps (link threejs-textures).
Environment: set
```
envMap
```
from cube or equirect; align
```
metalness
```
/
```
roughness
```
; consider
```
MeshPhysicalMaterial
```
for transmission/IOR when needed.
Transparency: order objects or use
```
alphaTest
```
/
```
depthWrite
```
trade-offs; mention sorting limitations.
ShaderMaterial: minimize re-lit work unless intentional; document required lights and
```
lights: true
```
flag behavior per version docs.
Performance: share materials across meshes; avoid cloning per frame.
Skinning/morph: set
```
skinning
```
/
```
morphTargets
```
where applicable—mesh side in threejs-objects.

See examples/workflow-pbr-transparent.md.

根据光照模型选择材质类：
```
MeshBasic
```
（无光照）、Lambert/Phong（传统光照）、Standard/Physical（PBR）。
分配贴图，确保albedo贴图与数据贴图的色彩空间正确（关联threejs-textures技能）。
环境设置：从立方体贴图或等距柱状贴图设置
```
envMap
```
；匹配
```
metalness
```
/
```
roughness
```
参数；必要时考虑使用
```
MeshPhysicalMaterial
```
实现透射/IOR效果。
透明度处理：调整物体渲染顺序，或权衡
```
alphaTest
```
/
```
depthWrite
```
的使用；需说明排序的局限性。
ShaderMaterial使用：除非刻意为之，否则尽量避免重新编写光照逻辑；需根据版本文档说明所需光照以及
```
lights: true
```
标志的行为。
性能优化：在多个网格间共享材质；避免每帧克隆材质。
蒙皮/形变：在适用场景下设置
```
skinning
```
/
```
morphTargets
```
——网格侧面相关问题参考threejs-objects技能。

参见examples/workflow-pbr-transparent.md。

Doc map (official)

文档导航（官方）

Docs section	Representative links
Materials (core)	https://threejs.org/docs/Material.html
PBR	https://threejs.org/docs/MeshStandardMaterial.html
Physical	https://threejs.org/docs/MeshPhysicalMaterial.html
Custom GLSL	https://threejs.org/docs/ShaderMaterial.html

文档板块	代表性链接
核心材质	https://threejs.org/docs/Material.html
PBR材质	https://threejs.org/docs/MeshStandardMaterial.html
物理材质	https://threejs.org/docs/MeshPhysicalMaterial.html
自定义GLSL	https://threejs.org/docs/ShaderMaterial.html

Scope

适用范围

In scope: Non-Node materials listed under Core Materials in docs (except
```
*NodeMaterial
```
).
Out of scope: Full Nodes catalog (threejs-node-tsl); post pass materials inside composer (threejs-postprocessing).

适用范围： 文档核心材质分类下的非Node材质（
```
*NodeMaterial
```
除外）。
不适用范围： 完整Nodes体系（threejs-node-tsl技能）；合成器中的后处理通道材质（threejs-postprocessing技能）。

Common pitfalls and best practices

常见陷阱与最佳实践

Wrong normal map
```
normalMapType
```
or tangent space breaks lighting; verify geometry has tangents or use appropriate mode.
Premultiplied alpha vs straight alpha mismatches cause fringe halos on foliage.
```
MeshPhysicalMaterial
```
```
transmission
```
needs thickness and good env—combine with threejs-textures / PMREM.
Too many unique materials hurts sorting and batching—merge where possible.

法线贴图的
```
normalMapType
```
或切线空间设置错误会破坏光照效果；需验证几何体是否包含切线，或使用合适的模式。
预乘alpha与直alpha不匹配会导致植物等物体出现边缘光晕。
```
MeshPhysicalMaterial
```
的
```
transmission
```
属性需要厚度参数和良好的环境贴图——需结合threejs-textures技能/PMREM使用。
过多独立材质会影响排序和批处理性能——尽可能合并材质。

Documentation and version

文档与版本说明

PBR and

ShaderMaterial

behavior track the Materials section in three.js docs. Color management and default

envMap

handling changed in modern releases—always pair material answers with renderer/output settings from threejs-renderers when colors look wrong.

PBR和

ShaderMaterial

的行为以three.js官方文档中的材质板块为准。现代版本中色彩管理和默认

envMap

处理方式有所变更——当颜色显示异常时，务必结合threejs-renderers技能中的渲染器/输出设置一并解答。

Agent response checklist

Agent回复检查清单

When answering under this skill, prefer responses that:

Link

MeshStandardMaterial

MeshPhysicalMaterial

, or

ShaderMaterial

pages as appropriate.

Force a clear choice vs threejs-node-tsl when the user asks for “shaders” or “nodes”.
Separate map roles (albedo vs roughness vs normal) and
```
colorSpace
```
expectations with threejs-textures.
Call out transparency and
```
depthWrite
```
trade-offs for sorted rendering.
Note that
```
*NodeMaterial
```
types belong to the node skill, not this one.

在本技能范围内作答时，回复应优先满足以下要求：

视情况链接

MeshStandardMaterial

、

MeshPhysicalMaterial

或

ShaderMaterial

的官方文档页面。

当用户询问“着色器”或“节点”相关内容时，需明确区分本技能与threejs-node-tsl的适用场景，给出清晰的选择建议。
结合threejs-textures技能，区分不同贴图的作用（albedo、roughness、normal等）以及对应的
```
colorSpace
```
要求。
说明排序渲染中透明度与
```
depthWrite
```
的权衡关系。
明确
```
*NodeMaterial
```
类型属于节点技能的范畴，不在本技能范围内。

References

参考资料

Keywords

关键词

English: meshstandardmaterial, meshphysicalmaterial, shadermaterial, pbr, transparency, envmap, materials, three.js

中文： 材质、PBR、MeshStandardMaterial、物理材质、透明、环境贴图、ShaderMaterial、three.js

English: meshstandardmaterial, meshphysicalmaterial, shadermaterial, pbr, transparency, envmap, materials, three.js

中文： 材质、PBR、MeshStandardMaterial、物理材质、透明、环境贴图、ShaderMaterial、three.js

能力边界

✅ 适用场景

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

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

⚠️ 需要注意

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

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

❌ 不适用场景

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

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

常见陷阱 (Gotchas)

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

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

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

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