Skip to content

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.

docs(assets): a page for importing models

esengine12eff5f89fa8
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index a00306243..83f5bd353 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -294,6 +294,7 @@ export default defineConfig({
items: [
{ label: 'Overview', translations: { 'zh-CN': '总览' }, slug: 'assets/overview' },
{ label: 'Textures', translations: { 'zh-CN': '纹理' }, slug: 'assets/textures' },
+ { label: 'Models', translations: { 'zh-CN': '模型' }, slug: 'assets/models' },
{ label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'assets/audio' },
{ label: 'Localization', translations: { 'zh-CN': '本地化' }, slug: 'assets/localization' },
],
diff --git a/docs/astro/src/content/docs/assets/models.mdx b/docs/astro/src/content/docs/assets/models.mdx
new file mode 100644
index 000000000..2a7c81fe9
--- /dev/null
+++ b/docs/astro/src/content/docs/assets/models.mdx
@@ -0,0 +1,126 @@
+---
+title: Models
+description: Importing glTF/GLB — what the import writes, how a model reaches a scene, the Scale setting, re-importing, which material channels become an .esmaterial, Draco and meshopt, and what is reported rather than imported.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The engine draws meshes, and it loads exactly one mesh format: `.esmesh`. A `.gltf` or
+`.glb` is a **source**, not an asset — bringing one into a project runs an import that
+writes the assets a scene can actually reference.
+
+That import is the subject of this page. For the component that draws the result see
+[the component reference](/docs/reference/components/graphics/); for materials in general see
+[Materials](/docs/graphics/materials/).
+
+## Importing a model
+
+Three doors, one import:
+
+| How | What happens |
+|---|---|
+| Drag a `.gltf`/`.glb` onto the Content Browser | The source is copied in (with the files it points at) and imported. |
+| Put one in the project folder | The editor notices and imports it — a `git checkout`, a copy in Finder, a re-export from Blender. |
+| `estella import-gltf <file> [outDir] --project <dir>` | The same import, on the command line. `--scale <n>` sizes it. |
+
+Products land **beside the source**, not in whatever folder the browser is showing:
+re-importing has to overwrite the same files.
+
+## What the import writes
+
+For `robot.gltf` with two primitives and one image:
+
+| Product | What it is |
+|---|---|
+| `robot_0_0.esmesh`, `robot_1_0.esmesh` | One per primitive — geometry, named `<stem>_<mesh>_<primitive>` (just `<stem>` for a single one). |
+| `robot_0.png` | Images the file carries inline. An image already on disk is referenced, never copied. |
+| `robot_m0.esmaterial` | Only when the source's material says something a `Mesh2D` cannot — see [Materials](#materials). |
+| `robot.esprefab` | How the pieces go together: the node hierarchy, each `Mesh2D` with its mesh, texture, tint and flags. |
+
+Drag the **prefab** into a scene. The individual `.esmesh` files are assets too — a
+`Mesh2D.mesh` field takes one directly — but the prefab is the model as authored.
+
+<Aside type="caution" title="Products are rewritten">
+Re-importing replaces every product. Edits made to a generated `.esprefab` are lost;
+place an instance in a scene and edit that instead.
+</Aside>
+
+## Scale
+
+A glTF is authored in **metres**. A world unit is a **design pixel**. A 1.7 m character
+therefore arrives 1.7 units tall — a couple of pixels — unless you say otherwise.
+
+The import does not guess a factor. It tells you when a model came in small, and the
+number that fixes it is `Scale` in the source's Import Settings (select the `.gltf` in the
+Content Browser). Saving it re-imports the model.
+
+`Scale` lands on the prefab root's `Transform`, never baked into the geometry — the
+`.esmesh` stays faithful to the source, and the number stays visible and editable.
+
+## Re-importing
+
+An import runs again when:
+
+- the source file changes (re-exported over the top of the old one);
+- **Reimport** is chosen on it in the Content Browser;
+- an import setting is saved.
+
+Asset uuids survive, so scenes and prefabs that reference the products keep working.
+
+## Materials
+
+A glTF material is split by what can carry it.
+
+**On the `Mesh2D` component** — base colour, because that is what the engine's mesh path
+already is (`texture(uv) × vertexColor × tint`):
+
+| glTF | Component field |
+|---|---|
+| `baseColorTexture` | `texture` |
+| `baseColorFactor` | `color` |
+| `alphaMode` ≠ `BLEND` | `opaque` |
+| `doubleSided: false` | `cullBackfaces` |
+| a `NORMAL` attribute | `lit: true` |
+
+**In an `.esmaterial`** — shading, which is per-material constants and samplers a
+component has no room for. Written only when the source uses one of them, on the built-in
+**Model** shader:
+
+| glTF | Material parameter |
+|---|---|
+| `normalTexture` | `u_normalMap` |
+| `emissiveFactor` / `emissiveTexture` | `u_emissive` / `u_emissiveMap` |
+| `occlusionTexture` (+ `strength`) | `u_occlusionMap` / `u_occlusionStrength` |
+| `alphaMode: MASK` + `alphaCutoff` | `u_alphaCutoff` |
+
+The material also restates the draw's blending, depth and culling, because a material
+replaces them — a model told to occlude itself keeps doing so through its material.
+
+## Compressed geometry
+
+`EXT_meshopt_compression` and `KHR_draco_mesh_compression` are decoded during import, so a
+compressed export produces the same `.esmesh` as an uncompressed one. Nothing about the
+runtime changes: compression is a property of the source file, not of the product.
+
+## What is reported, not imported
+
+The import never drops anything in silence — whatever it cannot carry appears as a note
+when it runs.
+
+| Not imported | Why |
+|---|---|
+| `metallicFactor`, `roughnessFactor`, `metallicRoughnessTexture` | Shading metal needs a view direction, and these lights are 2D. A factor nothing reads would be a knob that lies. |
+| Skinning (`JOINTS_0`/`WEIGHTS_0`), skins | A rigged model comes in as static geometry. |
+| Animations, morph targets | Not imported; the geometry is the bind pose. |
+| A second UV set (`TEXCOORD_1`), `KHR_texture_transform` | UVs are used as authored. |
+| Non-triangle primitives (`mode` ≠ 4) | The renderer draws triangle lists. |
+| `normalTexture.scale` | The map is applied at full strength. |
+
+## Limits worth knowing
+
+- Point lights measure distance in the XY plane (the 2D lighting model); **directional
+ lights are exact**, which is what a shaded model usually wants.
+- A material that writes its own vertex stage is not redirected onto mesh geometry — it
+ would ignore the per-object transform. Fragment-only materials work on both.
+- Geometry with no `NORMAL` attribute still takes light, off the constant normal a 2D
+ surface has — flat, but not black.
diff --git a/docs/astro/src/content/docs/zh-cn/assets/models.mdx b/docs/astro/src/content/docs/zh-cn/assets/models.mdx
new file mode 100644
index 000000000..d55da2ad8
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/assets/models.mdx
@@ -0,0 +1,116 @@
+---
+title: 模型
+description: glTF/GLB 导入 —— 导入写出什么、模型怎么进场景、Scale 设置、重新导入、哪些材质通道会变成 .esmaterial、Draco 与 meshopt、以及哪些东西只报告不导入。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+引擎画 mesh,而它只加载一种 mesh 格式:`.esmesh`。`.gltf` / `.glb` 是**源文件**,不是资源
+——把它带进项目会跑一次导入,写出场景真正能引用的那些资源。
+
+本页讲的就是这次导入。画出结果的那个组件见[组件参考](/docs/zh-cn/reference/components/graphics/);
+材质整体见[材质](/docs/zh-cn/graphics/materials/)。
+
+## 导入一个模型
+
+三个入口,同一次导入:
+
+| 方式 | 会发生什么 |
+|---|---|
+| 把 `.gltf`/`.glb` 拖进内容浏览器 | 源文件(连同它引用的文件)被拷进项目并导入。 |
+| 直接放进项目目录 | 编辑器会发现并导入它 —— `git checkout`、访达里拷贝、Blender 重新导出,都算。 |
+| `estella import-gltf <file> [outDir] --project <dir>` | 命令行里的同一次导入。`--scale <n>` 决定大小。 |
+
+产物落在**源文件旁边**,而不是内容浏览器当前显示的目录:重新导入必须覆盖同一批文件。
+
+## 导入写出什么
+
+以带两个 primitive、一张内嵌图的 `robot.gltf` 为例:
+
+| 产物 | 是什么 |
+|---|---|
+| `robot_0_0.esmesh`、`robot_1_0.esmesh` | 每个 primitive 一个几何文件,命名 `<stem>_<mesh>_<primitive>`(只有一个时就是 `<stem>`)。 |
+| `robot_0.png` | 文件内嵌的图片。已经在磁盘上的图片只被引用,不会复制。 |
+| `robot_m0.esmaterial` | **仅当**源材质说了 `Mesh2D` 装不下的东西时才写 —— 见[材质](#材质)。 |
+| `robot.esprefab` | 各部分怎么组装:节点层级,每个 `Mesh2D` 带上自己的 mesh、贴图、tint 和开关。 |
+
+把 **prefab** 拖进场景。单个 `.esmesh` 也是资源(`Mesh2D.mesh` 字段可以直接引用),
+但 prefab 才是作者组装好的那个模型。
+
+<Aside type="caution" title="产物会被重写">
+重新导入会替换每一个产物。手工改过的 `.esprefab` 会丢失;正确做法是在场景里放一个实例、改那个实例。
+</Aside>
+
+## Scale
+
+glTF 以**米**为单位。一个世界单位是一个**设计像素**。所以一个 1.7 米高的角色进来只有
+1.7 个单位高 —— 几个像素 —— 除非你另行指定。
+
+导入器不猜这个系数。模型进来很小的时候它会说出来,而修正它的那个数字就是源文件导入设置里的
+`Scale`(在内容浏览器里选中 `.gltf`)。保存它会重新导入这个模型。
+
+`Scale` 落在 prefab 根节点的 `Transform` 上,**不会烘进几何** —— `.esmesh` 保持与源一致,
+而那个数字始终看得见、改得动。
+
+## 重新导入
+
+以下情况会重新跑一次导入:
+
+- 源文件变了(重新导出覆盖了旧的);
+- 在内容浏览器里对它选择 **Reimport**;
+- 保存了一项导入设置。
+
+资源 uuid 会保留,所以引用这些产物的场景和 prefab 继续有效。
+
+## 材质
+
+一个 glTF 材质按「谁装得下」拆开。
+
+**落在 `Mesh2D` 组件上** —— base color,因为引擎的 mesh 通路本来就是
+`texture(uv) × 顶点色 × tint`:
+
+| glTF | 组件字段 |
+|---|---|
+| `baseColorTexture` | `texture` |
+| `baseColorFactor` | `color` |
+| `alphaMode` 不是 `BLEND` | `opaque` |
+| `doubleSided: false` | `cullBackfaces` |
+| 带 `NORMAL` 属性 | `lit: true` |
+
+**落在 `.esmaterial` 里** —— 着色,那是逐材质的常量和采样器,组件没有地方放。
+只在源文件用到它们时才写,基于内建的 **Model** shader:
+
+| glTF | 材质参数 |
+|---|---|
+| `normalTexture` | `u_normalMap` |
+| `emissiveFactor` / `emissiveTexture` | `u_emissive` / `u_emissiveMap` |
+| `occlusionTexture`(含 `strength`) | `u_occlusionMap` / `u_occlusionStrength` |
+| `alphaMode: MASK` + `alphaCutoff` | `u_alphaCutoff` |
+
+材质还会把这次 draw 的混合、深度和剔除重述一遍 —— 因为材质会**替换**它们,
+这样一个被要求自我遮挡的模型,在有了材质之后仍然自我遮挡。
+
+## 压缩几何
+
+`EXT_meshopt_compression` 与 `KHR_draco_mesh_compression` 在导入时解码,所以压缩过的导出件
+产出与未压缩件相同的 `.esmesh`。运行时什么都不变:压缩是源文件的属性,不是产物的属性。
+
+## 只报告、不导入的东西
+
+导入器不会无声丢弃任何东西 —— 它带不过来的,都会在导入时作为提示出现。
+
+| 不导入 | 为什么 |
+|---|---|
+| `metallicFactor`、`roughnessFactor`、`metallicRoughnessTexture` | 算金属高光要 view 方向,而这里的灯光是 2D 的。写进产物却没人读,那就是个会撒谎的旋钮。 |
+| 蒙皮(`JOINTS_0`/`WEIGHTS_0`)、skin | 绑定好的模型会以静态几何进来。 |
+| 动画、morph target | 不导入;几何就是绑定姿势。 |
+| 第二套 UV(`TEXCOORD_1`)、`KHR_texture_transform` | UV 按作者写的原样使用。 |
+| 非三角形 primitive(`mode` ≠ 4) | 渲染器画的是三角形列表。 |
+| `normalTexture.scale` | 法线贴图按全强度应用。 |
+
+## 值得知道的限制
+
+- 点光的距离在 XY 平面上算(2D 光照模型固有);**方向光是精确的**,而那通常正是着色一个模型需要的。
+- 自己写了 vertex stage 的材质**不会**被重定向到 mesh 几何上 —— 那样它会无视 per-object transform。
+ 只写 fragment 的材质两边都能用。
+- 没有 `NORMAL` 属性的几何仍然会受光,落在 2D 表面那个常量法线上 —— 平,但不是黑的。