A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
docs(materials): describe imported shading workflows and depth
yhhdf416f478ece
diff --git a/docs/astro/src/content/docs/assets/models.mdx b/docs/astro/src/content/docs/assets/models.mdxindex 0d5855bae..521c16c29 100644--- a/docs/astro/src/content/docs/assets/models.mdx+++ b/docs/astro/src/content/docs/assets/models.mdx@@ -192,11 +192,12 @@ component has no room for. Written only when the source uses one of them, on the| glTF | Material parameter ||---|---|-| `normalTexture` | `u_normalMap` |+| `normalTexture` / `normalTexture.scale` | `u_normalMap` / `u_normalScale` (default 1) || `emissiveFactor` / `emissiveTexture` | `u_emissive` / `u_emissiveMap` || `occlusionTexture` (+ `strength`) | `u_occlusionMap` / `u_occlusionStrength` || `alphaMode: MASK` + `alphaCutoff` | `u_alphaCutoff` || `metallicFactor` / `roughnessFactor` / `metallicRoughnessTexture` | `u_metallic` / `u_roughness` / `u_metallicRoughnessMap` |+| `KHR_materials_pbrSpecularGlossiness` | Model variant `ES_SPECULAR_GLOSSINESS`; `u_specularColor`, `u_glossiness`, and the packed map in `u_metallicRoughnessMap` || `KHR_materials_clearcoat` | `u_clearcoat` / `u_clearcoatRoughness` || `KHR_materials_sheen` | `u_sheenColor` / `u_sheenRoughness` || `KHR_materials_anisotropy` | `u_anisotropy` / `u_anisotropyRotation` |@@ -209,6 +210,19 @@ Metal and roughness are written even when they match the engine's own defaults:defaults both factors to 1 (a fully rough metal) and the shader defaults metal to 0, so aproduct that left them out would describe a surface the source did not.+For a legacy specular/glossiness material, its diffuse texture and factor replace+the metallic/roughness fallback's base colour on `MeshRenderer`. Its specular RGB+and glossiness alpha use the same native lighting path as other Model materials;+RGB is decoded from sRGB, alpha stays linear, and roughness is `1 - glossiness`.+The packed map reuses the existing sampler slot. Character-name presets do not+replace this explicitly authored workflow. New authoring can use metallic/roughness;+this variant preserves existing glTF exports without an approximate conversion.++Normal strength scales the tangent-space X/Y channels before normalization, on+Model, Skin and Hair materials. Zero produces a flat normal; negative values invert+the relief. Blended model materials test depth against opaque geometry while leaving+depth writes off, so transparent leaves behind a wall remain behind it.+A texture the material names that is not in the project (the file is missing next to themodel) is left off: the model imports without it and a warning says so, instead of keeping areference that fails to load on every use.@@ -337,7 +351,6 @@ when it runs.|---|---|| A material texture that asks for `TEXCOORD_1`, a `KHR_texture_transform` that offsets, scales or rotates, an FBX uv transform | A material samples the first UV set as authored. (The mesh itself keeps its second UV set, which a lightmap or a material's `v_texCoord1` can read.) || Non-triangle primitives (`mode` ≠ 4) | The renderer draws triangle lists. |-| `normalTexture.scale` | The map is applied at full strength. || The textures of a shading layer (`clearcoatTexture`, `sheenColorTexture`, `anisotropyTexture`, …), `specularColorFactor`, `attenuationDistance` | Each layer is a constant for the whole material; its factors are kept and the textures are reported. See [Shading layers](/docs/graphics/materials/#shading-layers). || Area and volume lights | Named in the import notes and skipped. (Point, directional and spot lights, and cameras, **are** imported: see [Lights and cameras](#lights-and-cameras).) || Separate FBX metalness/roughness maps, an FBX opacity map | See [FBX](#fbx). |diff --git a/docs/astro/src/content/docs/zh-cn/assets/models.mdx b/docs/astro/src/content/docs/zh-cn/assets/models.mdxindex 183e26a6f..737da72c4 100644--- a/docs/astro/src/content/docs/zh-cn/assets/models.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/models.mdx@@ -164,11 +164,12 @@ chart,每片投影到自己的平面,再按**同一个**世界-纹素比打包| glTF | 材质参数 ||---|---|-| `normalTexture` | `u_normalMap` |+| `normalTexture` / `normalTexture.scale` | `u_normalMap` / `u_normalScale`(默认 1) || `emissiveFactor` / `emissiveTexture` | `u_emissive` / `u_emissiveMap` || `occlusionTexture`(含 `strength`) | `u_occlusionMap` / `u_occlusionStrength` || `alphaMode: MASK` + `alphaCutoff` | `u_alphaCutoff` || `metallicFactor` / `roughnessFactor` / `metallicRoughnessTexture` | `u_metallic` / `u_roughness` / `u_metallicRoughnessMap` |+| `KHR_materials_pbrSpecularGlossiness` | Model 变体 `ES_SPECULAR_GLOSSINESS`;`u_specularColor`、`u_glossiness`,打包贴图使用 `u_metallicRoughnessMap` || `KHR_materials_clearcoat` | `u_clearcoat` / `u_clearcoatRoughness` || `KHR_materials_sheen` | `u_sheenColor` / `u_sheenRoughness` || `KHR_materials_anisotropy` | `u_anisotropy` / `u_anisotropyRotation` |@@ -180,6 +181,15 @@ chart,每片投影到自己的平面,再按**同一个**世界-纹素比打包金属度与粗糙度即使等于引擎自己的默认值也会写出来:glTF 把两个系数都默认成 1(完全粗糙的金属),而 shader 把金属度默认成 0 —— 省略它们的产物会描述出一个源文件没有说过的表面。+旧版高光/光泽材质会把自身的漫反射贴图和系数写入 `MeshRenderer`,覆盖金属/粗糙度后备材质的+base color。高光 RGB 与光泽 alpha 共用原生 Model 光照路径:RGB 从 sRGB 解码,alpha 保持线性,+粗糙度为 `1 - 光泽度`。打包贴图复用已有采样槽,不增加采样器。按名称选择角色材质的设置不会+覆盖这个明确指定的工作流。新资源可以采用金属/粗糙度;此变体用于保留已有 glTF 的材质语义,+无需近似转换。++法线强度在归一化前缩放切线空间的 X/Y 通道,适用于 Model、Skin、Hair 材质。0 表示平法线,+负值反转凹凸。混合透明模型仍对不透明几何进行深度测试,但不写深度,因此墙后的叶片不会盖到墙上。+材质里写的贴图如果项目里没有这个文件(模型旁边找不到),就不会绑上它:模型照常导入并给出警告,而不是留下一个每次使用都加载失败的引用。材质还会把这次 draw 的混合、深度和剔除重述一遍 —— 因为材质会**替换**它们,@@ -293,7 +303,6 @@ Physical、Blender 的 Principled 最终都落到[材质](#材质)那一节列|---|---|| 材质贴图要求用 `TEXCOORD_1`、带偏移/缩放/旋转的 `KHR_texture_transform`、FBX 的 uv transform | 材质按作者写的原样读第一套 UV。(mesh 本身保留第二套 UV,光照贴图或材质的 `v_texCoord1` 可以读它。) || 非三角形 primitive(`mode` ≠ 4) | 渲染器画的是三角形列表。 |-| `normalTexture.scale` | 法线贴图按全强度应用。 || 着色层的贴图(`clearcoatTexture`、`sheenColorTexture`、`anisotropyTexture` 等)、`specularColorFactor`、`attenuationDistance` | 每一层对整个材质是一个常量;系数保留,贴图只做报告。见[着色层](/docs/zh-cn/graphics/materials/#着色层)。 || 面光与体积光 | 在导入提示里点名并跳过。(点光、方向光、聚光灯以及相机**会**导入:见[灯光与相机](#灯光与相机)。) || FBX 分离的金属度/粗糙度贴图、FBX 的不透明度贴图 | 见 [FBX](#fbx)。 |