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
feat(render): a draw blends up to 64 morph targets at once, where 8 left a face rig's lighter shapes reading as zero
yhhe3349d038abf
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3600ee931..0cc6b6bca 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,8 @@ published separately; it ships inside the editor.- **Glyphs can be put on the atlas before they are shown.** The first page of a novel is hundreds of new characters, all landing in one frame. `preloadGlyphs(app, label, text, { budgetMs })` makes them ahead of time, a slice a frame, drawn as that `Text` will draw them, and returns `progress`, `done` and `release()`. On a Snapdragon 8 Elite a book's 2992 characters at 28 px took 145 ms over 25 frames with the worst frame at 9.5 ms, after which the first page's frame went from 49 to 11 ms and no page made a new glyph. Preloaded glyphs hold their atlas pages (4 MB each, a few hundred characters at that size) until `release()`.- **Voxel GI lights what the camera does not see, and bounces light more than once.** The cache now reads the sun's shadow map back into the world, so a surface the sun lights behind or beside the camera still sends light into the view. Each surface also gives off again the bounce light it received, so a corner or a floor in shade gets light that took two or more bounces to reach it. A ray now brings what it meets at full strength however far it went (it used to fade with distance, 40% at 4 m with 12 cm voxels). Each voxel is weighed by how much of it a surface covers, so a bright patch no longer lights like the whole voxel around it. Together these keep the result close to a path tracer's whatever the voxel size. In a sunlit test room the whole frame carries 0.95 of Cycles' light at the default size and 0.74 at 12 cm voxels; before, it was 0.54 at the default and darker the finer the grid. With the lit patch behind the camera, the walls went from no bounce light to 25–57%. A closed room the sun only lights from outside stays dark. Two inspector controls tune it: **Off-screen Sun Albedo** (the colour the shadow map cannot give, assumed) and **Multi-bounce**. A fine grid no longer drops every voxel: a count truncated by the cache's ageing had kept them below the two samples a ray asks for. The WebGL2 fallback does the same in its own passes: each voxel asks the sun's map whether a sunlit surface stands in it, and traces two rays through last frame's grid for the light it is given. In the test room it carries 1.00 of Cycles' light at the default size (it was 0.56) and 0.80 at 12 cm; with the lit patch behind the camera 0.20 (it was 0). Its voxel pass costs about 1.3 ms more at 720p on a desktop.+- **A mesh can blend 64 morph targets at once, up from 8.** A face rig holds dozens open at a time. A draw pays only for the targets that are live.+- **A foot stands on the ground under it.** A `foot-plant` constraint on an Animator looks down from each foot through physics and bends the leg to land on whatever is there, slopes and steps included, keeping any lift the clip gives it, laying the foot along the slope and lowering the hips so the leg can reach.- **AI agents can build 3D models in the editor from steps.** The `modeling` tool group writes a `.esmodel`, the steps that build a model (boxes, cylinders and floor plans, then extrude, inset, bevel, slice, array, mirror, paint), and bakes the `.esmesh` a scene draws beside it. Changing one number rebuilds it and whatever draws it follows, Undo takes both files back, and `model_views` shows every side with its silhouette, so an agent can check a shape without a scene. Blockouts, buildings and hard-surface props; and with the `organic` step, creatures, plants and rocks, as one skin over parts that melt into each other, carve, mirror and roughen. `lathe` and `loft` make curved solids from a few points: vases, pipes, handles, hulls. A `rig` of joints gets its weights found over the surface and `animations` of a few keys play as ordinary clips, so a creature can walk, with feet told where to land and a `controller` choosing which clip plays when. `rig.adjust` corrects a weight, `shapes` make expressions a clip can move, and `controller.ik` reaches and looks at goals as the game runs. `subdivide` and a rounded `bevel` smooth what polygons leave hard. A `boolean` step cuts real holes through solids, and a `uv` step or `uvAtlas` lays out how a texture lands.diff --git a/desktop b/desktopindex 44cf8f622..3671fb6ce 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 44cf8f6225d7532a5658721b1fc08fdfb85afdfa+Subproject commit 3671fb6ce6c6b19157f582906d8ebb15e73d2f72diff --git a/docs/astro/src/content/docs/animation/overview.mdx b/docs/astro/src/content/docs/animation/overview.mdxindex da28aab5d..57b4d7670 100644--- a/docs/astro/src/content/docs/animation/overview.mdx+++ b/docs/astro/src/content/docs/animation/overview.mdx@@ -621,6 +621,16 @@ towards an optional `pole`; `look-at` turns a joint until its own `axis` pointstarget. Each has a `weight`, and a float `parameter` can fade it. IK belongs to thecontroller, not to a layer, and runs once on the stack's answer.+`foot-plant` keeps a foot on the ground. It takes a `tip` and no target: it casts down+through 3D physics from where the clip put the foot, and bends the leg so the foot lands+on what it finds, keeping any lift the clip gave it, so a walk still walks. `pelvis`+names a joint lowered so the leg can reach the lower foot; `align: false` keeps the foot+from lying along the slope; `reach` is how far to look, `smooth` the seconds to settle on+a new height, and `layers` the physics layers that count as ground. Set `layers` when the+character has a collider of its own, or the ray stops on it. The rig should stand with its+feet at height 0 and its root on the ground. Foot-plants run before the other constraints,+and with no physics in the game they leave the clip alone.+**Avatars.** A clip names joints by whatever the exporter called them, so twocharacters rigged by two people share no clip. A `.esavatar` (New menu) is the rig'sown translation of those names and records its bind pose; a controller's `avatar` namesdiff --git a/docs/astro/src/content/docs/assets/models.mdx b/docs/astro/src/content/docs/assets/models.mdxindex d330b3ca7..ce375d5f4 100644--- a/docs/astro/src/content/docs/assets/models.mdx+++ b/docs/astro/src/content/docs/assets/models.mdx@@ -282,7 +282,8 @@ glTF states none, and pushing past 1 or below 0 is a shape an author may want.| Limit | Why ||---|---|-| 8 shapes blended at once | A budget on what is LIVE, not on what a mesh carries — a face holds a handful of expressions open while its mesh has a hundred. The heaviest weights are taken; the rest read as zero, which is what an untouched weight already means. |+| 64 shapes blended at once | A budget on what is LIVE, not on what a mesh carries. A draw pays only for the shapes it is using, each a texture read or two per vertex, so dozens live on a dense mesh cost more than a handful. Past 64 the heaviest weights are taken; the rest read as zero, which is what an untouched weight already means. |+| 4,194,304 deltas per mesh | Shapes × vertices, twice that with normals: a 2048-square texture, the most WebGL2 guarantees. Past it the mesh draws but never changes shape. || Normals deform only where the geometry has them | A mesh with no `NORMAL` channel is shaded off a constant normal, which no delta can bend. || Morph targets carry no tangents | The mesh keeps the tangent frame it has at rest; a shape moves the surface but not the frame its normal map was baked in. || An FBX's in-between shapes | A channel that passes through shapes on its way to the last one carries only the last; the import says which it dropped. |diff --git a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdxindex 67915b5e2..54afe0c31 100644--- a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx@@ -563,6 +563,13 @@ evaluateAnimatorPath(player, 'locomotion/idle', { speed: 3 }, new Set());可选 `pole` 决定朝哪边弯;`look-at` 让某个关节自己的 `axis` 转向目标。两者都有 `weight`,并可由一个 float `parameter` 淡入淡出。IK 属于控制器而不是某一层,在层叠加的结果上只运行一次。+`foot-plant` 让脚踩在地面上。它只要 `tip`,不要目标:从片段放脚的位置向下做 3D 物理射线检测,+再弯曲腿让脚落在检测到的地面上,并保留片段给的抬脚高度,所以走路还是走路。`pelvis` 指定一个+可以降低的关节,让腿够得到较低的那只脚;`align: false` 让脚不贴合坡面;`reach` 是搜索距离,+`smooth` 是落到新高度所用的秒数,`layers` 是算作地面的物理层。角色自身有碰撞体时要设置 `layers`,+否则射线会停在它自己身上。骨架应当脚在高度 0、根节点站在地面上。foot-plant 先于其他约束运行,+游戏里没有物理时它不改动片段。+**Avatar。** 片段按导出者起的名字指名关节,所以两个人绑的两个角色互相用不了对方的片段。`.esavatar`(新建菜单)是骨架自己对这些名字的翻译,并记录它的绑定姿态;控制器的 `avatar` 指明它的片段是对着哪个 avatar 做的,`Animator` 的 `avatar` 字段填这个骨架自己的。这样一个控制器就能驱动骨骼名字不同、绑定姿态不同的角色,根运动也会按各自骨架应走的距离缩放。diff --git a/docs/astro/src/content/docs/zh-cn/assets/models.mdx b/docs/astro/src/content/docs/zh-cn/assets/models.mdxindex 4d011a70e..7e3a0c1af 100644--- a/docs/astro/src/content/docs/zh-cn/assets/models.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/models.mdx@@ -245,7 +245,8 @@ target 对每个顶点的 delta,prefab 给实体挂一个 `MeshMorph`,它的| 限制 | 为什么 ||---|---|-| 同时最多混合 8 个形状 | 限制的是**活跃**数量,不是 mesh 能携带的数量——一张脸同时张开的表情就那么几个,而它的 mesh 可以有上百个形状。取权重最大的那些,其余按 0 读,这和作者没动过的权重是同一件事。 |+| 同时最多混合 64 个形状 | 限制的是**活跃**数量,不是 mesh 能携带的数量。一次绘制只为正在用的形状付出代价,每个形状每顶点多一两次纹理读取,所以在高密度 mesh 上同时用几十个比用几个开销更大。超过 64 个时取权重最大的那些,其余按 0 读,这和作者没动过的权重含义相同。 |+| 每个 mesh 最多 4,194,304 个增量 | 形状数 × 顶点数,带法线时再乘 2:对应 2048 见方的纹理,这是 WebGL2 保证的上限。超过后 mesh 仍会绘制,但不再变形。 || 只有几何自带法线时法线才变形 | 没有 `NORMAL` 通道的 mesh 按一个常量法线着色,任何 delta 都弯不动它。 || 形变目标不带切线 | 网格保留静止姿态下的切线基;形变目标移动表面,但不改变法线贴图烘焙时用的那个基。 || FBX 的 in-between 形状 | 一个通道途经多个形状时只带最后一个;导入时会说明丢掉了哪些。 |diff --git a/pipeline/src/modeling/modelBake.ts b/pipeline/src/modeling/modelBake.tsindex 3b3af281e..9ec01680f 100644--- a/pipeline/src/modeling/modelBake.ts+++ b/pipeline/src/modeling/modelBake.ts@@ -280,7 +280,7 @@ export function bakeModel(raw: unknown): BakedModel {if (idle.length) warnings.push(`joint${idle.length > 1 ? 's' : ''} ${idle.join(', ')} move${idle.length > 1 ? '' : 's'} no vertex the most: too near another, or outside the surface`);}- // The engine's delta texture is 2048 square, the most WebGL2 promises; past it the mesh draws, but never changes shape.+ // The engine's delta texture is 2048 square, the most WebGL2 guarantees; past it the mesh draws, but never changes shape.if (shapes && shapes.names.length * unwrapped.vertexCount * 2 > 2048 * 2048) {warnings.push(`${shapes.names.length} shapes over ${unwrapped.vertexCount} vertices is more than the engine holds (${2048 * 2048} deltas, two each): it would draw but never change shape. Lower the resolution or use fewer shapes`);}diff --git a/src/esengine/data/shaders/mesh.esshader b/src/esengine/data/shaders/mesh.esshaderindex 40ab6db93..323a8d418 100644--- a/src/esengine/data/shaders/mesh.esshader+++ b/src/esengine/data/shaders/mesh.esshader@@ -100,7 +100,7 @@ layout(std140) uniform SkinConstants {layout(std140) uniform MorphConstants {// x = live shapes, y = vertices, z = texels per vertex, w = texture width.vec4 u_morphInfo;- vec4 u_morphShape[8];+ vec4 u_morphShape[64];};// The deltas: one texel per (target, vertex), and a second behind it where the// targets bend normals. A texture because they are megabytes, and a uniform@@ -117,7 +117,7 @@ vec3 morphDelta(float index) {void applyMorph(inout vec3 position, inout vec3 normal) {int live = int(u_morphInfo.x);float perVertex = u_morphInfo.z;- for (int i = 0; i < 8; i++) {+ for (int i = 0; i < 64; i++) {if (i >= live) break;float at = (u_morphShape[i].x * u_morphInfo.y + float(gl_VertexID)) * perVertex;position += u_morphShape[i].y * morphDelta(at);@@ -399,7 +399,7 @@ struct SkinConstants { bones : array<mat4x4f, 64> };// texture is declared HERE, in the vertex stage, which is what tells the backend// that unit 4 has to be visible to it — group-1 textures are fragment-only// otherwise (see SkinConstants.hpp, which chose a block over a texture for it).-struct MorphConstants { info : vec4f, shape : array<vec4f, 8> };+struct MorphConstants { info : vec4f, shape : array<vec4f, 64> };@group(0) @binding(6) var<uniform> morph : MorphConstants;@group(1) @binding(4) var t4 : texture_2d<f32>;@@ -485,7 +485,7 @@ fn esPrevBone(joint : u32) -> mat4x4f {// Before the pose, never after: a target was authored against the mesh at// rest, so the offset it states is a local one.let live = i32(morph.info.x);- for (var i = 0; i < 8; i = i + 1) {+ for (var i = 0; i < 64; i = i + 1) {if (i >= live) { break; }let at = (morph.shape[i].x * morph.info.y + f32(v.vertexIndex)) * morph.info.z;local = local + morph.shape[i].y * morphDelta(at);diff --git a/src/esengine/renderer/rhi/GfxEnums.hpp b/src/esengine/renderer/rhi/GfxEnums.hppindex 1c24f0e66..db165b800 100644--- a/src/esengine/renderer/rhi/GfxEnums.hpp+++ b/src/esengine/renderer/rhi/GfxEnums.hpp@@ -129,10 +129,10 @@ static constexpr u32 MESH_INSTANCE_TEXTURE_UNIT = 15;/// Bone matrices one skinned draw may carry. 64 mat4 is 4KB, inside the 16KB a/// WebGL2 uniform block is guaranteed; a mesh wanting more is drawn static.static constexpr u32 MESH_MAX_BONES = 64;-/// Morph targets one draw may be blended by AT ONCE — a budget on what is LIVE,-/// since a face holds a handful of expressions open while its mesh carries a-/// hundred. The heaviest weights are taken; the rest read as zero.-static constexpr u32 MESH_MAX_ACTIVE_MORPHS = 8;+/// Morph targets one draw may blend AT ONCE; past it the heaviest are taken. The shader+/// loops over only the live ones, each a texture read or two per vertex, so an unused+/// budget costs nothing beyond the larger block. Matches the bones: a face runs dozens.+static constexpr u32 MESH_MAX_ACTIVE_MORPHS = 64;/// Texels per row of a mesh's delta texture. 2048 is the smallest MAX_TEXTURE_SIZE/// WebGL2 guarantees, so a square of them is the most any device here must hold.static constexpr u32 MORPH_TEXTURE_WIDTH = 2048;diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hppindex cb803c24a..745cef8df 100644--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp@@ -645,7 +645,7 @@ layout(std140) uniform SkinConstants {layout(std140) uniform MorphConstants {vec4 u_morphInfo;- vec4 u_morphShape[8];+ vec4 u_morphShape[64];};@@ -662,7 +662,7 @@ vec3 morphDelta(float index) {void applyMorph(inout vec3 position, inout vec3 normal) {int live = int(u_morphInfo.x);float perVertex = u_morphInfo.z;- for (int i = 0; i < 8; i++) {+ for (int i = 0; i < 64; i++) {if (i >= live) break;float at = (u_morphShape[i].x * u_morphInfo.y + float(gl_VertexID)) * perVertex;position += u_morphShape[i].y * morphDelta(at);@@ -944,7 +944,7 @@ struct SkinConstants { bones : array<mat4x4f, 64> };-struct MorphConstants { info : vec4f, shape : array<vec4f, 8> };+struct MorphConstants { info : vec4f, shape : array<vec4f, 64> };@group(0) @binding(6) var<uniform> morph : MorphConstants;@group(1) @binding(4) var t4 : texture_2d<f32>;@@ -1030,7 +1030,7 @@ fn esPrevBone(joint : u32) -> mat4x4f {let live = i32(morph.info.x);- for (var i = 0; i < 8; i = i + 1) {+ for (var i = 0; i < 64; i = i + 1) {if (i >= live) { break; }let at = (morph.shape[i].x * morph.info.y + f32(v.vertexIndex)) * morph.info.z;local = local + morph.shape[i].y * morphDelta(at);diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 76b0b43d4..784c836c6 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3866,6 +3866,10 @@ export const NOTED = {{"note":"A sea seen from above is no longer scored with straight lines."},"feat(mcp): an agent builds a 3D model in the editor from steps, changes it by one number, and sees every side of it":{"note":"AI agents can build 3D models in the editor from steps."},+ "feat(mcp): model_write says 64 shapes count at once, and the modeling check proves sixteen do":+ {"note":"A mesh can blend 64 morph targets at once, up from 8."},+ "feat(render): a draw blends up to 64 morph targets at once, where 8 left a face rig's lighter shapes reading as zero":+ {"note":"A mesh can blend 64 morph targets at once, up from 8."},"feat(animation): a foot-plant constraint keeps a foot on the physics ground under it, slopes and steps included":{"note":"A foot stands on the ground under it."},"feat(mcp): model_write plants feet on the ground, and model_views runs the IK on a test floor":