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): the animations a model brings with it

esengine9431de484be6
diff --git a/docs/astro/src/content/docs/assets/models.mdx b/docs/astro/src/content/docs/assets/models.mdx
index 2a7c81fe9..891405f38 100644
--- a/docs/astro/src/content/docs/assets/models.mdx
+++ b/docs/astro/src/content/docs/assets/models.mdx
@@ -35,6 +35,7 @@ For `robot.gltf` with two primitives and one image:
| `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_Walk.estimeline` | One per animation in the source, named `<stem>_<animation>` — see [Animations](#animations). |
| `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
@@ -96,6 +97,25 @@ component has no room for. Written only when the source uses one of them, on the
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.
+## Animations
+
+Each animation in the source becomes an `.estimeline` beside the meshes, and the prefab's
+root carries a `TimelinePlayer` pointing at the first one with `playing` off — what to play
+is the scene's decision. Set `playing`, or call the timeline API, to run it.
+
+A clip drives the nodes it was authored against, addressing each by its path of names under
+the prefab root. Two sibling nodes sharing a name are given distinct ones during the import
+so a track cannot drive the wrong one; that name is what the prefab shows.
+
+`LINEAR`, `STEP` and `CUBICSPLINE` all carry across, tangents included.
+
+<Aside type="caution" title="A skinned character will not deform">
+Node animation moves the nodes — which for a rigged model means the joints move and the
+mesh bound to them does not follow, because skinning is not implemented. The import says so
+when it happens. Models whose parts are separate nodes (machines, doors, props, camera
+moves) animate exactly as authored.
+</Aside>
+
## Compressed geometry
`EXT_meshopt_compression` and `KHR_draco_mesh_compression` are decoded during import, so a
@@ -110,8 +130,8 @@ 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. |
+| Skinning (`JOINTS_0`/`WEIGHTS_0`), skins | A rigged model comes in as static geometry, and a clip driving its joints says so. |
+| Morph targets, `weights` animation channels | Blending between shapes needs the targets themselves, which are not carried. |
| 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. |
diff --git a/docs/astro/src/content/docs/zh-cn/assets/models.mdx b/docs/astro/src/content/docs/zh-cn/assets/models.mdx
index d55da2ad8..48066a3fd 100644
--- a/docs/astro/src/content/docs/zh-cn/assets/models.mdx
+++ b/docs/astro/src/content/docs/zh-cn/assets/models.mdx
@@ -32,6 +32,7 @@ import { Aside } from '@astrojs/starlight/components';
| `robot_0_0.esmesh`、`robot_1_0.esmesh` | 每个 primitive 一个几何文件,命名 `<stem>_<mesh>_<primitive>`(只有一个时就是 `<stem>`)。 |
| `robot_0.png` | 文件内嵌的图片。已经在磁盘上的图片只被引用,不会复制。 |
| `robot_m0.esmaterial` | **仅当**源材质说了 `Mesh2D` 装不下的东西时才写 —— 见[材质](#材质)。 |
+| `robot_Walk.estimeline` | 源里每个动画一个,命名 `<stem>_<动画名>` —— 见[动画](#动画)。 |
| `robot.esprefab` | 各部分怎么组装:节点层级,每个 `Mesh2D` 带上自己的 mesh、贴图、tint 和开关。 |
把 **prefab** 拖进场景。单个 `.esmesh` 也是资源(`Mesh2D.mesh` 字段可以直接引用),
@@ -90,6 +91,24 @@ glTF 以**米**为单位。一个世界单位是一个**设计像素**。所以
材质还会把这次 draw 的混合、深度和剔除重述一遍 —— 因为材质会**替换**它们,
这样一个被要求自我遮挡的模型,在有了材质之后仍然自我遮挡。
+## 动画
+
+源里的每个动画会在 mesh 旁边写出一个 `.estimeline`,prefab 的根挂一个 `TimelinePlayer`
+指向第一个,且 `playing` 是关的 —— 播哪一个是场景的决定。打开 `playing`,或调用 timeline
+API,它就开始播。
+
+一条 clip 驱动的是它当初针对的那些节点,按**名字路径**在 prefab 根之下寻址。同一父节点下
+重名的兄弟节点会在导入时被改成不同的名字,好让一条轨道不会驱动错对象;prefab 里显示的就是
+那个名字。
+
+`LINEAR`、`STEP`、`CUBICSPLINE` 都会带过来,含切线。
+
+<Aside type="caution" title="蒙皮角色不会变形">
+节点动画移动的是**节点** —— 对绑定好的模型来说就是骨骼在动,而绑在骨骼上的 mesh 不会跟着
+变形,因为蒙皮还没实现。遇到这种情况导入器会说出来。各部分本来就是独立节点的模型(机械、
+门、道具、相机运动)会完全按作者的意思动起来。
+</Aside>
+
## 压缩几何
`EXT_meshopt_compression` 与 `KHR_draco_mesh_compression` 在导入时解码,所以压缩过的导出件
@@ -102,8 +121,8 @@ glTF 以**米**为单位。一个世界单位是一个**设计像素**。所以
| 不导入 | 为什么 |
|---|---|
| `metallicFactor`、`roughnessFactor`、`metallicRoughnessTexture` | 算金属高光要 view 方向,而这里的灯光是 2D 的。写进产物却没人读,那就是个会撒谎的旋钮。 |
-| 蒙皮(`JOINTS_0`/`WEIGHTS_0`)、skin | 绑定好的模型会以静态几何进来。 |
-| 动画、morph target | 不导入;几何就是绑定姿势。 |
+| 蒙皮(`JOINTS_0`/`WEIGHTS_0`)、skin | 绑定好的模型会以静态几何进来,驱动它骨骼的 clip 会说明这一点。 |
+| morph target、`weights` 动画通道 | 在多个形状之间混合需要那些 target 本身,而它们没有被带过来。 |
| 第二套 UV(`TEXCOORD_1`)、`KHR_texture_transform` | UV 按作者写的原样使用。 |
| 非三角形 primitive(`mode` ≠ 4) | 渲染器画的是三角形列表。 |
| `normalTexture.scale` | 法线贴图按全强度应用。 |