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(editor): a grip is edited where it is held, the character holding it live in the edit viewport
yhh12fc6388b7e0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b5d2b1cbc..2b11201a4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,10 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **A grip is edited where it is held.** Select an object with a `GripProfile` and its Details section edits the grip while a character in the scene holds it in the edit viewport, without Play: pick the character (it is given a `GripHolder`), create and pick the two palm anchors, see each palm drawn where it goes, switch the leading hand, and change every finger joint by joint in degrees, starting from a grip pose. Anchors are placed once and mirrored in the object's own plane for the other hand (`GripProfile.hand`, `mirror`); fingers said joint by joint (`GripFinger.bend`, `fan`, kept in `mainFingers`/`supportFingers`) are measured on the hand's own axes, so they mirror and fit any rig. The preview is the viewport's Preview FX and gives the bones back when it is turned off.+## [0.101.1] - 2026-11-10### Fixeddiff --git a/desktop b/desktopindex 630655788..cd9a1c9a4 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 63065578847c7e412cfe0f024f67a01128fe55b7+Subproject commit cd9a1c9a412b1a18cfe37820ff77cff59aa2d024diff --git a/docs/astro/src/content/docs/animation/grip-pose.mdx b/docs/astro/src/content/docs/animation/grip-pose.mdxindex 7b0a81334..64e5b3c31 100644--- a/docs/astro/src/content/docs/animation/grip-pose.mdx+++ b/docs/astro/src/content/docs/animation/grip-pose.mdx@@ -62,12 +62,16 @@ registerGripPose('claw', {| `curl` | How far the finger bends, 0 as the rig rests to 1 closed. || `base` | How far its first joint bends, where that differs: a finger laid along a frame, or hooked. Defaults to `curl`. || `spread` | How far the fingers fan out, -1 to 1. |+| `bend` | Each joint's bend in degrees, knuckle first, from where the rig rests: `[30, 45, 20]`. Over `curl` and `base`. What the editor writes. |+| `fan` | How far this one finger leans out from the middle of the hand, in degrees: the index and middle toward the thumb, the ring and little finger away. Over `spread`. |+| `trigger` | On the pose: the index finger as `rightTrigger` takes it to 1. || `opposition` | The thumb: how far it goes from where it rests to what it reaches for, 0 to 1. || `to` | The thumb: `fingers` (the middle of the middle finger, as a fist or a handle) or `index` (the index tip, as a pinch). || `gap` | The thumb: how far short of it it stops, in lengths of the index finger: the grip or the mug in between. |The thumb is not bent by numbers of its own: it reaches. Its tip goes to a point on the other fingers as they stand that frame, on the palm's side of them, and its two joints bend together to get there, so it lies over the fingers in a fist and comes round a grip. Out of reach (flat fingers are), it points at the place.-| `trigger` | On the pose: the index finger as `rightTrigger` takes it to 1. |++`gripPoseByJoint(pose)` writes any pose out joint by joint, holding the hand exactly as before: the starting point for changing one joint. `bend` and `fan` are measured on the hand's own axes, not a bone's, so a pose said joint by joint still fits any rig and either hand.## On your rig@@ -103,12 +107,34 @@ world.insert(hero, GripHolder, { held: rifle, placement: GripPlacement.Object })| `blendSeconds` | How long taking hold, letting go and changing what is held take. Every joint eases from where it was, from still and to rest, so no hand jumps. || `rightHand`, `leftHand` | The hand joints by path, where their names do not find them. |+| `GripProfile` field | What it does |+|---|---|+| `mainAnchor`, `supportAnchor` | The anchor entities. No supporting anchor holds the object in one hand. |+| `mainPose`, `supportPose` | Each hand's fingers: a grip pose by name, or a captured finger pose. |+| `mainFingers`, `supportFingers` | Each hand's fingers joint by joint, as JSON of a grip pose (the editor writes it). Over the pose by name where set. |+| `hand` | The hand the anchors were placed for. Held with the other hand leading, both are mirrored. |+| `mirror` | The object's own plane that mirrors them: the one square to its X (the default), Y or Z. |+It runs after the animator, in one order every frame, so nothing can drive itself round a loop: the clip's pose; then the object, on the leading hand or where the game put it; then the supporting anchor, read off the object as it now stands; then that arm; then the fingers of both. The object never reads the supporting hand. Each frame solves from the clip's pose, never from its own last answer, and nothing reads a clock but the game's: the same inputs and steps give the same bones, bit for bit.### Finger poses`captureFingerPose(world, handJoint)` takes the turn of every named joint under a hand as it stands, as plain JSON; `registerFingerPose(name, pose)` keeps it for a `GripProfile` to name. Pose the hand with a `GripPose`, a clip or by hand, capture it, and save the JSON with the game. A captured pose names its rig's bones, so it belongs to that rig; a grip pose by name fits any.+### The other hand++Anchors are placed once, for the hand `hand` names. A holder leading with the other hand gets both anchors mirrored in the object's `mirror` plane: their places reflected and their turns made the other hand's palm. Fingers by name, and fingers joint by joint, are a hand's shape rather than its bones, so they mirror too. A captured pose does not: it names one hand's bones.++### In the editor++Select an object with a `GripProfile`. Its section in Details edits the grip, and a character holding it shows the grip in the viewport as you change it, without Play:++- **Preview.** Pick the character. One without a `GripHolder` gets one, holding this object and placed by it, so it reaches for the object where it stands in the scene. The leading-hand switch sets the holder's `mainHand`, which is how to see the mirrored grip. A palm that cannot reach its anchor says how far short it stops.+- **Anchors.** Pick an entity, or Create one under the object. Select moves to it, for the move and rotate gizmos. The viewport draws each palm where it goes, mirrored when the other hand leads: a frame for the palm, an arrow the way the fingers point, a dashed line the way the palm faces, a stub on the thumb's side; amber for the leading hand, blue for the supporting one.+- **Fingers.** Start from a grip pose, then change any joint's bend or any finger's lean in degrees. The first change writes the pose out joint by joint into `mainFingers` or `supportFingers`; Reset goes back to the pose itself.++The preview is the viewport's **Preview FX**, the same switch spring bones use. It moves only the viewport's bones and the held object, never the scene, and turning it off gives them back as the scene has them.+### On another bodyAnchors are where a palm goes, not where a hand joint goes, and the arm is solved each frame from the body it is on, so a body with longer or shorter arms still puts its palm on the anchor. Past its reach, the arm points straight at the anchor and the wrist still turns to it: the palm stops short, the same way every time.@@ -116,7 +142,8 @@ Anchors are where a palm goes, not where a hand joint goes, and the arm is solve### Limits of holding- **The fingers do not fit the object.** A pose is set, not found on the surface: they can sink into a thick grip or stop short of a thin one. Fitting them to it is not built.-- **No editor for anchors or poses yet.** Anchors are moved with the ordinary gizmos; a finger pose is captured from code.+- **Fingers are edited as numbers.** There is no dragging a finger joint in the viewport, and a captured pose is not edited in the section.+- **A preview with no clip.** In the editor the character holds from the pose it stands in in the scene; how the grip sits over a clip is seen in Play.- **Only the supporting arm is bent with `Hand` placement,** and only the leading one is first with `Object`; a shoulder or the spine does not lean to help an arm reach.- **One object a holder.**diff --git a/docs/astro/src/content/docs/zh-cn/animation/grip-pose.mdx b/docs/astro/src/content/docs/zh-cn/animation/grip-pose.mdxindex 627fe1370..427080e85 100644--- a/docs/astro/src/content/docs/zh-cn/animation/grip-pose.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/grip-pose.mdx@@ -62,12 +62,16 @@ registerGripPose('claw', {| `curl` | 手指弯多少,0 是骨架静止状态,1 是完全握紧。 || `base` | 第一个关节弯多少,用于和其余关节不同的情况,比如手指沿枪身伸直或者勾起。默认等于 `curl`。 || `spread` | 手指张开多少,-1 到 1。 |+| `bend` | 每个关节相对放松姿势弯多少度,从根节开始:`[30, 45, 20]`。优先于 `curl` 和 `base`。编辑器写的就是它。 |+| `fan` | 这根手指偏离手掌中线多少度:食指和中指偏向拇指一侧,无名指和小指偏向另一侧。优先于 `spread`。 |+| `trigger` | 写在姿势上:`rightTrigger` 到 1 时食指的状态。 || `opposition` | 拇指:从静止位置走向目标的程度,0 到 1。 || `to` | 拇指:`fingers`(中指中节,用于握拳、握柄)或 `index`(食指指尖,用于捏合)。 || `gap` | 拇指:在目标前停多远,以食指长度为单位,相当于中间夹着的握把或杯子。 |拇指没有自己的弯曲数值,它是“去够”的:指尖走向其余手指当帧位置上的一个点(在手掌一侧),两个指节一起弯曲来够到它。所以握拳时拇指压在手指上,握东西时绕过握把。够不着时(比如手指伸直)就指向那个位置。-| `trigger` | 写在姿势上:`rightTrigger` 到 1 时食指的状态。 |++`gripPoseByJoint(pose)` 把任意姿势展开成逐个关节的形式,手的样子完全不变:这是改单个关节的起点。`bend` 和 `fan` 是按手掌自己的坐标轴量的,不是按骨骼,所以逐关节的姿势仍然适用于任何骨架和任意一只手。## 适配你的骨架@@ -103,12 +107,34 @@ world.insert(hero, GripHolder, { held: rifle, placement: GripPlacement.Object })| `blendSeconds` | 握住、松开、换物体分别花多久。每个关节都从原来的位置平滑过渡,起步和停止都平稳,手不会跳。 || `rightHand`、`leftHand` | 名字找不到手时,手部关节的路径。 |+| `GripProfile` 字段 | 作用 |+|---|---|+| `mainAnchor`、`supportAnchor` | 锚点实体。没有副手锚点就是单手握。 |+| `mainPose`、`supportPose` | 每只手的手指:GripPose 名字,或截取的手指姿势。 |+| `mainFingers`、`supportFingers` | 每只手逐个关节的手指,GripPose 的 JSON(编辑器写入)。设置后优先于名字。 |+| `hand` | 锚点是照哪只手摆的。另一只手主握时,两个锚点都会镜像。 |+| `mirror` | 用物体自己的哪个平面镜像:垂直于 X(默认)、Y 或 Z 的那个。 |+它在动画系统之后运行,每帧按固定顺序单向计算,所以不会形成循环:动画姿态;然后物体(跟着主手,或者在游戏放的位置);然后从物体当前位置读出副手锚点;然后副手手臂;最后两只手的手指。物体从不读取副手。每帧都从动画姿态开始求解,从不在自己上一帧的结果上继续;除了游戏时钟不读任何时钟。所以同样的输入和步进得到逐位相同的骨骼。### 手指姿势`captureFingerPose(world, handJoint)` 把手下面每个有名字的关节当前的旋转截取成普通 JSON;`registerFingerPose(name, pose)` 保存它,供 `GripProfile` 引用。用 GripPose、动画片段或手动摆好手型后截取下来,把 JSON 和游戏一起保存。截取的姿势用的是骨骼名字,所以属于那套骨架;GripPose 名字则适用于任何骨架。+### 另一只手++锚点只摆一次,按 `hand` 指定的那只手。持有者用另一只手主握时,两个锚点都按物体的 `mirror` 平面镜像:位置反射,朝向变成另一只手的掌心。按名字的手指和逐关节的手指描述的是手的形状而不是骨骼,所以同样会镜像。截取的姿势不会:它记录的是一只手的骨骼。++### 在编辑器里++选中带 `GripProfile` 的物体,细节面板里它的分区就是握持编辑;握着它的角色会在视口里实时显示握持,不用进 Play:++- **预览。** 选一个角色。没有 `GripHolder` 的会被加上一个,握住这个物体、摆放方式为物体,于是它会去够场景里物体所在的位置。主手开关改的是持有者的 `mainHand`,用它查看镜像后的握持。掌心够不着锚点时,会显示差多远。+- **锚点。** 选一个实体,或者在物体下新建一个。「选中」会切到它,用移动、旋转 gizmo 摆放。视口按实际使用的位置画出每个掌心(另一只手主握时画镜像后的):一个框表示掌心,箭头是手指方向,虚线是掌心朝向,短线在拇指一侧;主手黄色,副手蓝色。+- **手指。** 从一个 GripPose 开始,再按度数改任意关节的弯曲或任意手指的张开。第一次修改会把姿势逐关节写进 `mainFingers` 或 `supportFingers`;「重置」回到姿势本身。++预览用的是视口的 **预览特效** 开关,和弹簧骨同一个。它只动视口里的骨骼和被握的物体,不写场景;关掉后它们回到场景里的样子。+### 换一个体型锚点表示掌心的位置,不是手部关节的位置,手臂每帧按所在的身体求解,所以手臂更长或更短的身体仍然能把掌心放到锚点上。够不着时,手臂伸直指向锚点,手腕仍然转到锚点朝向:掌心停在锚点前方,每次结果都一样。@@ -116,7 +142,8 @@ world.insert(hero, GripHolder, { held: rifle, placement: GripPlacement.Object })### 握持的限制- **手指不贴合物体。** 姿势是设定好的,不是在表面上找到的:握把太粗时手指会陷进去,太细时碰不到。贴合还没有做。-- **还没有锚点和姿势的编辑器。** 锚点用普通 gizmo 移动,手指姿势要用代码截取。+- **手指用数值编辑。** 不能在视口里直接拖手指关节,截取的姿势也不能在面板里编辑。+- **预览没有动画。** 编辑器里角色从它在场景里的姿势出发去握;握持叠在动画上的效果要进 Play 看。- **`Hand` 模式只弯副手手臂,`Object` 模式先弯主手;** 肩膀和脊柱不会为了够到而倾斜。- **一个持有者只能握一个物体。**diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex be8d97da3..9562e1f8c 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 115,"beta": 178,- "experimental": 3005,+ "experimental": 3009,"deprecated": 3},- "total": 3298,+ "total": 3302,"subsystems": [{"id": "mobile-controls",diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 233707188..a794a3741 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -2916,11 +2916,48 @@"type": "string","default": "\"support\"","doc": "The supporting hand's fingers."+ },+ {+ "key": "mainFingers",+ "type": "string",+ "default": "empty",+ "doc": "The leading hand's fingers joint by joint, as JSON. Written by the grip editor; over mainPose where set.",+ "advanced": true+ },+ {+ "key": "supportFingers",+ "type": "string",+ "default": "empty",+ "doc": "The supporting hand's fingers joint by joint, as JSON.",+ "advanced": true+ },+ {+ "key": "hand",+ "type": "enum",+ "default": "Right",+ "doc": "The hand the anchors were placed for. Held with the other leading, they are mirrored.",+ "values": [+ "Right",+ "Left"+ ]+ },+ {+ "key": "mirror",+ "type": "enum",+ "default": "YZ (X)",+ "doc": "The object's own plane that mirrors the anchors to the other hand.",+ "values": [+ "YZ (X)",+ "XZ (Y)",+ "XY (Z)"+ ]}],"animatable": ["mainAnchor",- "supportAnchor"+ "supportAnchor",+ "hand",+ "mirror"]},{diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 358311a5b..66ed57296 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2130 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2134 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -5037,7 +5037,9 @@ static prototype: GridLayoutProvider## GripFinger — interface @experimental```base: number | undefined+bend: [number, number, number] | undefinedcurl: number+fan: number | undefinedspread: number | undefined```@@ -5072,6 +5074,11 @@ supportWeight: numberweight: number```+## GripMirror — const @experimental+```+{ readonly X: 0; readonly Y: 1; readonly Z: 2; }+```+## GripPlacement — const @experimental```{ readonly Hand: 0; readonly Object: 1; }@@ -5112,9 +5119,13 @@ ComponentDef<GripProfileData>## GripProfileData — interface @experimental```+hand: numbermainAnchor: number+mainFingers: stringmainPose: string+mirror: numbersupportAnchor: number+supportFingers: stringsupportPose: string```@@ -15925,7 +15936,7 @@ Plugin## gripHolderStatus — function @experimental```-(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; } | null+(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; short: { main: number; support: number; }; mirrored: boolean; palm: number; } | null```## gripPose — function @experimental@@ -15933,6 +15944,16 @@ Plugin(name: string): GripPoseDef | undefined```+## gripPoseByJoint — function @experimental+```+(pose: GripPoseDef): GripPoseDef+```++## gripPoseFromJson — function @experimental+```+(text: string): GripPoseDef | null+```+## gripPoseNames — function @experimental```(): string[]@@ -17133,6 +17154,11 @@ PrefabsPlugin(): (componentType: string) => readonly string[]```+## releaseGripHolds — function @experimental+```+(app: App): void+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex b7a04d3fe..c27ce7f3a 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 171 beta · 2150 experimental · 3 deprecated+Symbols: 115 public · 171 beta · 2154 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -5045,7 +5045,9 @@ static prototype: GridLayoutProvider## GripFinger — interface @experimental```base: number | undefined+bend: [number, number, number] | undefinedcurl: number+fan: number | undefinedspread: number | undefined```@@ -5080,6 +5082,11 @@ supportWeight: numberweight: number```+## GripMirror — const @experimental+```+{ readonly X: 0; readonly Y: 1; readonly Z: 2; }+```+## GripPlacement — const @experimental```{ readonly Hand: 0; readonly Object: 1; }@@ -5120,9 +5127,13 @@ ComponentDef<GripProfileData>## GripProfileData — interface @experimental```+hand: numbermainAnchor: number+mainFingers: stringmainPose: string+mirror: numbersupportAnchor: number+supportFingers: stringsupportPose: string```@@ -16186,7 +16197,7 @@ Plugin## gripHolderStatus — function @experimental```-(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; } | null+(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; short: { main: number; support: number; }; mirrored: boolean; palm: number; } | null```## gripPose — function @experimental@@ -16194,6 +16205,16 @@ Plugin(name: string): GripPoseDef | undefined```+## gripPoseByJoint — function @experimental+```+(pose: GripPoseDef): GripPoseDef+```++## gripPoseFromJson — function @experimental+```+(text: string): GripPoseDef | null+```+## gripPoseNames — function @experimental```(): string[]@@ -17404,6 +17425,11 @@ PrefabsPlugin(): (componentType: string) => readonly string[]```+## releaseGripHolds — function @experimental+```+(app: App): void+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex e7f125f39..15d96e10c 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 168 beta · 2129 experimental · 3 deprecated+Symbols: 115 public · 168 beta · 2133 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -5032,7 +5032,9 @@ static prototype: GridLayoutProvider## GripFinger — interface @experimental```base: number | undefined+bend: [number, number, number] | undefinedcurl: number+fan: number | undefinedspread: number | undefined```@@ -5067,6 +5069,11 @@ supportWeight: numberweight: number```+## GripMirror — const @experimental+```+{ readonly X: 0; readonly Y: 1; readonly Z: 2; }+```+## GripPlacement — const @experimental```{ readonly Hand: 0; readonly Object: 1; }@@ -5107,9 +5114,13 @@ ComponentDef<GripProfileData>## GripProfileData — interface @experimental```+hand: numbermainAnchor: number+mainFingers: stringmainPose: string+mirror: numbersupportAnchor: number+supportFingers: stringsupportPose: string```@@ -15920,7 +15931,7 @@ Plugin## gripHolderStatus — function @experimental```-(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; } | null+(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; short: { main: number; support: number; }; mirrored: boolean; palm: number; } | null```## gripPose — function @experimental@@ -15928,6 +15939,16 @@ Plugin(name: string): GripPoseDef | undefined```+## gripPoseByJoint — function @experimental+```+(pose: GripPoseDef): GripPoseDef+```++## gripPoseFromJson — function @experimental+```+(text: string): GripPoseDef | null+```+## gripPoseNames — function @experimental```(): string[]@@ -17138,6 +17159,11 @@ PrefabsPlugin(): (componentType: string) => readonly string[]```+## releaseGripHolds — function @experimental+```+(app: App): void+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 16887b716..80e5d86df 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2151 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2155 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -5032,7 +5032,9 @@ static prototype: GridLayoutProvider## GripFinger — interface @experimental```base: number | undefined+bend: [number, number, number] | undefinedcurl: number+fan: number | undefinedspread: number | undefined```@@ -5067,6 +5069,11 @@ supportWeight: numberweight: number```+## GripMirror — const @experimental+```+{ readonly X: 0; readonly Y: 1; readonly Z: 2; }+```+## GripPlacement — const @experimental```{ readonly Hand: 0; readonly Object: 1; }@@ -5107,9 +5114,13 @@ ComponentDef<GripProfileData>## GripProfileData — interface @experimental```+hand: numbermainAnchor: number+mainFingers: stringmainPose: string+mirror: numbersupportAnchor: number+supportFingers: stringsupportPose: string```@@ -16227,7 +16238,7 @@ Plugin## gripHolderStatus — function @experimental```-(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; } | null+(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; short: { main: number; support: number; }; mirrored: boolean; palm: number; } | null```## gripPose — function @experimental@@ -16235,6 +16246,16 @@ Plugin(name: string): GripPoseDef | undefined```+## gripPoseByJoint — function @experimental+```+(pose: GripPoseDef): GripPoseDef+```++## gripPoseFromJson — function @experimental+```+(text: string): GripPoseDef | null+```+## gripPoseNames — function @experimental```(): string[]@@ -17445,6 +17466,11 @@ PrefabsPlugin(): (componentType: string) => readonly string[]```+## releaseGripHolds — function @experimental+```+(app: App): void+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 221d030bb..3b51c3935 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2142 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2146 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -5032,7 +5032,9 @@ static prototype: GridLayoutProvider## GripFinger — interface @experimental```base: number | undefined+bend: [number, number, number] | undefinedcurl: number+fan: number | undefinedspread: number | undefined```@@ -5067,6 +5069,11 @@ supportWeight: numberweight: number```+## GripMirror — const @experimental+```+{ readonly X: 0; readonly Y: 1; readonly Z: 2; }+```+## GripPlacement — const @experimental```{ readonly Hand: 0; readonly Object: 1; }@@ -5107,9 +5114,13 @@ ComponentDef<GripProfileData>## GripProfileData — interface @experimental```+hand: numbermainAnchor: number+mainFingers: stringmainPose: string+mirror: numbersupportAnchor: number+supportFingers: stringsupportPose: string```@@ -15953,7 +15964,7 @@ Plugin## gripHolderStatus — function @experimental```-(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; } | null+(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity; short: { main: number; support: number; }; mirrored: boolean; palm: number; } | null```## gripPose — function @experimental@@ -15961,6 +15972,16 @@ Plugin(name: string): GripPoseDef | undefined```+## gripPoseByJoint — function @experimental+```+(pose: GripPoseDef): GripPoseDef+```++## gripPoseFromJson — function @experimental+```+(text: string): GripPoseDef | null+```+## gripPoseNames — function @experimental```(): string[]@@ -17171,6 +17192,11 @@ PrefabsPlugin(): (componentType: string) => readonly string[]```+## releaseGripHolds — function @experimental+```+(app: App): void+```+## remapComponentEntityRefs — function @experimental```(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): voiddiff --git a/sdk/src/animation/gripHold.ts b/sdk/src/animation/gripHold.tsindex d7343cb32..971e28860 100644--- a/sdk/src/animation/gripHold.ts+++ b/sdk/src/animation/gripHold.ts@@ -18,12 +18,12 @@ import { defineSystem, GetWorld, Schedule } from '../ecs/system';import { Res, Time, type TimeData } from '../ecs/resource';import type { World } from '../ecs/world';import { resolveChildEntity } from '../ecs/childPath';-import { playModeOnly } from '../ecs/env';+import { fxPreviewOrPlayMode } from '../ecs/env';import { SystemLabel } from '../ecs/systemLabels';import { log } from '../util/logger';import { q } from '../math/quat';import type { Entity } from '../types';-import { findHand, gripPose, GripPose, palmFrameOf, type GripPoseData } from './gripPose';+import { askHeldHands, findHand, gripPose, gripPoseFromJson, palmFrameOf, releaseGripPoses, type GripPoseDef, type HeldHand } from './gripPose';interface Vec3 { x: number; y: number; z: number }interface Quat { w: number; x: number; y: number; z: number }@@ -37,18 +37,32 @@ export interface GripProfileData {/** The fingers of each: a pose captured from a hand (registerFingerPose), or a GripPose by name. */mainPose: string;supportPose: string;+ /** The fingers of each said joint by joint, as JSON of a GripPoseDef (an editor writes it). Over the pose by name where it is set. */+ mainFingers: string;+ supportFingers: string;+ /** The hand the anchors were placed for. Held with the other hand leading, both anchors are mirrored to it. */+ hand: number;+ /** The plane of the object's own that mirrors them: the one square to its X, Y or Z. */+ mirror: number;}+/** The plane an object's anchors are mirrored in, by the axis square to it. @experimental */+export const GripMirror = { X: 0, Y: 1, Z: 2 } as const;+/*** How an object is held. Goes on the object; its anchors are entities under it.** @experimental*/export const GripProfile: ComponentDef<GripProfileData> = /* @__PURE__ */ defineComponent<GripProfileData>('GripProfile', {- mainAnchor: 0 as Entity, supportAnchor: 0 as Entity, mainPose: 'handle', supportPose: 'support',+ mainAnchor: 0 as Entity, supportAnchor: 0 as Entity, mainPose: 'handle', supportPose: 'support', mainFingers: '', supportFingers: '', hand: 0, mirror: 0,}, {entityFields: ['mainAnchor', 'supportAnchor'],fields: {+ mainFingers: { advanced: true, tooltip: 'The leading hand\'s fingers joint by joint, as JSON. Written by the grip editor; over mainPose where set.' },+ supportFingers: { advanced: true, tooltip: 'The supporting hand\'s fingers joint by joint, as JSON.' },+ hand: { enum: [{ label: 'Right', value: 0 }, { label: 'Left', value: 1 }], tooltip: 'The hand the anchors were placed for. Held with the other leading, they are mirrored.' },+ mirror: { enum: [{ label: 'YZ (X)', value: 0 }, { label: 'XZ (Y)', value: 1 }, { label: 'XY (Z)', value: 2 }], tooltip: 'The object\'s own plane that mirrors the anchors to the other hand.' },mainAnchor: { tooltip: 'Where the leading palm sits: an entity under this one. Its +Z is the way the fingers point, +Y the way the palm faces.' },supportAnchor: { tooltip: 'Where the supporting palm sits. Empty holds this in one hand.' },mainPose: { tooltip: 'The leading hand\'s fingers: a captured finger pose, or a grip pose (pistol, handle, support, ...).' },@@ -186,6 +200,13 @@ function anchorOn(world: World, object: Entity, anchor: Entity): Pose3 | null {return null;}+/** An anchor's pose on its object, mirrored in the plane square to one of the object's axes: what the other hand's palm takes there. */+function mirrored(a: Pose3, axis: number): Pose3 {+ const p = { ...a.p }, r = { ...a.r };+ if (axis === 1) { p.y = -p.y; r.x = -r.x; r.z = -r.z; } else if (axis === 2) { p.z = -p.z; r.x = -r.x; r.y = -r.y; } else { p.x = -p.x; r.y = -r.y; r.z = -r.z; }+ return { p, r, s: a.s };+}+/** One hand's arm and palm, found once. */interface Arm {hand: Entity;@@ -230,6 +251,13 @@ interface HolderState {written: Map<Entity, Quat>;/** Each joint's turn as something else last left it: the clip's, which a hold goes over. */base: Map<Entity, Quat>;+ /** Each object it carried on a hand: where it was before, and where this last put it, to give it back when a preview ends. */+ carried: Map<Entity, { rest: { p: Vec3; r: Quat }; put: { p: Vec3; r: Quat } }>;+ /** The fingers last asked of each hand, faded out by `amount` once nothing is held. */+ asked: { right?: HeldHand & { share: number }; left?: HeldHand & { share: number } };+ /** How far each palm stops short of its anchor, as the arm reaches: 0 within reach. */+ short: { main: number; support: number };+ mirrored: boolean;}/** Eases `value` toward `wanted`, critically damped: from still, and to rest without passing it. */@@ -248,14 +276,15 @@ function ease(value: number, speed: number, wanted: number, blend: number, dt: n* The upper arm and forearm turned so the hand joint lands on `goal`, the elbow keeping the side it is bent toward; then the hand turned to `handTurn`.* World turns in, each joint's own turn out. The arm cannot be longer than it is: past its reach it points straight at the goal.*/-function bendArm(world: World, arm: Arm, goal: Vec3, handTurn: Quat): Map<Entity, Quat> {+function bendArm(world: World, arm: Arm, goal: Vec3, handTurn: Quat): Map<Entity, Quat> & { short?: number } {const upper = worldOf(world, arm.upper), fore = worldOf(world, arm.forearm), hand = worldOf(world, arm.hand);const shoulder = parentOf(world, arm.upper);const shoulderTurn = shoulder === null ? { w: 1, x: 0, y: 0, z: 0 } : worldOf(world, shoulder).r;const a = len(sub(fore.p, upper.p)), b = len(sub(hand.p, fore.p));const reach = sub(goal, upper.p);- const out = new Map<Entity, Quat>();+ const out: Map<Entity, Quat> & { short?: number } = new Map<Entity, Quat>();if (a < 1e-9 || b < 1e-9 || len(reach) < 1e-9) return out;+ out.short = Math.max(0, len(reach) - (a + b));const c = Math.min(Math.max(len(reach), Math.abs(a - b) + 1e-6), a + b - 1e-6);const along = norm(reach);// The side the elbow is bent to now; a straight arm takes any side off the line.@@ -316,17 +345,59 @@ export function installGripHold(app: App): void {}}if (restored) world.ensureTransformsComposed();- for (const rig of holders) hold(world, known, rig, world.get(rig, GripHolder) as GripHolderData, time.delta);- }, { name: 'GripHoldSystem' }), { runAfter: [SystemLabel.Animator], runIf: playModeOnly });+ for (const rig of holders) hold(app, world, known, rig, world.get(rig, GripHolder) as GripHolderData, time.delta);+ }, { name: 'GripHoldSystem' }), { runAfter: [SystemLabel.Animator], runIf: fxPreviewOrPlayMode });+}++/**+ * Every joint a hold turned, and every object it carried, given back as they were before it, and every holder forgotten: an editor leaving its+ * preview, where nothing moves the bones back. What something else has moved since is left as it is. @experimental+ */+export function releaseGripHolds(app: App): void {+ const world = app.world;+ const known = rigs.get(app);+ for (const state of known?.values() ?? []) {+ for (const [joint, written] of state.written) {+ const base = state.base.get(joint);+ if (!base || !world.valid(joint) || !world.has(joint, Transform)) continue;+ if (same((world.get(joint, Transform) as TransformData).rotation, written)) world.update(joint, Transform, (t: TransformData) => { t.rotation = { ...base }; });+ }+ for (const [object, { rest, put }] of state.carried) {+ if (!world.valid(object) || !world.has(object, Transform)) continue;+ const t0 = world.get(object, Transform) as TransformData;+ if (near(t0.position, put.p) && same(t0.rotation, put.r)) world.update(object, Transform, (t: TransformData) => { t.position = { ...rest.p }; t.rotation = { ...rest.r }; });+ }+ }+ known?.clear();+ releaseGripPoses(app);+}++const near = (a: Vec3, b: Vec3): boolean => Math.abs(a.x - b.x) < 1e-6 && Math.abs(a.y - b.y) < 1e-6 && Math.abs(a.z - b.z) < 1e-6;++/** Inline finger poses read once per text. */+const parsedFingers = new Map<string, GripPoseDef | null>();+function inlineFingers(text: string): GripPoseDef | null {+ if (!text) return null;+ let pose = parsedFingers.get(text);+ if (pose === undefined) {+ if (parsedFingers.size > 64) parsedFingers.clear();+ pose = gripPoseFromJson(text);+ if (!pose) log.warn('animation', 'a GripProfile\'s fingers are not a grip pose in JSON: the pose by name is used');+ parsedFingers.set(text, pose);+ }+ return pose;}-function hold(world: World, known: Map<Entity, HolderState>, rig: Entity, data: GripHolderData, dt: number): void {+function hold(app: App, world: World, known: Map<Entity, HolderState>, rig: Entity, data: GripHolderData, dt: number): void {const paths = `${data.rightHand}|${data.leftHand}`;let state = known.get(rig);if (!state || state.paths !== paths) {const right = armOf(world, rig, 'right', data.rightHand), left = armOf(world, rig, 'left', data.leftHand);if (!right && !left) log.warn('animation', `a GripHolder found no arm with a hand on "${(world.tryGet(rig, Name) as { value?: string } | null)?.value ?? rig}"`);- state = { arms: { right, left }, paths, held: 0 as Entity, amount: 0, speed: 0, from: new Map(), change: 1, changeSpeed: 0, written: new Map(), base: new Map() };+ state = {+ arms: { right, left }, paths, held: 0 as Entity, amount: 0, speed: 0, from: new Map(), change: 1, changeSpeed: 0, written: new Map(), base: new Map(),+ carried: new Map(), asked: {}, short: { main: 0, support: 0 }, mirrored: false,+ };known.set(rig, state);}const held = data.held && world.valid(data.held) && world.has(data.held, GripProfile) ? data.held : 0 as Entity;@@ -342,12 +413,16 @@ function hold(world: World, known: Map<Entity, HolderState>, rig: Entity, data:const main = data.mainHand === GripHand.Left ? state.arms.left : state.arms.right;const support = data.mainHand === GripHand.Left ? state.arms.right : state.arms.left;const wanted = new Map<Entity, Quat>();- const fingerNames: { arm: Arm; pose: string; weight: number }[] = [];+ const fingerNames: { arm: Arm; pose: string; inline: string; weight: number }[] = [];+ state.short = { main: 0, support: 0 };if (held && main) {const profile = world.get(held, GripProfile) as GripProfileData;- const mainAnchor = profile.mainAnchor ? anchorOn(world, held, profile.mainAnchor) : null;- const supportAnchor = profile.supportAnchor ? anchorOn(world, held, profile.supportAnchor) : null;+ // Placed for the other hand: both anchors mirrored in the object's own plane, so one set serves either.+ state.mirrored = data.mainHand !== profile.hand;+ const place = (anchor: Pose3 | null): Pose3 | null => (anchor && state!.mirrored ? mirrored(anchor, profile.mirror) : anchor);+ const mainAnchor = place(profile.mainAnchor ? anchorOn(world, held, profile.mainAnchor) : null);+ const supportAnchor = place(profile.supportAnchor ? anchorOn(world, held, profile.supportAnchor) : null);if (mainAnchor) {const handWorld = worldOf(world, main.hand);let object: Pose3;@@ -355,48 +430,68 @@ function hold(world: World, known: Map<Entity, HolderState>, rig: Entity, data:// The game has put the object: the leading arm is brought to its anchor.object = worldOf(world, held);const goal = handFor(main, then(object, mainAnchor), handWorld.s);- for (const [joint, turn] of bendArm(world, main, goal.at, goal.turn)) wanted.set(joint, turn);+ const turns = bendArm(world, main, goal.at, goal.turn);+ for (const [joint, turn] of turns) wanted.set(joint, turn);+ state.short.main = turns.short ?? 0;} else {// The object rides the leading hand, wherever the clip has put it.object = then(then(handWorld, main.palm), inverse(mainAnchor));const parent = parentOf(world, held);const local = parent === null ? object : then(inverse(worldOf(world, parent)), object);+ const before = world.get(held, Transform) as TransformData;+ const carried = state.carried.get(held);+ if (!carried || !(near(before.position, carried.put.p) && same(before.rotation, carried.put.r))) {+ state.carried.set(held, { rest: { p: { ...before.position }, r: { ...before.rotation } }, put: { p: { ...before.position }, r: { ...before.rotation } } });+ }world.update(held, Transform, (t: TransformData) => {t.position = { ...local.p };t.rotation = { ...local.r };});+ const after = world.get(held, Transform) as TransformData;+ state.carried.get(held)!.put = { p: { ...after.position }, r: { ...after.rotation } };}- fingerNames.push({ arm: main, pose: profile.mainPose, weight: 1 });+ fingerNames.push({ arm: main, pose: profile.mainPose, inline: profile.mainFingers, weight: 1 });const supportWeight = Math.min(1, Math.max(0, data.supportWeight));if (support && supportAnchor && supportWeight > 0) {// Read off the object as it now stands; the object never reads this hand.const goal = handFor(support, then(object, supportAnchor), worldOf(world, support.hand).s);- for (const [joint, turn] of bendArm(world, support, goal.at, goal.turn)) {+ const turns = bendArm(world, support, goal.at, goal.turn);+ for (const [joint, turn] of turns) {wanted.set(joint, turn);supportWeights.set(joint, supportWeight);}- fingerNames.push({ arm: support, pose: profile.supportPose, weight: supportWeight });+ state.short.support = turns.short ?? 0;+ fingerNames.push({ arm: support, pose: profile.supportPose, inline: profile.supportFingers, weight: supportWeight });}}}- // The fingers last: a captured pose by joint, or a grip pose handed to the GripPose that holds the hand.- const presets: Partial<GripPoseData> = {};- for (const { arm, pose, weight } of fingerNames) {- const captured = capturedFingers(arm, pose);+ // The fingers last: a pose said joint by joint on the profile, a captured one by joint name, or a grip pose by name; the last two kinds are handed+ // to the grip-pose system, which eases them on over whatever else holds that hand.+ const now: HolderState['asked'] = {};+ for (const { arm, pose, inline, weight } of fingerNames) {+ const side = arm === state.arms.right ? 'right' : 'left';+ const joints = inlineFingers(inline);+ const captured = joints ? null : capturedFingers(arm, pose);if (captured) {for (const [joint, turn] of captured) { wanted.set(joint, turn); supportWeights.set(joint, weight); }+ } else if (joints) {+ now[side] = { key: inline, pose: joints, weight: 0, share: weight };} else if (gripPose(pose)) {- const right = arm === state.arms.right;- if (right) { presets.rightPose = pose; presets.rightWeight = state.amount * weight; } else { presets.leftPose = pose; presets.leftWeight = state.amount * weight; }+ now[side] = { key: pose, pose: gripPose(pose)!, weight: 0, share: weight };}}- if (Object.keys(presets).length || world.has(rig, GripPose)) {- if (!world.has(rig, GripPose)) world.insert(rig, GripPose, { blendSeconds: data.blendSeconds });- world.update(rig, GripPose, (g: GripPoseData) => {- if (presets.rightPose !== undefined) { g.rightPose = presets.rightPose; g.rightWeight = presets.rightWeight!; } else if (state!.amount === 0) g.rightWeight = 0;- if (presets.leftPose !== undefined) { g.leftPose = presets.leftPose; g.leftWeight = presets.leftWeight!; } else if (state!.amount === 0) g.leftWeight = 0;- });+ // Let go of, the last grip fades out with the hold; held, what is asked now.+ if (held && main) state.asked = now;+ if (state.amount > 0 || held) {+ const hands = { blendSeconds: data.blendSeconds, rightHand: data.rightHand, leftHand: data.leftHand } as Parameters<typeof askHeldHands>[2];+ for (const side of ['right', 'left'] as const) {+ const a = state.asked[side];+ if (a) hands[side] = { key: a.key, pose: a.pose, weight: state.amount * a.share };+ }+ if (hands.right || hands.left) askHeldHands(app, rig, hands);+ } else {+ state.asked = {};}// Every joint once: the clip's turn, toward the hold's by how much of it applies, and from the old grip by how far the change has come.@@ -427,7 +522,16 @@ const supportWeights = new Map<Entity, number>();const same = (a: Quat, b: Quat): boolean => Math.abs(a.w - b.w) < 1e-6 && Math.abs(a.x - b.x) < 1e-6 && Math.abs(a.y - b.y) < 1e-6 && Math.abs(a.z - b.z) < 1e-6;/** What a holder found and is doing. @experimental */-export function gripHolderStatus(app: App, rig: Entity): { right: boolean; left: boolean; amount: number; held: Entity } | null {+export function gripHolderStatus(app: App, rig: Entity): {+ right: boolean; left: boolean; amount: number; held: Entity;+ /** How far each palm stops short of its anchor, in world units: 0 where the arm reaches it. */+ short: { main: number; support: number };+ /** Whether the anchors are mirrored this frame: held by the other hand than they were placed for. */+ mirrored: boolean;+ /** How long the palm is, from the wrist to the middle knuckle, in the hand's own units: what an editor sizes an anchor's marker by. 0 with no hand found. */+ palm: number;+} | null {const state = rigs.get(app)?.get(rig);- return state ? { right: !!state.arms.right, left: !!state.arms.left, amount: state.amount, held: state.held } : null;+ const arm = state?.arms.right ?? state?.arms.left;+ return state ? { right: !!state.arms.right, left: !!state.arms.left, amount: state.amount, held: state.held, short: { ...state.short }, mirrored: state.mirrored, palm: arm ? 2 * len(arm.palm.p) : 0 } : null;}diff --git a/sdk/src/animation/gripPose.ts b/sdk/src/animation/gripPose.tsindex 18b8d6c35..32114d20b 100644--- a/sdk/src/animation/gripPose.ts+++ b/sdk/src/animation/gripPose.ts@@ -18,7 +18,7 @@ import { defineSystem, GetWorld, Schedule } from '../ecs/system';import { Res, Time, type TimeData } from '../ecs/resource';import type { World } from '../ecs/world';import { resolveChildEntity } from '../ecs/childPath';-import { playModeOnly } from '../ecs/env';+import { fxPreviewOrPlayMode } from '../ecs/env';import { SystemLabel } from '../ecs/systemLabels';import { log } from '../util/logger';import { q } from '../math/quat';@@ -33,6 +33,10 @@ export interface GripFinger {base?: number;/** How far the fingers fan out from one another, -1 to 1. */spread?: number;+ /** Each joint's bend, knuckle first, in degrees from where the rig rests: what a hand posed joint by joint keeps. Over `curl` and `base`. */+ bend?: [number, number, number];+ /** How far this finger leans out from the middle of the hand, in degrees: the index and middle toward the thumb, the ring and little finger away. Over `spread`. */+ fan?: number;}/** How the thumb is held: as a reach, since where it can rest is somewhere on the other fingers. @experimental */@@ -173,25 +177,90 @@ interface Joint {/** A finger's joints, knuckle first. Those it has no joint for are left out. */type Finger = { name: FingerName; joints: Joint[]; fan: number };-/** Numbers a hand is held by, kept flat so two poses can be eased between: curl, base, spread for each finger, then the thumb's reach, how much of it is for the index tip, and its gap. */-const NUMBERS = FINGERS.length * 3 + 3;+/** Numbers a hand is held by, kept flat so two poses can be eased between: each finger's three joint bends and its lean (radians), then the thumb's reach, how much of it is for the index tip, and its gap. */+const PER_FINGER = 4;+const NUMBERS = FINGERS.length * PER_FINGER + 3;const REACH = NUMBERS - 3, TO_INDEX = NUMBERS - 2, GAP = NUMBERS - 1;+/** Which way a positive `fan` leans each finger along its spread axis: out from the middle of the hand. */+const FAN_SIDE: Record<FingerName, number> = { thumb: 0, index: 1, middle: 1, ring: -1, pinky: -1 };+const RAD = Math.PI / 180;+const clampTo = (v: number, lo: number, hi: number): number => (v > lo ? (v < hi ? v : hi) : lo);++/** A finger's three joint bends and its lean, in radians: a bend by joint where it says one, else its curl and base. */+function anglesOf(name: FingerName, finger: GripFinger | undefined): [number, number, number, number] {+ const curl = clamp01(finger?.curl ?? 0), base = clamp01(finger?.base ?? finger?.curl ?? 0);+ const bend = (i: number, fallback: number): number => {+ const deg = finger?.bend?.[i];+ return typeof deg === 'number' && Number.isFinite(deg) ? clampTo(deg, -45, 130) * RAD : fallback;+ };+ const fan = finger?.fan;+ return [+ bend(0, base * CLOSED[0]!), bend(1, curl * CLOSED[1]!), bend(2, curl * CLOSED[2]!),+ typeof fan === 'number' && Number.isFinite(fan) ? FAN_SIDE[name] * clampTo(fan, -30, 30) * RAD : clampTo(finger?.spread ?? 0, -1, 1) * FAN[name] * SPREAD,+ ];+}+function numbersOf(pose: GripPoseDef | null, out: Float64Array): void {let i = 0;for (const name of FINGERS) {- const finger = name === 'thumb' ? undefined : pose?.[name];- out[i++] = clamp01(finger?.curl ?? 0);- out[i++] = clamp01(finger?.base ?? finger?.curl ?? 0);- out[i++] = Math.max(-1, Math.min(1, finger?.spread ?? 0));+ const angles = name === 'thumb' ? [0, 0, 0, 0] : anglesOf(name, pose?.[name]);+ for (const a of angles) out[i++] = a;}- out[REACH] = clamp01(pose?.thumb.opposition ?? 0);- out[TO_INDEX] = pose?.thumb.to === 'index' ? 1 : 0;- out[GAP] = Math.max(0, pose?.thumb.gap ?? 0);+ out[REACH] = clamp01(pose?.thumb?.opposition ?? 0);+ out[TO_INDEX] = pose?.thumb?.to === 'index' ? 1 : 0;+ out[GAP] = Math.max(0, pose?.thumb?.gap ?? 0);}const clamp01 = (v: number): number => (v > 0 ? (v < 1 ? v : 1) : 0);+/**+ * A pose with every finger said joint by joint, in degrees: what an editor starts from when a preset is to be changed one joint at a time. It holds+ * the hand exactly as the preset does.+ *+ * @experimental+ */+export function gripPoseByJoint(pose: GripPoseDef): GripPoseDef {+ const deg = (r: number): number => Math.round((r / RAD) * 10) / 10;+ const byJoint = (name: FingerName, finger: GripFinger | undefined): GripFinger => {+ const [a0, a1, a2, lean] = anglesOf(name, finger);+ const side = FAN_SIDE[name];+ return { curl: finger?.curl ?? 0, bend: [deg(a0), deg(a1), deg(a2)], fan: side ? deg(lean / side) : 0 };+ };+ const out: GripPoseDef = {+ thumb: { opposition: clamp01(pose.thumb?.opposition ?? 0), to: pose.thumb?.to === 'index' ? 'index' : 'fingers', gap: Math.max(0, pose.thumb?.gap ?? 0) },+ index: byJoint('index', pose.index), middle: byJoint('middle', pose.middle), ring: byJoint('ring', pose.ring), pinky: byJoint('pinky', pose.pinky),+ };+ if (pose.trigger) out.trigger = byJoint('index', pose.trigger);+ return out;+}++/** A pose read from JSON as an editor writes it, any part it leaves out taken as open. Null for text that is not one. @experimental */+export function gripPoseFromJson(text: string): GripPoseDef | null {+ if (!text) return null;+ let raw: unknown;+ try { raw = JSON.parse(text); } catch { return null; }+ if (!raw || typeof raw !== 'object') return null;+ const o = raw as Record<string, unknown>;+ const num = (v: unknown): number | undefined => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);+ const finger = (v: unknown): GripFinger => {+ const f = (v && typeof v === 'object' ? v : {}) as Record<string, unknown>;+ const out: GripFinger = { curl: num(f.curl) ?? 0 };+ if (num(f.base) !== undefined) out.base = num(f.base);+ if (num(f.spread) !== undefined) out.spread = num(f.spread);+ if (Array.isArray(f.bend) && f.bend.length === 3 && f.bend.every((x) => num(x) !== undefined)) out.bend = [f.bend[0], f.bend[1], f.bend[2]] as [number, number, number];+ if (num(f.fan) !== undefined) out.fan = num(f.fan);+ return out;+ };+ const t = (o.thumb && typeof o.thumb === 'object' ? o.thumb : {}) as Record<string, unknown>;+ const pose: GripPoseDef = {+ thumb: { opposition: num(t.opposition) ?? 0, to: t.to === 'index' ? 'index' : 'fingers', gap: num(t.gap) ?? 0 },+ index: finger(o.index), middle: finger(o.middle), ring: finger(o.ring), pinky: finger(o.pinky),+ };+ if (o.trigger) pose.trigger = finger(o.trigger);+ return pose;+}+/** What is known of one hand on one rig. */interface HandState {hand: Entity;@@ -453,7 +522,7 @@ export function findHand(world: World, root: Entity, side: 'right' | 'left'): En}/** What one rig's hands are doing. */-interface RigState { right: HandState | null; left: HandState | null; rightHand: string; leftHand: string; tried: { right: boolean; left: boolean } }+interface RigState { right: HandState | null; left: HandState | null; rightHand: string; leftHand: string; tried: { right: boolean; left: boolean }; byComponent: boolean; blend: number }const SAME = 1e-6;const same = (a: Quat, b: Quat): boolean => Math.abs(a.w - b.w) < SAME && Math.abs(a.x - b.x) < SAME && Math.abs(a.y - b.y) < SAME && Math.abs(a.z - b.z) < SAME;@@ -475,9 +544,9 @@ function ease(value: number, wanted: number, state: HandState, slot: number, blereturn next;}-/** Holds one hand a frame: eases its numbers on, and turns each joint to them over what is there. */-function holdHand(world: World, state: HandState, poseName: string, weight: number, trigger: number, blend: number, dt: number, moved: boolean): void {- const pose = poseName ? poses.get(poseName) ?? null : null;+/** Holds one hand a frame: eases its numbers on, and turns each joint to them over what is there. `poseName` tells one pose from the next; `def` is it. */+function holdHand(world: World, state: HandState, poseName: string, def: GripPoseDef | null, weight: number, trigger: number, blend: number, dt: number, moved: boolean): void {+ const pose = poseName ? def : null;if (poseName !== state.pose) {if (poseName && !pose) log.warn('animation', `there is no grip pose called "${poseName}": the hand is left alone`);state.pose = poseName;@@ -504,12 +573,12 @@ function holdHand(world: World, state: HandState, poseName: string, weight: numbconst ordered = [...state.fingers.filter((x) => x.name !== 'thumb'), ...state.fingers.filter((x) => x.name === 'thumb')];for (const finger of ordered) {const reached = finger.name === 'thumb' && state.thumb ? thumbTurns(world, state) : null;- const at = FINGERS.indexOf(finger.name) * 3;- let curl = state.current[at]!, base = state.current[at + 1]!;- const spread = state.current[at + 2]!;+ const at = FINGERS.indexOf(finger.name) * PER_FINGER;+ const bends = [state.current[at]!, state.current[at + 1]!, state.current[at + 2]!];+ const lean = state.current[at + 3]!;if (finger.name === 'index' && press > 0 && pose?.trigger) {- curl += (clamp01(pose.trigger.curl) - curl) * press;- base += (clamp01(pose.trigger.base ?? pose.trigger.curl) - base) * press;+ const pressed = anglesOf('index', pose.trigger);+ for (let i = 0; i < 3; i++) bends[i] = bends[i]! + (pressed[i]! - bends[i]!) * press;}for (let i = 0; i < finger.joints.length; i++) {const joint = finger.joints[i]!;@@ -519,8 +588,8 @@ function holdHand(world: World, state: HandState, poseName: string, weight: numbconst parent = i === 0 ? state.thumb!.parentTurn : reached[i - 1]!;target = q.normalize(q.mul(q.conjugate(parent), reached[i]!));} else {- let turn = axisAngle(joint.curlAxis, (i === 0 ? base : curl) * CLOSED[i]!);- if (joint.spreadAxis && spread !== 0 && finger.fan !== 0) turn = q.mul(axisAngle(joint.spreadAxis, spread * finger.fan * SPREAD), turn);+ let turn = axisAngle(joint.curlAxis, bends[i]!);+ if (joint.spreadAxis && lean !== 0) turn = q.mul(axisAngle(joint.spreadAxis, lean), turn);target = q.normalize(q.mul(joint.rest, turn));}const local = world.get(joint.entity, Transform) as TransformData;@@ -574,6 +643,33 @@ function letGo(world: World, state: HandState | null): void {}}+/**+ * A hand pose something else asks of a rig each frame: a holder handing the fingers its grip. Over the rig's own GripPose for that hand, if it has+ * one. `key` tells one pose from the next. @internal+ */+export interface HeldHand { key: string; pose: GripPoseDef | null; weight: number }+/** @internal */+export interface HeldHands { right?: HeldHand; left?: HeldHand; blendSeconds: number; rightHand: string; leftHand: string }++const asked = new WeakMap<App, Map<Entity, HeldHands>>();++/** Asks for a rig's hands this frame. Read by the next run of the grip-pose system, then forgotten. @internal */+export function askHeldHands(app: App, rig: Entity, hands: HeldHands): void {+ let map = asked.get(app);+ if (!map) { map = new Map(); asked.set(app, map); }+ map.set(rig, hands);+}++/** Every hand this has posed put back as the rig rests, and forgotten: an editor leaving its preview. @internal */+export function releaseGripPoses(app: App): void {+ const known = rigs.get(app);+ if (known) {+ for (const state of known.values()) { letGo(app.world, state.right); letGo(app.world, state.left); }+ known.clear();+ }+ asked.get(app)?.clear();+}+/** What a rig's hand was found to have. @experimental */export interface GripHandStatus {/** The joint it took for the hand, or null where none could be found. */@@ -608,37 +704,59 @@ export function installGripPose(app: App): void {const hasClipOn = (world: World, rig: Entity): boolean => ['Animator', 'TimelinePlayer'].some((name) => { const def = getComponent(name); return !!def && world.has(rig, def); });// system-access: the hand's joints are found by walking the rig, so which entities it writes is known only then, and only their Transforms.app.addSystemToSchedule(Schedule.Update, defineSystem([Res(Time), GetWorld()], (time: TimeData, world: World) => {+ const wanted = asked.get(app) ?? new Map<Entity, HeldHands>();+ asked.set(app, wanted);+ const comps = new Set(world.getEntitiesWithComponents([GripPose]));for (const [rig, state] of known) {- if (world.valid(rig) && world.has(rig, GripPose)) continue;- letGo(world, state.right);- letGo(world, state.left);- known.delete(rig);+ if (!world.valid(rig)) { known.delete(rig); continue; }+ if (comps.has(rig) || wanted.has(rig)) continue;+ // A component taken off lets go at once, as it always has; hands a holder stopped asking for fade out below.+ if (state.byComponent) { letGo(world, state.right); letGo(world, state.left); known.delete(rig); }}- for (const rig of world.getEntitiesWithComponents([GripPose])) {- const data = world.get(rig, GripPose) as GripPoseData;- if (!data.rightPose && !data.leftPose && !known.has(rig)) continue;+ const rigsNow = new Set<Entity>([...comps, ...wanted.keys(), ...known.keys()]);+ for (const rig of rigsNow) {+ if (!world.valid(rig)) continue;+ const data = comps.has(rig) ? world.get(rig, GripPose) as GripPoseData : null;+ const ask = wanted.get(rig);+ const rightHandPath = data?.rightHand || ask?.rightHand || '', leftHandPath = data?.leftHand || ask?.leftHand || '';+ const handOf = (side: 'right' | 'left'): { key: string; def: GripPoseDef | null; weight: number; trigger: number } => {+ const held = ask?.[side];+ if (held) return { key: held.key, def: held.pose, weight: held.weight, trigger: data ? (side === 'right' ? data.rightTrigger : data.leftTrigger) : 0 };+ if (data) {+ const name = side === 'right' ? data.rightPose : data.leftPose;+ return { key: name, def: poses.get(name) ?? null, weight: side === 'right' ? data.rightWeight : data.leftWeight, trigger: side === 'right' ? data.rightTrigger : data.leftTrigger };+ }+ return { key: '', def: null, weight: 0, trigger: 0 };+ };+ const hands = { right: handOf('right'), left: handOf('left') };+ if (!hands.right.key && !hands.left.key && !known.has(rig)) continue;let state = known.get(rig);- if (!state || state.rightHand !== data.rightHand || state.leftHand !== data.leftHand) {+ if (!state || state.rightHand !== rightHandPath || state.leftHand !== leftHandPath) {if (state) { letGo(world, state.right); letGo(world, state.left); }- state = { right: null, left: null, rightHand: data.rightHand, leftHand: data.leftHand, tried: { right: false, left: false } };+ state = { right: null, left: null, rightHand: rightHandPath, leftHand: leftHandPath, tried: { right: false, left: false }, byComponent: !!data, blend: 0.15 };known.set(rig, state);}+ state.byComponent = !!data;+ // Asked for, the holder's; on the rig's own, its; fading out once neither speaks, the last there was.+ const blend = ask ? ask.blendSeconds : data ? data.blendSeconds : state.blend;+ state.blend = blend;const moved = hasClipOn(world, rig);for (const side of ['right', 'left'] as const) {- const poseName = side === 'right' ? data.rightPose : data.leftPose;+ const poseName = hands[side].key;if (!state[side] && poseName && !state.tried[side]) {state.tried[side] = true;- const path = side === 'right' ? data.rightHand : data.leftHand;+ const path = side === 'right' ? rightHandPath : leftHandPath;const hand = path ? resolveChildEntity(world, rig, path) : findHand(world, rig, side);state[side] = hand === null ? null : buildHand(world, hand, side);if (!state[side]) log.warn('animation', `a GripPose found no ${side} hand with fingers on "${nameOf(world, rig)}"${path ? ` at "${path}"` : ''}: name its joint in ${side}Hand`);else if (state[side]!.missing.length) log.warn('animation', `the ${side} hand of "${nameOf(world, rig)}" has no bones for its ${state[side]!.missing.join(', ')}: a pose does without them`);}const hand = state[side];- if (hand) {- holdHand(world, hand, poseName, side === 'right' ? data.rightWeight : data.leftWeight, side === 'right' ? data.rightTrigger : data.leftTrigger, data.blendSeconds, time.delta, moved);- }+ if (hand) holdHand(world, hand, poseName, hands[side].def, hands[side].weight, hands[side].trigger, blend, time.delta, moved);}+ // Hands no one asks for any more, faded all the way out: nothing is left to hold.+ if (!data && !ask && (!state.right || state.right.weight === 0) && (!state.left || state.left.weight === 0)) known.delete(rig);}- }, { name: 'GripPoseSystem' }), { runAfter: [SystemLabel.Animator], runIf: playModeOnly });+ wanted.clear();+ }, { name: 'GripPoseSystem' }), { runAfter: [SystemLabel.Animator], runIf: fxPreviewOrPlayMode });}diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.tsindex 21340f656..7bb3063cd 100644--- a/sdk/src/animation/index.ts+++ b/sdk/src/animation/index.ts@@ -82,11 +82,11 @@ export {type AnimatorPathEvalResult,} from './Animator';export {- GripPose, registerGripPose, gripPose, gripPoseNames, gripPoseStatus,+ GripPose, registerGripPose, gripPose, gripPoseNames, gripPoseStatus, gripPoseByJoint, gripPoseFromJson,type GripPoseData, type GripPoseDef, type GripFinger, type GripThumb, type GripHandStatus,} from './gripPose';export {- GripProfile, GripHolder, GripHand, GripPlacement, registerFingerPose, fingerPose, captureFingerPose, gripHolderStatus, slerpQuat,+ GripProfile, GripHolder, GripHand, GripPlacement, GripMirror, releaseGripHolds, registerFingerPose, fingerPose, captureFingerPose, gripHolderStatus, slerpQuat,type GripProfileData, type GripHolderData, type FingerPoseDef,} from './gripHold';diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 2d5c8c03e..3d36fea53 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -655,6 +655,8 @@ export {gripPose,gripPoseNames,gripPoseStatus,+ gripPoseByJoint,+ gripPoseFromJson,type GripPoseData,type GripPoseDef,type GripFinger,@@ -664,6 +666,8 @@ export {GripHolder,GripHand,GripPlacement,+ GripMirror,+ releaseGripHolds,registerFingerPose,fingerPose,captureFingerPose,diff --git a/sdk/tests/grip-hold-wasm.test.ts b/sdk/tests/grip-hold-wasm.test.tsindex fd86521c7..59486792d 100644--- a/sdk/tests/grip-hold-wasm.test.ts+++ b/sdk/tests/grip-hold-wasm.test.ts@@ -7,10 +7,10 @@import { afterEach, beforeAll, describe, expect, it } from 'vitest';import { App } from '../src/app/app';import { AnimationPlugin } from '../src/animation/AnimationPlugin';-import { GripHolder, GripPlacement, GripProfile, captureFingerPose, gripHolderStatus, registerFingerPose, slerpQuat, type GripHolderData } from '../src/animation/gripHold';-import { palmFrameOf } from '../src/animation/gripPose';-import { Name, Parent, Transform, type TransformData } from '../src/ecs/component';-import { setEditorMode, setPlayMode } from '../src/ecs/env';+import { GripHand, GripHolder, GripMirror, GripPlacement, GripProfile, captureFingerPose, gripHolderStatus, registerFingerPose, releaseGripHolds, slerpQuat, type GripHolderData, type GripProfileData } from '../src/animation/gripHold';+import { GripPose, gripPose, gripPoseByJoint, gripPoseFromJson, gripPoseStatus, palmFrameOf, registerGripPose } from '../src/animation/gripPose';+import { Children, Name, Parent, Transform, type TransformData } from '../src/ecs/component';+import { setEditorMode, setFxEditPreview, setPlayMode } from '../src/ecs/env';import { q } from '../src/math/quat';import type { Entity } from '../src/types';import type { ESEngineModule } from '../src/wasm';@@ -22,7 +22,7 @@ const I: Q = { w: 1, x: 0, y: 0, z: 0 };let core: ESEngineModule;const apps: App[] = [];-afterEach(() => { while (apps.length) apps.pop()!.quit?.(); setEditorMode(false); setPlayMode(false); });+afterEach(() => { while (apps.length) apps.pop()!.quit?.(); setEditorMode(false); setPlayMode(false); setFxEditPreview(false); });function scene() {core.setActiveContext(null);@@ -358,9 +358,177 @@ describe.skipIf(!HAS_WASM)('holding an object', () => {s.world.update(g.e, GripProfile, (p: { mainPose: string; supportPose: string }) => { p.mainPose = 'pistol'; p.supportPose = 'support'; });holder(s.world, b.root, { held: g.e, placement: GripPlacement.Hand });await s.tick(3);- const grip = s.world.get(b.root, (await import('../src/animation/gripPose')).GripPose) as { rightPose: string; leftPose: string; rightWeight: number };- expect(grip.rightPose).toBe('pistol');- expect(grip.leftPose).toBe('support');- expect(grip.rightWeight).toBe(1);+ const status = gripPoseStatus(s.app, b.root)!;+ expect(status.right.pose).toBe('pistol');+ expect(status.left.pose).toBe('support');+ expect(status.right.weight).toBe(1);+ // Handed over without writing a GripPose onto the rig: an editor's preview must not leave a component behind.+ expect(s.world.has(b.root, GripPose)).toBe(false);+ // Let go of, the hands fade out and are forgotten once nothing is left of them.+ s.world.update(b.root, GripHolder, (h: GripHolderData) => { h.held = 0 as Entity; });+ await s.tick(3);+ expect(gripPoseStatus(s.app, b.root)).toBeNull();+ });++ it('mirrors the anchors in the object\'s own plane when the other hand leads, so one set serves either hand', async () => {+ const run = async (mainHand: number, x: number) => {+ const s = scene();+ const b = body(s.world);+ const g = gun(s.world, { x, y: 1.25, z: 0.45 });+ // Turned off the gun's own plane (yawed, then rolled), so a mirror that kept the turn would put the palm the wrong way round.+ const tilt = q.normalize(q.mul({ w: Math.cos(0.2), x: 0, y: Math.sin(0.2), z: 0 }, q.mul({ w: Math.cos(0.15), x: 0, y: 0, z: Math.sin(0.15) }, { w: 0, x: 0, y: 0, z: 1 })));+ s.world.update(g.main, Transform, (t: TransformData) => { t.rotation = tilt; });+ holder(s.world, b.root, { held: g.e, placement: GripPlacement.Object, supportWeight: 0, mainHand });+ await s.tick(2);+ return { s, b, g };+ };+ const right = await run(GripHand.Right, -0.15);+ const left = await run(GripHand.Left, 0.15);+ expect(gripHolderStatus(left.s.app, left.b.root)!.mirrored).toBe(true);+ expect(gripHolderStatus(right.s.app, right.b.root)!.mirrored).toBe(false);+ // The left palm sits on the anchor mirrored in the gun's YZ plane: its place with x negated, its turn the mirror of the anchor's.+ const o = worldPose(left.s.world, left.g.e);+ const a = left.s.world.get(left.g.main, Transform) as TransformData;+ const at = q.rotate(o.r, { x: -a.position.x, y: a.position.y, z: a.position.z });+ const want = { p: { x: o.p.x + at.x, y: o.p.y + at.y, z: o.p.z + at.z }, r: q.normalize(q.mul(o.r, { w: a.rotation.w, x: a.rotation.x, y: -a.rotation.y, z: -a.rotation.z })) };+ const palm = palmOf(left.s.world, left.b.arms.Left!.hand, 'left');+ expect(dist(palm.p, want.p)).toBeLessThan(1e-3);+ expect(angle(palm.r, want.r)).toBeLessThan(0.01);+ // And on a body that is its own mirror, the whole left arm is the right one's mirror image.+ const pr = palmOf(right.s.world, right.b.arms.Right!.hand, 'right').p;+ expect(dist(palm.p, { x: -pr.x, y: pr.y, z: pr.z })).toBeLessThan(1e-3);+ const er = worldPose(right.s.world, right.b.arms.Right!.fore).p, el = worldPose(left.s.world, left.b.arms.Left!.fore).p;+ expect(dist(el, { x: -er.x, y: er.y, z: er.z })).toBeLessThan(1e-3);+ });++ it('does not mirror anchors placed for the hand that leads, whichever it is', async () => {+ const s = scene();+ const b = body(s.world);+ const g = gun(s.world, { x: 0.15, y: 1.25, z: 0.45 });+ s.world.update(g.e, GripProfile, (p: { hand: number; mirror: number }) => { p.hand = GripHand.Left; p.mirror = GripMirror.X; });+ holder(s.world, b.root, { held: g.e, placement: GripPlacement.Object, supportWeight: 0, mainHand: GripHand.Left });+ await s.tick(2);+ expect(gripHolderStatus(s.app, b.root)!.mirrored).toBe(false);+ const palm = palmOf(s.world, b.arms.Left!.hand, 'left');+ expect(dist(palm.p, worldPose(s.world, g.main).p)).toBeLessThan(1e-3);+ });++ it('holds fingers said joint by joint exactly as the preset they were expanded from, and one joint changed moves that joint alone', async () => {+ const fingersOf = async (profile: Partial<GripProfileData>) => {+ const s = scene();+ const b = body(s.world);+ const g = gun(s.world, { x: 3, y: 0, z: 0 });+ s.world.update(g.e, GripProfile, (p: GripProfileData) => { Object.assign(p, profile); });+ holder(s.world, b.root, { held: g.e, placement: GripPlacement.Hand });+ await s.tick(30);+ return captureFingerPose(s.world, b.arms.Right!.hand).joints;+ };+ const byName = await fingersOf({ mainPose: 'pistol' });+ const expanded = gripPoseByJoint(gripPose('pistol')!);+ const byJoint = await fingersOf({ mainPose: '', mainFingers: JSON.stringify(expanded) });+ expect(Object.keys(byJoint).length).toBeGreaterThan(10);+ for (const [name, r] of Object.entries(byName)) expect(angle(r, byJoint[name]!)).toBeLessThan(2e-3);+ // Twenty degrees more on the middle finger's knuckle: that joint turns by twenty degrees, nothing else on the hand moves.+ const edited = JSON.parse(JSON.stringify(expanded));+ edited.middle.bend[0] += 20;+ const changed = await fingersOf({ mainPose: '', mainFingers: JSON.stringify(edited) });+ for (const [name, r] of Object.entries(byJoint)) {+ const turned = angle(r, changed[name]!);+ if (name === 'mixamorig:RightHandMiddle1') expect(Math.abs(turned - (20 * Math.PI) / 180)).toBeLessThan(2e-3);+ else if (/Thumb/.test(name)) continue; // the thumb reaches for the middle finger, which has moved+ else expect(turned).toBeLessThan(1e-4);+ }+ });++ it('holds a pose said joint by joint the same on either hand, mirrored, lean included', async () => {+ registerGripPose('test-by-joint', { thumb: { opposition: 0 }, index: { curl: 0, bend: [30, 40, 20], fan: 12 }, middle: { curl: 0, bend: [50, 60, 30], fan: 4 }, ring: { curl: 0, bend: [55, 70, 35], fan: 8 }, pinky: { curl: 0, bend: [60, 75, 40], fan: 15 } });+ const s = scene();+ const b = body(s.world);+ s.world.insert(b.root, GripPose, { rightPose: 'test-by-joint', leftPose: 'test-by-joint', blendSeconds: 0 });+ await s.tick(2);+ for (const finger of ['Index', 'Middle', 'Ring', 'Pinky']) {+ const r = worldPose(s.world, descendant(s.world, b.root, `mixamorig:RightHand${finger}4`)).p;+ const l = worldPose(s.world, descendant(s.world, b.root, `mixamorig:LeftHand${finger}4`)).p;+ expect(dist(l, { x: -r.x, y: r.y, z: r.z })).toBeLessThan(1e-4);+ }+ });++ it('leans a finger out from the middle of the hand for a positive lean, the index toward the thumb and the little finger away', async () => {+ const tips = async (fan: number) => {+ registerGripPose(`test-fan-${fan}`, { thumb: { opposition: 0 }, index: { curl: 0, fan }, middle: { curl: 0 }, ring: { curl: 0 }, pinky: { curl: 0, fan } });+ const s = scene();+ const b = body(s.world);+ s.world.insert(b.root, GripPose, { rightPose: `test-fan-${fan}`, blendSeconds: 0 });+ await s.tick(2);+ const at = (f: string) => worldPose(s.world, descendant(s.world, b.root, `mixamorig:RightHand${f}4`)).p;+ return { index: at('Index'), pinky: at('Pinky'), middle: at('Middle') };+ };+ const flat = await tips(0), out = await tips(20);+ expect(dist(out.index, out.pinky)).toBeGreaterThan(dist(flat.index, flat.pinky) + 0.02);+ expect(dist(out.index, out.middle)).toBeGreaterThan(dist(flat.index, flat.middle) + 0.01);+ });++ it('reads fingers from JSON leniently, and refuses text that is not a pose', () => {+ expect(gripPoseFromJson('')).toBeNull();+ expect(gripPoseFromJson('not json')).toBeNull();+ expect(gripPoseFromJson('3')).toBeNull();+ const partial = gripPoseFromJson('{"index":{"bend":[10,20,30]},"thumb":{"opposition":0.5,"to":"index"}}')!;+ expect(partial.index.bend).toEqual([10, 20, 30]);+ expect(partial.middle.curl).toBe(0);+ expect(partial.thumb).toEqual({ opposition: 0.5, to: 'index', gap: 0 });+ expect(gripPoseFromJson('{"index":{"bend":[10,"x",30]}}')!.index.bend).toBeUndefined();+ });++ it('says how far a palm stops short of an anchor out of reach, and nothing within it', async () => {+ const s = scene();+ const b = body(s.world);+ const g = gun(s.world, { x: -0.15, y: 1.25, z: 0.45 });+ holder(s.world, b.root, { held: g.e, placement: GripPlacement.Object, supportWeight: 0 });+ await s.tick(2);+ expect(gripHolderStatus(s.app, b.root)!.short.main).toBe(0);+ s.world.update(g.e, Transform, (t: TransformData) => { t.position = { x: -0.15, y: 1.25, z: 3 }; });+ await s.tick(2);+ const short = gripHolderStatus(s.app, b.root)!.short.main;+ // The arm is 0.57 long from a shoulder at z 0.05; the anchor is about 2.93 ahead of it.+ expect(short).toBeGreaterThan(2.2);+ expect(short).toBeLessThan(2.5);+ });++ it('previews in an editor only with the effects preview on, and gives every bone and the carried object back when it ends', async () => {+ const s = scene();+ setPlayMode(false);+ setEditorMode(true);+ const b = body(s.world);+ const g = gun(s.world, { x: 3, y: 0, z: 0 });+ s.world.update(g.e, GripProfile, (p: { mainPose: string; supportPose: string }) => { p.mainPose = 'fist'; p.supportPose = 'fist'; });+ reachable(s.world, g);+ holder(s.world, b.root, { held: g.e, placement: GripPlacement.Hand });+ const fingers = () => Object.values(captureFingerPose(s.world, b.arms.Left!.hand).joints);+ const before = { arms: rotationsOf(s.world, armJoints(b)), fingers: fingers(), gun: { ...(s.world.get(g.e, Transform) as TransformData).position } };+ await s.tick(5);+ expect(rotationsOf(s.world, armJoints(b))).toEqual(before.arms);+ setFxEditPreview(true);+ await s.tick(30);+ expect(dist((s.world.get(g.e, Transform) as TransformData).position, before.gun)).toBeGreaterThan(1);+ expect(Math.max(...rotationsOf(s.world, armJoints(b)).map((r, i) => angle(r, before.arms[i]!)))).toBeGreaterThan(0.1);+ expect(Math.max(...fingers().map((r, i) => angle(r, before.fingers[i]!)))).toBeGreaterThan(0.5);+ releaseGripHolds(s.app);+ setFxEditPreview(false);+ await s.tick(2);+ rotationsOf(s.world, armJoints(b)).forEach((r, i) => expect(angle(r, before.arms[i]!)).toBeLessThan(1e-5));+ fingers().forEach((r, i) => expect(angle(r, before.fingers[i]!)).toBeLessThan(1e-5));+ expect(dist((s.world.get(g.e, Transform) as TransformData).position, before.gun)).toBeLessThan(1e-6);});});++/** An entity below `root` by name. */+function descendant(world: World, root: Entity, name: string): Entity {+ const stack = [root];+ while (stack.length) {+ const at = stack.pop()!;+ if ((world.tryGet(at, Name) as { value?: string } | null)?.value === name) return at;+ stack.push(...((world.tryGet(at, Children) as { entities?: Entity[] } | null)?.entities ?? []));+ }+ throw new Error(`no ${name}`);+}+diff --git a/tools/check-theme.mjs b/tools/check-theme.mjsindex b29328421..29f3fcca8 100644--- a/tools/check-theme.mjs+++ b/tools/check-theme.mjs@@ -142,6 +142,7 @@ const NAMES_THE_SAME_THING = [['.ts-p', 'the tileset collision-polygon editor, a canvas of its own'],['.ax.', "an Inspector vec field's axis letters: the legend for the gizmo's arms"],['.world__', "the World panel's residency colours — its key, a cell's dot and state word — for what the viewport draws"],+ ['.gi-tag', "the GripProfile section's hand tags: the legend for the palm markers the viewport draws in those colours"],['components/GizmoReadout.tsx', 'the drag readout carries the dot of the gizmo axis it reports'],['panels/SequencerCurve.tsx', 'a curve channel IS the axis channel, so it takes the axis colour'],];diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 10382dee5..13cf95ce3 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -4254,6 +4254,8 @@ export const NOTED = {{"note": "Particles and plain sprites in a Canvas paint by their place in its tree."},"fix(text): stopping lets go of the labels the engine holds, so the next Play cannot draw them on other entities":{"note": "Labels no longer come back as black boxes after a change between Plays."},+ "feat(editor): a grip is edited where it is held, the character holding it live in the edit viewport":+ {"note": "A grip is edited where it is held."},"feat(animation): a character holds an object by anchors on it, the arms bent to them in one order that cannot loop":{"note": "Holding an object in both hands."},"feat(animation): a rig's hands held in a named pose that fits any skeleton":