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(animation): a spring-bone chain takes a wind, with gusts that ripple down the strand
yhh98f2fdec7208
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 85f417184..4fe3e8285 100644--- a/.github/workflows/build.yml+++ b/.github/workflows/build.yml@@ -27,7 +27,7 @@ env:test_ecs test_events test_particle test_tilemap test_tilemap_context test_sparse_settest_resource_pool test_shader_variant test_log_format test_registry_safetytest_registry_ondestroy test_view_api_matrix- test_hierarchy_links test_entity_activity test_transform_traversal test_ui_tree test_tween_activity+ test_hierarchy_links test_entity_activity test_transform_traversal test_ui_tree test_tween_activity test_springbonetest_shader_device test_draw_params test_per_draw_blocks test_texture_fb test_buffer_devicetest_compressed_format test_batch_builder test_skeletal_batch_color test_boundary_span test_webgpu_devicetest_clip_depth test_planar_reflection test_sort_key test_sprite_mask_range test_sprite_draw_mode test_shadow_atlas test_particle_shapes test_lod_selection test_view_shading test_mesh_edges test_hdr_format test_probe_store test_occlusion_view test_reflection_store test_tiled_lightsdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex ef6db7ee0..00bd204f6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -35,6 +35,7 @@ published separately; it ships inside the editor.- **Contact shadows and screen-space bounce light.** Contact Shadows and Screen Space GI effects add small sharp shadows at contacts and one bounce of colour between surfaces, and the weather softens the sun's shadows. `contactShadows` marches a short ray toward the scene's sun in the depth buffer; `ssgi` gathers eight rays a pixel over the G-buffer's normals at half size into a float target and averages the neighbours on the same surface before laying the light, times the receiver's colour, over the picture. The Weather component raises the sun's `sourceAngle` and lowers its `shadowStrength` as the sky clouds over.- **Terrain and Foliage.** A Terrain component makes ground from a heightmap or noise, paints it with grass, dirt, snow and rock layers and draws it in chunks that coarsen with distance; a Foliage component scatters grass or a mesh over it, swaying in the wind and thinning out with distance.- **Separate material maps packed on import.** Importing an FBX with separate metalness, roughness and occlusion images now packs them into the one map the Model shader samples, instead of dropping them. Occlusion goes in red, roughness in green and metal in blue, each from its image's red channel (a glossiness map is inverted); a channel with no image stays at full so the material's own value speaks. Only PNG and DDS can be read.+- **Spring-bone wind.** A spring-bone chain takes a wind: `wind` is a steady acceleration on the chain, `windGust` swings its strength from calm to twice as strong, and `windFrequency` sets how often. Each bone meets a gust a moment after the one above, so a strand ripples rather than swaying as one, and a chain's gusts depend only on its own clock, so the same scene moves the same way twice. The wind is a field on each chain; there is no scene-wide wind source yet.- **Spring-bone authoring.** Spring bones can be authored in the editor: Details groups a chain's fields into Motion, Chain and Collision and counts the bones below it (or warns that there are none), the viewport draws a selected chain (the bones as posed, a ring at each joint, the tips) with the colliders it keeps out of, or a selected collider on its own, behind a Spring bones entry in the Gizmo menu, and View · Preview FX simulates the chain in the edit viewport, drawn solid over its dashed pose. Ending the preview gives the bones back as the scene has them.- **Spring bones.** Spring bones give a skeleton secondary motion: a `SpringBone` on the root of a chain of bones (hair, a tail, a cord) makes everything below it a spring that lags the animation, falls with gravity, is pulled back to its animated pose, never stretches, and is kept out of `SpringBoneCollider` spheres and capsules. It runs in C++ in the engine, so it costs the same on every target: 300 chains of six bones step in 0.28 ms. Only the bones' rotations are written, and switching it off gives the animation's own back.- **Water rows in the quality settings.** Project Settings → Rendering has a Level · Water group for the five water quality fields (waves, ripple cells, displacement, mirror, caustics) of the level chosen under Editing level. Each is saved as a difference to that level only, and the group is hidden while quality is off or the project excludes the water module.diff --git a/docs/astro/src/content/docs/animation/spring-bones.mdx b/docs/astro/src/content/docs/animation/spring-bones.mdxindex 3729ab2c2..9ac4f773f 100644--- a/docs/astro/src/content/docs/animation/spring-bones.mdx+++ b/docs/astro/src/content/docs/animation/spring-bones.mdx@@ -21,6 +21,9 @@ is simulated.| `stiffness` | How hard each bone is pulled back toward its animated pose, 0 to 1 a frame at 60 Hz. 0 hangs free. || `drag` | How much of its speed a bone loses each frame, 0 to 1. Higher settles sooner; the default is damped enough not to ring. || `gravity` | World units a second squared (world y is up). The default is a metre a hundred units. |+| `wind` | A steady wind on the chain, world units a second squared. Zero is still air. |+| `windGust` | How far gusts swing the wind's strength, 0 to 1. 0 is steady; 1 takes it from calm to twice its strength. Each bone meets a gust a moment after the one above, so the strand ripples. |+| `windFrequency` | Gusts a second. || `endLength` | A leaf bone has no child to aim at; this gives it a tip that long. 0 leaves leaf bones unsimulated. || `radius` | The thickness of the strand, kept clear of the colliders. || `weight` | How much of the simulation is used, 0 to 1. 0 is the animation alone. |@@ -29,6 +32,18 @@ is simulated.A `SpringBoneCollider` is a sphere, or a capsule along its entity's own Y axis, placed by the entity's transform (and its `offset`). Put them on the headand shoulders bones so hair does not pass through the body.+## From a model++Set a model's **Spring Bones** import setting to **By Bone Name** and the importer builds the chains from names the file already carries, so nobody sets up forty strands by hand:++| Name | Becomes |+| --- | --- |+| `Hair_<region>_<chain>_00` (with bones below it) | a `SpringBone` on that bone; the rest of the strand is whatever hangs below it |+| `SBC_Sphere_<name>_r<cm>` | a sphere `SpringBoneCollider`, radius in centimetres |+| `SBC_Capsule_<name>_r<cm>_h<cm>` | a capsule, radius and the distance between its two end centres, along the node's local +Y |++The region (`Ponytail`, `Temple_L`, `Fringe`, `Crest`, `Crown`) picks a starting stiffness and drag: a fringe is held close, a ponytail swings. Every chain is kept out of every collider the model has. Sizes are in the model's metres and follow the import scale, and gravity is Earth's in those metres. A capsule with no length, or a chain root with nothing below it, is skipped. A name is a convention, so look at what the import made in Details and adjust it there.+## In the editorDetails groups the chain's fields into **Motion** (stiffness, drag, gravity), **Chain** (end length, radius, weight) and **Collision** (colliders), and says on its first@@ -67,5 +82,5 @@ cost 0.28 ms an update.** The test is `springbone` in the editor checks; `test_s- A bone with several children aims at its first child; the others follow by being children, and aim at their own.- Scale is taken from the bones' composed scale; non-uniform scale down a chain is not modelled.- Collision is bone against sphere or capsule: no collision between strands, no self-collision, and no collision with the world's physics shapes.-- There is no wind yet. A collider's radius, height and offset are typed in Details; the viewport has no handles to drag them. A hair importer that finds the strands and makes- the chains from the model's bone names does not exist yet either.+- The wind is a field on each chain, not a force in the scene: there is no scene-wide wind source to set once for every chain. A collider's radius, height and offset are typed in Details; the viewport has no handles to drag them. Chains are made from names; the importer does not look at+ the shape of the mesh, so a strand with no `Hair_` bone gets no motion.diff --git a/docs/astro/src/content/docs/zh-cn/animation/spring-bones.mdx b/docs/astro/src/content/docs/zh-cn/animation/spring-bones.mdxindex 1dac6c253..73c358dfe 100644--- a/docs/astro/src/content/docs/zh-cn/animation/spring-bones.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/spring-bones.mdx@@ -17,6 +17,9 @@ description: 骨骼链的次级运动(头发、尾巴、绳索):放在链根上| `stiffness` | 每根骨头被拉回动画姿势的力度,按 60 Hz 每帧计,0 到 1。0 是自由悬垂。 || `drag` | 每帧骨头损失的速度比例,0 到 1。越高越快安定;默认值阻尼足够,不会来回晃。 || `gravity` | 世界单位每二次方秒(世界 y 向上)。默认是一米一百个单位。 |+| `wind` | 作用在链上的稳定风,世界单位每二次方秒。0 是无风。 |+| `windGust` | 阵风让风力强弱摆动的幅度,0 到 1。0 是稳定的风;1 让风力在无风到两倍强度之间变化。每根骨头比上一根晚一点遇到阵风,所以发丝会起伏。 |+| `windFrequency` | 每秒几阵风。 || `endLength` | 末端骨头没有子骨头可以瞄准;这个值给它一段这么长的尖端。0 表示末端骨头不模拟。 || `radius` | 发丝的粗细,与碰撞体保持这个距离。 || `weight` | 用多少模拟,0 到 1。0 就是只有动画。 |@@ -24,6 +27,18 @@ description: 骨骼链的次级运动(头发、尾巴、绳索):放在链根上`SpringBoneCollider` 是一个球,或者沿它自己实体 Y 轴的胶囊,位置由实体的变换(和它的 `offset`)决定。把它们放在头和肩膀的骨头上,头发就不会穿过身体。+## 从模型导入++把模型的 **Spring Bones** 导入设置改成 **By Bone Name**,导入器就按文件里已有的名字建链,不用手动设置几十根发丝:++| 名字 | 变成 |+| --- | --- |+| `Hair_<分区>_<链号>_00`(下面有骨头) | 这根骨头上的 `SpringBone`;链的其余部分就是它下面挂着的骨头 |+| `SBC_Sphere_<名>_r<厘米>` | 球形 `SpringBoneCollider`,半径以厘米计 |+| `SBC_Capsule_<名>_r<厘米>_h<厘米>` | 胶囊,半径与两端球心的距离,沿节点本地 +Y |++分区(`Ponytail`、`Temple_L`、`Fringe`、`Crest`、`Crown`)决定起始的刚度和阻尼:刘海贴得紧,马尾摆得开。每条链都被挡在模型里所有碰撞体之外。尺寸是模型的米,随导入缩放,重力是这些米里的地球重力。没有长度的胶囊,或下面没有骨头的链根,会被跳过。名字只是约定,导入后在 Details 里看它做了什么,再在那里调整。+## 在编辑器里Details 把链的字段分成 **Motion**(stiffness、drag、gravity)、**Chain**(end length、radius、weight)和 **Collision**(colliders)三组,第一行说明这条链在它的实体下有几根骨头、几个末端尖端;没有子骨头时用警告色说明它什么也不会模拟。@@ -51,4 +66,4 @@ Details 把链的字段分成 **Motion**(stiffness、drag、gravity)、**Chain**- 有多个子骨头的骨头瞄准它的第一个子骨头;其他的因为是子骨头而跟着动,并各自瞄准自己的。- 缩放取骨头合成后的缩放;链上的非均匀缩放没有建模。- 碰撞是骨头对球或胶囊:没有发丝之间的碰撞,没有自碰撞,也没有和世界物理形状的碰撞。-- 还没有风。碰撞体的半径、高度和偏移在 Details 里输入;视口里没有可以拖动它们的手柄。能从模型的骨骼名字找出发束并生成链的头发导入器也还没有。+- 风是每条链自己的字段,不是场景里的力:还没有一个场景级的风源可以一次设置给所有链。碰撞体的半径、高度和偏移在 Details 里输入;视口里没有可以拖动它们的手柄。链是按名字建的,导入器不看网格的形状,所以没有 `Hair_` 骨头的发束不会有动作。diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 36168fe79..ac959aa7d 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5,7 +5,7 @@ Symbols: 115 public · 159 beta · 1749 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"0683d80a6ccb5275"+"7403dd8de628613e"```## ANCHOR_AXES — const @experimental@@ -8921,6 +8921,9 @@ gravity: Vec3radius: numberstiffness: numberweight: number+wind: Vec3+windFrequency: number+windGust: number```## SpringBoneParticle — interface @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex f3c64b643..707a4dcd8 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5,7 +5,7 @@ Symbols: 115 public · 164 beta · 1768 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"0683d80a6ccb5275"+"7403dd8de628613e"```## ANCHOR_AXES — const @experimental@@ -9134,6 +9134,9 @@ gravity: Vec3radius: numberstiffness: numberweight: number+wind: Vec3+windFrequency: number+windGust: number```## SpringBoneParticle — interface @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 87db70b83..db1cc2afa 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -8916,6 +8916,9 @@ gravity: Vec3radius: numberstiffness: numberweight: number+wind: Vec3+windFrequency: number+windGust: number```## SpringBoneParticle — interface @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 025b399cd..1fd9d7368 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -9209,6 +9209,9 @@ gravity: Vec3radius: numberstiffness: numberweight: number+wind: Vec3+windFrequency: number+windGust: number```## SpringBoneParticle — interface @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 0fd31e340..6b0a1c251 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -8923,6 +8923,9 @@ gravity: Vec3radius: numberstiffness: numberweight: number+wind: Vec3+windFrequency: number+windGust: number```## SpringBoneParticle — interface @experimentaldiff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.tsindex b2688a7dc..ec53733f5 100644--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts@@ -1906,6 +1906,9 @@ export interface SpringBonePtrData {stiffness: number;drag: number;gravity: Vec3;+ wind: Vec3;+ windGust: number;+ windFrequency: number;endLength: number;radius: number;weight: number;@@ -1919,9 +1922,12 @@ export function fillSpringBone(out.stiffness = f32[(ptr + 4) >> 2];out.drag = f32[(ptr + 8) >> 2];const gravity_ = out.gravity; gravity_.x = f32[(ptr + 12) >> 2]; gravity_.y = f32[((ptr + 12) >> 2) + 1]; gravity_.z = f32[((ptr + 12) >> 2) + 2];- out.endLength = f32[(ptr + 24) >> 2];- out.radius = f32[(ptr + 28) >> 2];- out.weight = f32[(ptr + 32) >> 2];+ const wind_ = out.wind; wind_.x = f32[(ptr + 24) >> 2]; wind_.y = f32[((ptr + 24) >> 2) + 1]; wind_.z = f32[((ptr + 24) >> 2) + 2];+ out.windGust = f32[(ptr + 36) >> 2];+ out.windFrequency = f32[(ptr + 40) >> 2];+ out.endLength = f32[(ptr + 44) >> 2];+ out.radius = f32[(ptr + 48) >> 2];+ out.weight = f32[(ptr + 52) >> 2];}export function writeSpringBone(@@ -1932,9 +1938,12 @@ export function writeSpringBone(f32[(ptr + 4) >> 2] = data.stiffness;f32[(ptr + 8) >> 2] = data.drag;f32[(ptr + 12) >> 2] = data.gravity.x; f32[((ptr + 12) >> 2) + 1] = data.gravity.y; f32[((ptr + 12) >> 2) + 2] = data.gravity.z;- f32[(ptr + 24) >> 2] = data.endLength;- f32[(ptr + 28) >> 2] = data.radius;- f32[(ptr + 32) >> 2] = data.weight;+ f32[(ptr + 24) >> 2] = data.wind.x; f32[((ptr + 24) >> 2) + 1] = data.wind.y; f32[((ptr + 24) >> 2) + 2] = data.wind.z;+ f32[(ptr + 36) >> 2] = data.windGust;+ f32[(ptr + 40) >> 2] = data.windFrequency;+ f32[(ptr + 44) >> 2] = data.endLength;+ f32[(ptr + 48) >> 2] = data.radius;+ f32[(ptr + 52) >> 2] = data.weight;}export function createSpringBoneData(): SpringBonePtrData {@@ -1943,6 +1952,9 @@ export function createSpringBoneData(): SpringBonePtrData {stiffness: 0,drag: 0,gravity: { x: 0, y: 0, z: 0 },+ wind: { x: 0, y: 0, z: 0 },+ windGust: 0,+ windFrequency: 0,endLength: 0,radius: 0,weight: 0,diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex 0aacc2651..667f72dce 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, Cl* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = '0683d80a6ccb5275';+export const ABI_LAYOUT_HASH = '7403dd8de628613e';/*** One asset-valued field of a component: which field, and what kind of@@ -1022,6 +1022,9 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {stiffness: 0.1,drag: 0.5,gravity: { x: 0, y: -980, z: 0 },+ wind: { x: 0, y: 0, z: 0 },+ windGust: 0,+ windFrequency: 0.5,endLength: 0,radius: 0,weight: 1,@@ -1036,6 +1039,9 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {stiffness: { min: 0, max: 1, step: 0.01, slider: true, tooltip: "How hard each bone is pulled back toward its animated pose. 0 hangs free, 1 follows the animation exactly.", category: "Motion" },drag: { min: 0, max: 1, step: 0.01, slider: true, tooltip: "How much of its speed a bone loses each frame. Higher settles sooner.", category: "Motion" },gravity: { tooltip: "Gravity on the chain, in world units a second squared (world y is up).", category: "Motion" },+ wind: { tooltip: "A steady wind on the chain, in world units a second squared. Zero is still air.", category: "Wind" },+ windGust: { min: 0, max: 1, step: 0.01, slider: true, tooltip: "How far gusts swing the wind's strength. 0 is a steady wind, 1 takes it from calm to twice its strength.", category: "Wind" },+ windFrequency: { min: 0, step: 0.05, tooltip: "Gusts a second.", category: "Wind" },endLength: { min: 0, step: 0.1, tooltip: "Length of the tip past each end bone, in world units. 0 leaves the end bones unsimulated.", category: "Chain" },radius: { min: 0, step: 0.1, tooltip: "Thickness of the strand, in world units, kept clear of the colliders.", category: "Chain" },weight: { min: 0, max: 1, step: 0.01, slider: true, tooltip: "How much of the simulation is used. 0 is the animation alone.", category: "Chain" },@@ -1835,6 +1841,9 @@ export interface SpringBoneData {stiffness: number;drag: number;gravity: Vec3;+ wind: Vec3;+ windGust: number;+ windFrequency: number;endLength: number;radius: number;weight: number;diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex 6884eac6b..5c6052fd1 100644--- a/sdk/src/wasm/ptrLayouts.generated.ts+++ b/sdk/src/wasm/ptrLayouts.generated.ts@@ -507,9 +507,12 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'stiffness', type: 'f32', offset: 4 },{ name: 'drag', type: 'f32', offset: 8 },{ name: 'gravity', type: 'vec3', offset: 12 },- { name: 'endLength', type: 'f32', offset: 24 },- { name: 'radius', type: 'f32', offset: 28 },- { name: 'weight', type: 'f32', offset: 32 },+ { name: 'wind', type: 'vec3', offset: 24 },+ { name: 'windGust', type: 'f32', offset: 36 },+ { name: 'windFrequency', type: 'f32', offset: 40 },+ { name: 'endLength', type: 'f32', offset: 44 },+ { name: 'radius', type: 'f32', offset: 48 },+ { name: 'weight', type: 'f32', offset: 52 },],},SpringBoneCollider: {diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex 667850704..483aac083 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -866,6 +866,9 @@ export interface SpringBone {stiffness: number;drag: number;gravity: Vec3;+ wind: Vec3;+ windGust: number;+ windFrequency: number;endLength: number;radius: number;weight: number;diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex f530560c6..fc6a67e4b 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -1347,6 +1347,24 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"step": 0.01,"tooltip": "How much of the simulation is used. 0 is the animation alone.",},+ "wind": {+ "category": "Wind",+ "tooltip": "A steady wind on the chain, in world units a second squared. Zero is still air.",+ },+ "windFrequency": {+ "category": "Wind",+ "min": 0,+ "step": 0.05,+ "tooltip": "Gusts a second.",+ },+ "windGust": {+ "category": "Wind",+ "max": 1,+ "min": 0,+ "slider": true,+ "step": 0.01,+ "tooltip": "How far gusts swing the wind's strength. 0 is a steady wind, 1 takes it from calm to twice its strength.",+ },},"SpringBoneCollider": {"height": {diff --git a/src/esengine/aot/EngineDigest.generated.h b/src/esengine/aot/EngineDigest.generated.hindex 1ecc6b39d..90d8f6abc 100644--- a/src/esengine/aot/EngineDigest.generated.h+++ b/src/esengine/aot/EngineDigest.generated.h@@ -6,7 +6,7 @@/* One per address width, because the width is IN the digest: a host thattook the other one would refuse every module built for it. */-#define ES_ENGINE_ABI_DIGEST_32 0x3e28c8d2ebc2c1c4ULL-#define ES_ENGINE_ABI_DIGEST_64 0x5f1e2389e92b4ae8ULL+#define ES_ENGINE_ABI_DIGEST_32 0x2fcc8caf6bae5f99ULL+#define ES_ENGINE_ABI_DIGEST_64 0x9b42eef6b1a2ffbdULL#define ES_ENGINE_ABI_DIGEST \(sizeof(es_addr_t) == 8 ? ES_ENGINE_ABI_DIGEST_64 : ES_ENGINE_ABI_DIGEST_32)diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex e3f0d0598..7ace135c7 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash b8db52cc968a31ad+ * @schema_hash 3a4ef4999092f3eb*/-#define ES_EDITOR_API_SCHEMA_HASH "b8db52cc968a31ad"+#define ES_EDITOR_API_SCHEMA_HASH "3a4ef4999092f3eb"#include <emscripten/bind.h>#include <string>@@ -638,6 +638,11 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"gravity.x","type":"float","group":"SpringBone"},{"key":"gravity.y","type":"float","group":"SpringBone"},{"key":"gravity.z","type":"float","group":"SpringBone"},+ {"key":"wind.x","type":"float","group":"SpringBone"},+ {"key":"wind.y","type":"float","group":"SpringBone"},+ {"key":"wind.z","type":"float","group":"SpringBone"},+ {"key":"windGust","type":"float","group":"SpringBone"},+ {"key":"windFrequency","type":"float","group":"SpringBone"},{"key":"endLength","type":"float","group":"SpringBone"},{"key":"radius","type":"float","group":"SpringBone"},{"key":"weight","type":"float","group":"SpringBone"},@@ -1626,6 +1631,11 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::selse if (field == "gravity.x") { c.gravity.x = value; }else if (field == "gravity.y") { c.gravity.y = value; }else if (field == "gravity.z") { c.gravity.z = value; }+ else if (field == "wind.x") { c.wind.x = value; }+ else if (field == "wind.y") { c.wind.y = value; }+ else if (field == "wind.z") { c.wind.z = value; }+ else if (field == "windGust") { c.windGust = value; }+ else if (field == "windFrequency") { c.windFrequency = value; }else if (field == "endLength") { c.endLength = value; }else if (field == "radius") { c.radius = value; }else if (field == "weight") { c.weight = value; }@@ -2150,6 +2160,11 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "gravity.x") { return c.gravity.x; }else if (field == "gravity.y") { return c.gravity.y; }else if (field == "gravity.z") { return c.gravity.z; }+ else if (field == "wind.x") { return c.wind.x; }+ else if (field == "wind.y") { return c.wind.y; }+ else if (field == "wind.z") { return c.wind.z; }+ else if (field == "windGust") { return c.windGust; }+ else if (field == "windFrequency") { return c.windFrequency; }else if (field == "endLength") { return c.endLength; }else if (field == "radius") { return c.radius; }else if (field == "weight") { return c.weight; }diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 7bfcc0d89..b3f2d1c62 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -1275,6 +1275,9 @@ struct SpringBoneJS {f32 stiffness;f32 drag;glm::vec3 gravity;+ glm::vec3 wind;+ f32 windGust;+ f32 windFrequency;f32 endLength;f32 radius;f32 weight;@@ -1286,6 +1289,9 @@ void springboneApplyJS(esengine::ecs::SpringBone& c, const SpringBoneJS& js) {c.stiffness = js.stiffness;c.drag = js.drag;c.gravity = js.gravity;+ c.wind = js.wind;+ c.windGust = js.windGust;+ c.windFrequency = js.windFrequency;c.endLength = js.endLength;c.radius = js.radius;c.weight = js.weight;@@ -1305,6 +1311,9 @@ SpringBoneJS springboneToJS(const esengine::ecs::SpringBone& c) {js.stiffness = c.stiffness;js.drag = c.drag;js.gravity = c.gravity;+ js.wind = c.wind;+ js.windGust = c.windGust;+ js.windFrequency = c.windFrequency;js.endLength = c.endLength;js.radius = c.radius;js.weight = c.weight;@@ -2134,6 +2143,9 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("stiffness", &SpringBoneJS::stiffness).field("drag", &SpringBoneJS::drag).field("gravity", &SpringBoneJS::gravity)+ .field("wind", &SpringBoneJS::wind)+ .field("windGust", &SpringBoneJS::windGust)+ .field("windFrequency", &SpringBoneJS::windFrequency).field("endLength", &SpringBoneJS::endLength).field("radius", &SpringBoneJS::radius).field("weight", &SpringBoneJS::weight)@@ -3945,9 +3957,12 @@ static_assert(offsetof(esengine::ecs::SpringBone, enabled) == 0, "ABI offset dristatic_assert(offsetof(esengine::ecs::SpringBone, stiffness) == 4, "ABI offset drift: esengine::ecs::SpringBone.stiffness (EHT expected 4)");static_assert(offsetof(esengine::ecs::SpringBone, drag) == 8, "ABI offset drift: esengine::ecs::SpringBone.drag (EHT expected 8)");static_assert(offsetof(esengine::ecs::SpringBone, gravity) == 12, "ABI offset drift: esengine::ecs::SpringBone.gravity (EHT expected 12)");-static_assert(offsetof(esengine::ecs::SpringBone, endLength) == 24, "ABI offset drift: esengine::ecs::SpringBone.endLength (EHT expected 24)");-static_assert(offsetof(esengine::ecs::SpringBone, radius) == 28, "ABI offset drift: esengine::ecs::SpringBone.radius (EHT expected 28)");-static_assert(offsetof(esengine::ecs::SpringBone, weight) == 32, "ABI offset drift: esengine::ecs::SpringBone.weight (EHT expected 32)");+static_assert(offsetof(esengine::ecs::SpringBone, wind) == 24, "ABI offset drift: esengine::ecs::SpringBone.wind (EHT expected 24)");+static_assert(offsetof(esengine::ecs::SpringBone, windGust) == 36, "ABI offset drift: esengine::ecs::SpringBone.windGust (EHT expected 36)");+static_assert(offsetof(esengine::ecs::SpringBone, windFrequency) == 40, "ABI offset drift: esengine::ecs::SpringBone.windFrequency (EHT expected 40)");+static_assert(offsetof(esengine::ecs::SpringBone, endLength) == 44, "ABI offset drift: esengine::ecs::SpringBone.endLength (EHT expected 44)");+static_assert(offsetof(esengine::ecs::SpringBone, radius) == 48, "ABI offset drift: esengine::ecs::SpringBone.radius (EHT expected 48)");+static_assert(offsetof(esengine::ecs::SpringBone, weight) == 52, "ABI offset drift: esengine::ecs::SpringBone.weight (EHT expected 52)");static_assert(offsetof(esengine::ecs::SpringBoneCollider, shape) == 0, "ABI offset drift: esengine::ecs::SpringBoneCollider.shape (EHT expected 0)");static_assert(offsetof(esengine::ecs::SpringBoneCollider, radius) == 4, "ABI offset drift: esengine::ecs::SpringBoneCollider.radius (EHT expected 4)");static_assert(offsetof(esengine::ecs::SpringBoneCollider, height) == 8, "ABI offset drift: esengine::ecs::SpringBoneCollider.height (EHT expected 8)");@@ -4064,7 +4079,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "0683d80a6ccb5275";+static const char* kEsAbiLayoutHash = "7403dd8de628613e";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/ecs/components/SpringBone.hpp b/src/esengine/ecs/components/SpringBone.hppindex 40c255a28..9455cb27a 100644--- a/src/esengine/ecs/components/SpringBone.hpp+++ b/src/esengine/ecs/components/SpringBone.hpp@@ -51,6 +51,18 @@ struct SpringBone {ES_PROPERTY(category=Motion, tooltip="Gravity on the chain, in world units a second squared (world y is up).")glm::vec3 gravity{0.0f, -980.0f, 0.0f};+ /** @brief A steady wind on the chain, in world units a second squared. */+ ES_PROPERTY(category=Wind, tooltip="A steady wind on the chain, in world units a second squared. Zero is still air.")+ glm::vec3 wind{0.0f, 0.0f, 0.0f};++ /** @brief How far gusts swing the wind's strength, 0 to 1. */+ ES_PROPERTY(category=Wind, min=0, max=1, step=0.01, slider, tooltip="How far gusts swing the wind's strength. 0 is a steady wind, 1 takes it from calm to twice its strength.")+ f32 windGust{0.0f};++ /** @brief Gusts a second. */+ ES_PROPERTY(category=Wind, min=0, step=0.05, tooltip="Gusts a second.")+ f32 windFrequency{0.5f};+/** @brief How far the last bones of a chain reach past themselves, in world units: a leaf has no child to aim at, so this gives it a tip. 0 leaves leaves unsimulated. */ES_PROPERTY(category=Chain, min=0, step=0.1, tooltip="Length of the tip past each end bone, in world units. 0 leaves the end bones unsimulated.")f32 endLength{0.0f};diff --git a/src/esengine/springbone/SpringBoneSolver.cpp b/src/esengine/springbone/SpringBoneSolver.cppindex 23d28a45e..273d44051 100644--- a/src/esengine/springbone/SpringBoneSolver.cpp+++ b/src/esengine/springbone/SpringBoneSolver.cpp@@ -54,9 +54,18 @@ bool pushOut(glm::vec3& p, const Collider& c, f32 extra) {return true;}+f32 gustFactor(f32 time, f32 frequency, f32 gust, i32 index) {+ if (gust <= 0.0f) return 1.0f;+ constexpr f32 kTwoPi = 6.28318530718f;+ // Two incommensurate sines: no beat repeats soon enough to read as a loop. The index lags the phase so each bone meets a gust a moment after the one above.+ const f32 phase = time * frequency * kTwoPi - static_cast<f32>(index) * 0.35f;+ const f32 n = 0.6f * std::sin(phase) + 0.4f * std::sin(phase * 2.37f + 1.3f);+ return std::max(0.0f, 1.0f + std::clamp(gust, 0.0f, 1.0f) * n);+}+namespace {-void substep(std::vector<Particle>& chain, const StepParams& params, const std::vector<Collider>& colliders, f32 h) {+void substep(std::vector<Particle>& chain, const StepParams& params, const std::vector<Collider>& colliders, f32 h, f32 time) {// Stiffness and drag are quoted per 60 Hz frame; at another step they are the same decay over that time.const f32 frames = h / kReferenceStep;const f32 keep = std::pow(std::clamp(1.0f - params.drag, 0.0f, 1.0f), frames);@@ -74,6 +83,7 @@ void substep(std::vector<Particle>& chain, const StepParams& params, const std::const glm::vec3 velocity = (p.position - p.previous) * keep;p.previous = p.position;p.position += velocity + fall;+ if (glm::dot(params.wind, params.wind) > 0.0f) p.position += params.wind * (gustFactor(time, params.windFrequency, params.windGust, static_cast<i32>(i)) * h * h);p.position += (p.target - p.position) * pull;}// Parents first: a node's parent is already where it will be, so each node is put at its distance from it and the chain cannot stretch.@@ -108,7 +118,7 @@ void step(std::vector<Particle>& chain, const StepParams& params, const std::vecdt = std::min(dt, kMaxStep);const i32 steps = std::max(1, static_cast<i32>(std::ceil(dt / kReferenceStep - 1e-4f)));const f32 h = dt / static_cast<f32>(steps);- for (i32 s = 0; s < steps; ++s) substep(chain, params, colliders, h);+ for (i32 s = 0; s < steps; ++s) substep(chain, params, colliders, h, params.time + h * static_cast<f32>(s));}} // namespace esengine::springbonediff --git a/src/esengine/springbone/SpringBoneSolver.hpp b/src/esengine/springbone/SpringBoneSolver.hppindex 32afa1156..da1325f8c 100644--- a/src/esengine/springbone/SpringBoneSolver.hpp+++ b/src/esengine/springbone/SpringBoneSolver.hpp@@ -37,8 +37,15 @@ struct StepParams {f32 drag = 0.5f; ///< Share of speed lost per 60 Hz frame, 0 to 1.glm::vec3 gravity{0.0f, -980.0f, 0.0f};f32 radius = 0.0f; ///< The strand's own thickness, kept clear of colliders.+ glm::vec3 wind{0.0f}; ///< Steady wind acceleration, world units a second squared.+ f32 windGust = 0.0f; ///< How far gusts swing the wind's strength, 0 to 1: 0.5 takes it between half and one and a half times `wind`.+ f32 windFrequency = 0.5f;///< Gusts a second.+ f32 time = 0.0f; ///< Seconds on the chain's own clock at the start of the call; gusts are a function of it, so a chain is repeatable.};+/** @brief The factor gusts put on the wind's strength for a particle at a moment: a travelling wave down the chain, so the strand ripples instead of swaying as one. */+f32 gustFactor(f32 time, f32 frequency, f32 gust, i32 index);+/** @brief A collider in world space: a sphere when `a == b`, else a capsule from `a` to `b`. */struct Collider {glm::vec3 a{0.0f};diff --git a/src/esengine/springbone/SpringBoneSystem.cpp b/src/esengine/springbone/SpringBoneSystem.cppindex d0b0717c4..730f7f5aa 100644--- a/src/esengine/springbone/SpringBoneSystem.cpp+++ b/src/esengine/springbone/SpringBoneSystem.cpp@@ -241,7 +241,12 @@ void SpringBoneSystem::update(ecs::Registry& registry, ecs::TransformSystem* traparams.drag = sb.drag;params.gravity = sb.gravity;params.radius = sb.radius;+ params.wind = sb.wind;+ params.windGust = sb.windGust;+ params.windFrequency = sb.windFrequency;+ params.time = st.clock;step(st.particles, params, colliders_, dt);+ st.clock += std::min(dt, springbone::kMaxStep);++simulated_;// Write back: each bone is turned to aim at where its child's simulated point is, going down the chain so a bone's own positiondiff --git a/src/esengine/springbone/SpringBoneSystem.hpp b/src/esengine/springbone/SpringBoneSystem.hppindex e078ac2ee..42e9d3cec 100644--- a/src/esengine/springbone/SpringBoneSystem.hpp+++ b/src/esengine/springbone/SpringBoneSystem.hpp@@ -77,6 +77,7 @@ private:std::vector<Node> nodes;glm::vec3 rootPosition{0.0f};bool primed = false;+ f32 clock = 0.0f; ///< Seconds this chain has been simulated, which the wind's gusts are a function of./// The animation's local rotation of each bone, the one this system last wrote there, and whether it has written one. A bone/// still holding what was written was not animated this frame, so the animation's own value is the one kept from before.std::vector<glm::quat> animated;diff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.hindex fd0bf27e8..446168915 100644--- a/tests/aot/generated/conformance/handshake.h+++ b/tests/aot/generated/conformance/handshake.h@@ -1,5 +1,5 @@/* GENERATED by sdk/tests/aot-conformance.test.ts — do not edit. *//* The contract half of the handshake. The width half is the harness. */-#define ES_CONF_EXPECTED_CONTRACT_HASH 0x5f1e2389e92b4ae8ULL+#define ES_CONF_EXPECTED_CONTRACT_HASH 0x9b42eef6b1a2ffbdULL/* And which BUILD the artifact beside this one is. */#define ES_CONF_EXPECTED_MODULE_CONTRACT 0xc3d0e057d5701a2eULLdiff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.cindex 076a3e3c8..8b7e98550 100644--- a/tests/aot/generated/conformance/systems_decl.c+++ b/tests/aot/generated/conformance/systems_decl.c@@ -10,7 +10,7 @@answer, it is a read of a different field. The address width belongsto the MACHINE, so it mixes in here rather than in the compiler and a32-bit artifact cannot load into a 64-bit host. */-#define ES_ABI_ENGINE_DIGEST 0x5f1e2389e92b4ae8ULL+#define ES_ABI_ENGINE_DIGEST 0x9b42eef6b1a2ffbdULLES_EXPORT const uint64_t es_abi_hash =ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));diff --git a/tests/aot/generated/move_system_decl.c b/tests/aot/generated/move_system_decl.cindex 3e7e78c3c..5cc21b0fe 100644--- a/tests/aot/generated/move_system_decl.c+++ b/tests/aot/generated/move_system_decl.c@@ -10,7 +10,7 @@answer, it is a read of a different field. The address width belongsto the MACHINE, so it mixes in here rather than in the compiler and a32-bit artifact cannot load into a 64-bit host. */-#define ES_ABI_ENGINE_DIGEST 0x5f1e2389e92b4ae8ULL+#define ES_ABI_ENGINE_DIGEST 0x9b42eef6b1a2ffbdULLES_EXPORT const uint64_t es_abi_hash =ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));diff --git a/tests/aot/generated/move_system_hash.h b/tests/aot/generated/move_system_hash.hindex 2522c3c44..88766b076 100644--- a/tests/aot/generated/move_system_hash.h+++ b/tests/aot/generated/move_system_hash.h@@ -1,6 +1,6 @@/* GENERATED by @estella/compiler — do not edit. *//* The contract half of the handshake. The width half is the harness. */-#define ES_EXPECTED_CONTRACT_HASH 0x5f1e2389e92b4ae8ULL+#define ES_EXPECTED_CONTRACT_HASH 0x9b42eef6b1a2ffbdULL/* And which BUILD the artifact beside this one is, which the sidecarwritten with it has to carry too. */#define ES_EXPECTED_MODULE_CONTRACT 0x10bf77bb714ea1e3ULLdiff --git a/tests/springbone/test_springbone.cpp b/tests/springbone/test_springbone.cppindex 793a04444..bd154075f 100644--- a/tests/springbone/test_springbone.cpp+++ b/tests/springbone/test_springbone.cpp@@ -326,3 +326,70 @@ TEST_CASE("a collider entity keeps the simulated bones out") {REQUIRE(chain != nullptr);for (size_t i = 1; i < chain->size(); ++i) CHECK(glm::length((*chain)[i].position - glm::vec3(15.0f, -10.0f, 0.0f)) >= 7.9f);}++TEST_CASE("a steady wind holds a chain out downwind of its pose") {+ auto chain = hanging(5, 10.0f);+ StepParams params;+ params.gravity = glm::vec3(0.0f);+ params.stiffness = 0.05f;+ params.wind = glm::vec3(600.0f, 0.0f, 0.0f);+ for (int i = 0; i < 240; ++i) {+ params.time = static_cast<f32>(i) / 60.0f;+ step(chain, params, {}, 1.0f / 60.0f);+ }+ CHECK(chain.back().position.x > 3.0f);+ CHECK(std::abs(chain.back().position.z) < 1e-3f);+ CHECK(stretch(chain) < 1e-2f);+ // The root is what the body drives and the wind never moves it.+ CHECK(chain[0].position.x == doctest::Approx(0.0f));+}++TEST_CASE("without a wind the chain is as it was, gusts or not") {+ auto still = hanging(4, 10.0f);+ auto gusty = hanging(4, 10.0f);+ StepParams a;+ StepParams b;+ b.windGust = 1.0f;+ for (int i = 0; i < 60; ++i) {+ a.time = b.time = static_cast<f32>(i) / 60.0f;+ step(still, a, {}, 1.0f / 60.0f);+ step(gusty, b, {}, 1.0f / 60.0f);+ }+ for (size_t i = 0; i < still.size(); ++i) CHECK(glm::length(still[i].position - gusty[i].position) < 1e-5f);+}++TEST_CASE("gusts swing the wind's strength, within bounds and reproducibly") {+ CHECK(gustFactor(1.7f, 0.5f, 0.0f, 3) == doctest::Approx(1.0f));+ f32 lo = 10.0f, hi = -10.0f;+ for (int i = 0; i < 400; ++i) {+ const f32 f = gustFactor(static_cast<f32>(i) * 0.05f, 0.5f, 1.0f, 0);+ lo = std::min(lo, f);+ hi = std::max(hi, f);+ CHECK(f >= 0.0f);+ CHECK(f <= 2.0f);+ }+ CHECK(lo < 0.5f);+ CHECK(hi > 1.5f);+ CHECK(gustFactor(2.5f, 0.5f, 0.6f, 2) == gustFactor(2.5f, 0.5f, 0.6f, 2));+ // A bone further down meets the same gust later: the strand ripples.+ CHECK(gustFactor(2.5f, 0.5f, 1.0f, 0) != doctest::Approx(gustFactor(2.5f, 0.5f, 1.0f, 4)));+}++TEST_CASE("the chain's own clock makes a gusting chain repeatable") {+ auto run = [] {+ auto chain = hanging(5, 10.0f);+ StepParams p;+ p.gravity = glm::vec3(0.0f);+ p.wind = glm::vec3(400.0f, 0.0f, 100.0f);+ p.windGust = 0.8f;+ for (int i = 0; i < 180; ++i) {+ p.time = static_cast<f32>(i) / 60.0f;+ step(chain, p, {}, 1.0f / 60.0f);+ }+ return chain.back().position;+ };+ const glm::vec3 first = run();+ const glm::vec3 second = run();+ CHECK(first.x == second.x);+ CHECK(first.z == second.z);+}diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex b188d3f8f..ea2d2f37d 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -2567,6 +2567,8 @@ export const NOTED = {{"note":"Water holds things up. A Floating component on an entity with a RigidBody3D floats it: a buoyant force against gravity (`buoyancy` is the water's density against the body's, so 2 floats it half under) and a drag against its velocity relative to the water, which brings it to rest in a lake and carries it with a river's current, applied at a few points of the body so waves tip it. It works from the CPU's own water surface, so it needs no renderer, and it needs the 3D physics module, which gains force and mass queries."},"feat(water): a camera under the surface sees through the water, fogged and tinted by what it has crossed":{"note":"A camera under water sees through it. Whenever the active camera is below a water body's surface an Underwater effect is added to the post-process volumes: the light of each pixel is taken out colour by colour (red first) by the distance it crossed, with the same absorption and density the surface's material draws with, and the water gives back its own colour, dimmer the deeper the camera is. The surface seen from below turns over and, past the critical angle, reflects whole (Snell's window)."},+ "feat(animation): a spring-bone chain takes a wind, with gusts that ripple down the strand":+ {"note":"A spring-bone chain takes a wind: `wind` is a steady acceleration on the chain, `windGust` swings its strength from calm to twice as strong, and `windFrequency` sets how often. Each bone meets a gust a moment after the one above, so a strand ripples rather than swaying as one, and a chain's gusts depend only on its own clock, so the same scene moves the same way twice. The wind is a field on each chain; there is no scene-wide wind source yet."},"feat(editor): a selected spring-bone chain and its colliders are drawn in the viewport, Details groups and counts them, and Preview FX simulates the chain":{"note":"Spring bones can be authored in the editor: Details groups a chain's fields into Motion, Chain and Collision and counts the bones below it (or warns that there are none), the viewport draws a selected chain (the bones as posed, a ring at each joint, the tips) with the colliders it keeps out of, or a selected collider on its own, behind a Spring bones entry in the Gizmo menu, and View · Preview FX simulates the chain in the edit viewport, drawn solid over its dashed pose. Ending the preview gives the bones back as the scene has them."},"feat(animation): spring bones give a chain of bones secondary motion in the engine, with colliders to keep it out of the body":