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
fix(animation): a held hand's thumb reaches for the fingers and lies over them, instead of standing out from the palm
yhh2c3198757412
diff --git a/desktop b/desktopindex 5b53eec38..a10a9b0cf 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 5b53eec3841a7a14e1bbc93d19ccc44d8d7d7912+Subproject commit a10a9b0cf4c4dadcbc157beea5d16dd0bad0820adiff --git a/docs/astro/src/content/docs/animation/grip-pose.mdx b/docs/astro/src/content/docs/animation/grip-pose.mdxindex 26f94d8a5..7266d405b 100644--- a/docs/astro/src/content/docs/animation/grip-pose.mdx+++ b/docs/astro/src/content/docs/animation/grip-pose.mdx@@ -3,7 +3,7 @@ title: Grip Posedescription: Hold a character's hands in a named pose, a pistol grip, a handle, a cup, that fits any rig with fingers.----A `GripPose` holds a rig's hands the way you name: `pistol`, `handle`, `cup`. A pose says only how far each finger bends, how far they fan out and how far the thumb comes across, and nothing in it names a bone, so one pose fits any rig. Which way those bends go is worked out from each rig's own hand, the first time it is held.+A `GripPose` holds a rig's hands the way you name: `pistol`, `handle`, `cup`. A pose says only how far each finger bends, how far they fan out and what the thumb reaches for, and nothing in it names a bone, so one pose fits any rig. Which way those bends go is worked out from each rig's own hand, the first time it is held.It shapes the hand. Putting the hand on an object is up to whatever attaches it, usually an entity under the hand joint and two-bone IK for the arm.@@ -49,7 +49,7 @@ To add your own, or replace one by name:import { registerGripPose } from 'esengine';registerGripPose('claw', {- thumb: { curl: 0.6, opposition: 0.7 },+ thumb: { opposition: 1, gap: 0.2 },index: { curl: 0.9, base: 0.2 },middle: { curl: 0.9, base: 0.2 },ring: { curl: 0.9, base: 0.2 },@@ -62,7 +62,11 @@ 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. |-| `opposition` | The thumb only: how far it comes across the palm, 0 beside the hand to 1 facing the fingers. |+| `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. |## On your rigdiff --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 c0eb5f57a..786ab2568 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@@ -3,7 +3,7 @@ title: 握持姿势description: 让角色的手保持一个命名姿势,比如手枪握、手柄握、捧杯,适用于任何带手指骨骼的角色。----`GripPose` 让角色的手保持你指定的姿势:`pistol`、`handle`、`cup`。姿势只描述每根手指弯多少、张开多少、拇指对掌多少,不涉及任何骨骼名字,所以同一个姿势可以用在任何骨架上。弯曲的方向在第一次握持时,根据每个角色自己的手算出来。+`GripPose` 让角色的手保持你指定的姿势:`pistol`、`handle`、`cup`。姿势只描述每根手指弯多少、张开多少、拇指去够哪里,不涉及任何骨骼名字,所以同一个姿势可以用在任何骨架上。弯曲的方向在第一次握持时,根据每个角色自己的手算出来。它只负责手型。把手放到物体上由挂点负责,通常是手部关节下的子实体,加上手臂的 two-bone IK。@@ -49,7 +49,7 @@ world.update(hero, GripPose, (grip) => { grip.rightTrigger = 1; });import { registerGripPose } from 'esengine';registerGripPose('claw', {- thumb: { curl: 0.6, opposition: 0.7 },+ thumb: { opposition: 1, gap: 0.2 },index: { curl: 0.9, base: 0.2 },middle: { curl: 0.9, base: 0.2 },ring: { curl: 0.9, base: 0.2 },@@ -62,7 +62,11 @@ registerGripPose('claw', {| `curl` | 手指弯多少,0 是骨架静止状态,1 是完全握紧。 || `base` | 第一个关节弯多少,用于和其余关节不同的情况,比如手指沿枪身伸直或者勾起。默认等于 `curl`。 || `spread` | 手指张开多少,-1 到 1。 |-| `opposition` | 仅拇指:拇指对掌多少,0 贴在手边,1 正对手指。 |+| `opposition` | 拇指:从静止位置走向目标的程度,0 到 1。 |+| `to` | 拇指:`fingers`(中指中节,用于握拳、握柄)或 `index`(食指指尖,用于捏合)。 |+| `gap` | 拇指:在目标前停多远,以食指长度为单位,相当于中间夹着的握把或杯子。 |++拇指没有自己的弯曲数值,它是“去够”的:指尖走向其余手指当帧位置上的一个点(在手掌一侧),两个指节一起弯曲来够到它。所以握拳时拇指压在手指上,握东西时绕过握把。够不着时(比如手指伸直)就指向那个位置。| `trigger` | 写在姿势上:`rightTrigger` 到 1 时食指的状态。 |## 适配你的骨架diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 5c625d2e4..09b9068c5 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5075,10 +5075,9 @@ trigger: GripFinger | undefined## GripThumb — interface @experimental```-base: number | undefined-curl: number+gap: number | undefinedopposition: number-spread: number | undefined+to: "fingers" | "index" | undefined```## Ground — type @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex d853623b6..cf0e1a1dc 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5083,10 +5083,9 @@ trigger: GripFinger | undefined## GripThumb — interface @experimental```-base: number | undefined-curl: number+gap: number | undefinedopposition: number-spread: number | undefined+to: "fingers" | "index" | undefined```## Ground — type @experimental@@ -8763,7 +8762,12 @@ TextureUploadDecision## REGISTRY_BINDINGS — const @experimental```-{ readonly createEntity: "es_createEntity"; readonly destroyEntity: "es_destroyEntity"; readonly setParent: "es_setParent"; readonly hasParent: "es_hasParent"; readonly getParent: "es_getParent"; readonly removeParent: "es_removeParent"; readonly hasChildren: "es_hasChildren"; readonly getChildren: "es_getChildren"; readonly getMeshSkinJoints: "es_getMeshSkinJoints"; readonly setMeshSkinJoints: "es_setMeshSkinJoints"; readonly layoutEpoch: "es_registryLayoutEpoch"; readonly transformEpoch: "es_transformEpochBuffer"; readonly ensureComposed: "es_transformEnsureComposed"; }+{ readonly hasParent: "es_hasParent"; readonly getParent: "es_getParent"; readonly removeParent: "es_removeParent"; readonly hasChildren: "es_hasChildren"; readonly getChildren: "es_getChildren"; readonly getMeshSkinJoints: "es_getMeshSkinJoints"; readonly setMeshSkinJoints: "es_setMeshSkinJoints"; readonly layoutEpoch: "es_registryLayoutEpoch"; readonly transformEpoch: "es_transformEpochBuffer"; readonly ensureComposed: "es_transformEnsureComposed"; }+```++## REGISTRY_OPS — const @experimental+```+{ readonly create: "es_registry_create"; readonly destroy: "es_registry_destroy"; readonly valid: "es_registry_valid"; readonly entityCount: "es_registry_entityCount"; readonly reserveDestruction: "es_registry_reserveDestruction"; readonly releaseDestruction: "es_registry_releaseDestruction"; readonly destructionPending: "es_registry_destructionPending"; readonly setEntityEnabled: "es_registry_setEntityEnabled"; readonly isEntityActive: "es_registry_isEntityActive"; readonly isEntityEnabled: "es_registry_isEntityEnabled"; readonly hasInactiveEntities: "es_registry_hasInactiveEntities"; readonly activityEpoch: "es_registry_activityEpoch"; readonly setParent: "es_registry_setParent"; }```## RENAMED_COMPONENT_TYPES — const @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex f5945e54c..1d699662f 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -5070,10 +5070,9 @@ trigger: GripFinger | undefined## GripThumb — interface @experimental```-base: number | undefined-curl: number+gap: number | undefinedopposition: number-spread: number | undefined+to: "fingers" | "index" | undefined```## Ground — type @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 74855b76f..33ac9e1ab 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -5070,10 +5070,9 @@ trigger: GripFinger | undefined## GripThumb — interface @experimental```-base: number | undefined-curl: number+gap: number | undefinedopposition: number-spread: number | undefined+to: "fingers" | "index" | undefined```## Ground — type @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex fcbee0d7f..9f161c22f 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -5070,10 +5070,9 @@ trigger: GripFinger | undefined## GripThumb — interface @experimental```-base: number | undefined-curl: number+gap: number | undefinedopposition: number-spread: number | undefined+to: "fingers" | "index" | undefined```## Ground — type @experimentaldiff --git a/sdk/src/animation/gripPose.ts b/sdk/src/animation/gripPose.tsindex dbc8ab301..8b8e25a8b 100644--- a/sdk/src/animation/gripPose.ts+++ b/sdk/src/animation/gripPose.ts@@ -35,10 +35,14 @@ export interface GripFinger {spread?: number;}-/** How the thumb is held. @experimental */-export interface GripThumb extends GripFinger {- /** How far it comes across the palm, 0 beside the hand to 1 facing the fingers. */+/** How the thumb is held: as a reach, since where it can rest is somewhere on the other fingers. @experimental */+export interface GripThumb {+ /** How far it goes from where it rests to what it reaches for, 0 to 1. */opposition: number;+ /** What it reaches for: the middle of the middle finger, as a fist or a handle has it, or the index finger's tip, as a pinch does. Defaults to `fingers`. */+ to?: 'fingers' | 'index';+ /** How far short of them it stops, in lengths of the index finger: what is held between, a grip or a mug. Defaults to 0. */+ gap?: number;}/** How a whole hand is held. Nothing in it names a bone, so it fits any rig. @experimental */@@ -53,20 +57,20 @@ export interface GripPoseDef {}const f = (curl: number, base?: number, spread?: number): GripFinger => ({ curl, ...(base !== undefined ? { base } : {}), ...(spread !== undefined ? { spread } : {}) });-const thumb = (curl: number, opposition: number, base?: number): GripThumb => ({ curl, opposition, ...(base !== undefined ? { base } : {}) });+const thumb = (opposition: number, gap = 0, to: 'fingers' | 'index' = 'fingers'): GripThumb => ({ opposition, gap, to });const poses = new Map<string, GripPoseDef>(Object.entries({- open: { thumb: thumb(0, 0), index: f(0), middle: f(0), ring: f(0), pinky: f(0) },- relaxed: { thumb: thumb(0.15, 0.25), index: f(0.18, 0.15), middle: f(0.25, 0.2), ring: f(0.3, 0.25), pinky: f(0.35, 0.3) },- fist: { thumb: thumb(0.7, 0.85), index: f(1), middle: f(1), ring: f(1), pinky: f(1) },+ open: { thumb: thumb(0), index: f(0), middle: f(0), ring: f(0), pinky: f(0) },+ relaxed: { thumb: thumb(0.25, 0.6), index: f(0.18, 0.15), middle: f(0.25, 0.2), ring: f(0.3, 0.25), pinky: f(0.35, 0.3) },+ fist: { thumb: thumb(1), index: f(1), middle: f(1), ring: f(1), pinky: f(1) },pistol: {- thumb: thumb(0.45, 0.8), index: f(0.1, 0.32), middle: f(0.78, 0.72), ring: f(0.82, 0.76), pinky: f(0.85, 0.8),+ thumb: thumb(1, 0.4), index: f(0.1, 0.32), middle: f(0.78, 0.72), ring: f(0.82, 0.76), pinky: f(0.85, 0.8),trigger: f(0.55, 0.42),},- support: { thumb: thumb(0.3, 0.65), index: f(0.4, 0.35), middle: f(0.45, 0.4), ring: f(0.48, 0.42), pinky: f(0.5, 0.45) },- handle: { thumb: thumb(0.6, 0.85), index: f(0.78, 0.7), middle: f(0.82, 0.75), ring: f(0.85, 0.78), pinky: f(0.88, 0.8) },- pinch: { thumb: thumb(0.5, 0.8), index: f(0.55, 0.5), middle: f(0.25, 0.2), ring: f(0.25, 0.2), pinky: f(0.25, 0.2) },- cup: { thumb: thumb(0.25, 0.7), index: f(0.45, 0.25, 0.3), middle: f(0.45, 0.25, 0.3), ring: f(0.45, 0.25, 0.3), pinky: f(0.45, 0.25, 0.3) },+ support: { thumb: thumb(0.9, 0.5), index: f(0.4, 0.35), middle: f(0.45, 0.4), ring: f(0.48, 0.42), pinky: f(0.5, 0.45) },+ handle: { thumb: thumb(1, 0.1), index: f(0.78, 0.7), middle: f(0.82, 0.75), ring: f(0.85, 0.78), pinky: f(0.88, 0.8) },+ pinch: { thumb: thumb(1, 0, 'index'), index: f(0.55, 0.5), middle: f(0.25, 0.2), ring: f(0.25, 0.2), pinky: f(0.25, 0.2) },+ cup: { thumb: thumb(0.9, 0.8), index: f(0.45, 0.25, 0.3), middle: f(0.45, 0.25, 0.3), ring: f(0.45, 0.25, 0.3), pinky: f(0.45, 0.25, 0.3) },} satisfies Record<string, GripPoseDef>));/** Adds a pose of the game's own, or replaces one by name. @experimental */@@ -138,8 +142,6 @@ const INSIDE_PALM = /metacarpal|palm/i;/** How far each joint of a finger bends when it is closed: first, second, third. In radians. */const CLOSED = [Math.PI / 2, (100 * Math.PI) / 180, (70 * Math.PI) / 180];-/** The thumb's are far less: its root barely bends, and what it does there is opposition's. */-const THUMB_CLOSED = [(15 * Math.PI) / 180, (60 * Math.PI) / 180, (80 * Math.PI) / 180];const SPREAD = (15 * Math.PI) / 180;const FAN: Record<FingerName, number> = { thumb: 0, index: 1, middle: 0.15, ring: -0.6, pinky: -1 };@@ -164,9 +166,6 @@ interface Joint {curlAxis: Vec3;/** On a finger's first joint. */spreadAxis?: Vec3;- /** On the thumb's first joint: the turn that faces it to the fingers at full opposition, as an axis and an angle. */- opposeAxis?: Vec3;- opposeAngle?: number;/** What this wrote last, to tell it from what a clip has written since. */written: Quat;}@@ -174,18 +173,21 @@ 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 opposition. */-const NUMBERS = FINGERS.length * 3 + 1;+/** 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;+const REACH = NUMBERS - 3, TO_INDEX = NUMBERS - 2, GAP = NUMBERS - 1;function numbersOf(pose: GripPoseDef | null, out: Float64Array): void {let i = 0;for (const name of FINGERS) {- const finger = pose?.[name];+ 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));}- out[i] = clamp01(pose?.thumb.opposition ?? 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);@@ -206,6 +208,27 @@ interface HandState {settled: boolean;pose: string;trigger: number;+ /** What the thumb reaches with, where it has a chain long enough to bend. */+ thumb: ThumbReach | null;+ /** The hand's own directions, in its frame. */+ palm: Vec3;+ across: Vec3;+ /** The index finger's length: what a gap is measured in, and about how thick a finger is. */+ reachUnit: number;+ index: Entity[];+ middle: Entity[];+}++/** The thumb as a chain that reaches: where its root stands and how long each bone is, as the rig rests, in the hand's frame. */+interface ThumbReach {+ root: Vec3;+ lengths: [number, number, number];+ /** Each bone's direction as it rests, and each joint's turn from the hand. */+ restDirs: [Vec3, Vec3, Vec3];+ restTurns: [Quat, Quat, Quat];+ /** The turn of the joint the thumb's root hangs from. */+ parentTurn: Quat;+ restTip: Vec3;}/** A finger's bones in order, from the hand: those named for it, knuckle first, those in the palm passed through. */@@ -278,7 +301,7 @@ function buildHand(world: World, hand: Entity, side: 'right' | 'left'): HandStatfor (const name of FINGERS) chains[name] = fingerChain(world, hand, name);const shape = palmOf(world, side, chains);if (!shape) return null;- const { palm, across, forward } = shape;+ const { palm, across } = shape;const fingers: Finger[] = [];const missing: FingerName[] = [];for (const name of FINGERS) {@@ -287,13 +310,7 @@ function buildHand(world: World, hand: Entity, side: 'right' | 'left'): HandStatconst { at, turn } = fromHand(world, chain);// Its first joint to its second is the way it points; a finger of one joint points as the joint does from the hand.const pointing = norm(chain.length > 1 ? sub(at[1]!, at[0]!) : at[0]!);- // The thumb's way to the fingers is a direction and not a turn about some axis: where it starts from differs from rig to rig, and where it has to get to does not.- const facing = name === 'thumb' ? norm(add(add(scale(forward, 0.85), scale(palm, 0.45)), scale(across, 0.25))) : pointing;- const oppose = q.rotationTo(pointing, facing);- // A closing thumb lies over the first two fingers, its tip going on toward the little finger.- const towards = name === 'thumb' ? norm(add(add(scale(palm, 0.15), scale(across, -1)), scale(forward, -0.1))) : palm;- // Worked out where it faces once opposed, and taken back to where it rests, since that turn comes first.- const bend = q.rotate(q.conjugate(oppose), norm(cross(facing, towards)));+ const bend = norm(cross(pointing, palm));// The last bone of a chain that goes on past three is the tip's end, which nothing bends.const moved = chain.slice(0, 3);const joints: Joint[] = moved.map((entity, i) => {@@ -304,18 +321,82 @@ function buildHand(world: World, hand: Entity, side: 'right' | 'left'): HandStatjoint.spreadAxis = norm(q.rotate(toJoint, palm));// Toward the index finger for a positive spread.if (dot(cross(palm, pointing), across) < 0) joint.spreadAxis = scale(joint.spreadAxis, -1);- if (name === 'thumb') {- const half = Math.min(1, Math.abs(oppose.w));- const axis = norm({ x: oppose.x, y: oppose.y, z: oppose.z });- joint.opposeAxis = norm(q.rotate(toJoint, oppose.w < 0 ? scale(axis, -1) : axis));- joint.opposeAngle = 2 * Math.acos(half);- }}return joint;});fingers.push({ name, joints, fan: FAN[name] });}- return { hand, fingers, missing, current: new Float64Array(NUMBERS), wanted: new Float64Array(NUMBERS), weight: 0, speed: new Float64Array(NUMBERS + 1), settled: false, pose: '', trigger: 0 };+ const index = chains.index ?? [], middle = chains.middle ?? [];+ const lengthOf = (chain: Entity[]): number => {+ const at = chain.length ? fromHand(world, chain).at : [];+ let n = 0;+ for (let i = 1; i < at.length; i++) n += Math.hypot(at[i]!.x - at[i - 1]!.x, at[i]!.y - at[i - 1]!.y, at[i]!.z - at[i - 1]!.z);+ return n;+ };+ const reachUnit = lengthOf(index) || lengthOf(middle) || 0;+ return {+ hand, fingers, missing, current: new Float64Array(NUMBERS), wanted: new Float64Array(NUMBERS), weight: 0, speed: new Float64Array(NUMBERS + 1), settled: false, pose: '', trigger: 0,+ thumb: thumbReach(world, chains.thumb ?? []), palm, across, reachUnit, index, middle,+ };+}++/** The thumb's chain as it rests: null with fewer than three bones, since two cannot both reach and curl. */+function thumbReach(world: World, chain: Entity[]): ThumbReach | null {+ if (chain.length < 3) return null;+ const { at, turn } = fromHand(world, chain);+ const segment = (i: number): Vec3 => sub(at[i + 1]!, at[i]!);+ const third = chain.length > 3 ? segment(2) : scale(segment(1), 0.85);+ const lengths: [number, number, number] = [Math.hypot(...xyz(segment(0))), Math.hypot(...xyz(segment(1))), Math.hypot(...xyz(third))];+ if (lengths.some((l) => !(l > 1e-6))) return null;+ const local0 = (world.get(chain[0]!, Transform) as TransformData).rotation;+ return {+ root: at[0]!, lengths, restDirs: [norm(segment(0)), norm(segment(1)), norm(third)], restTurns: [turn[0]!, turn[1]!, turn[2]!],+ parentTurn: q.normalize(q.mul(turn[0]!, q.conjugate(local0))), restTip: add(at[2]!, third),+ };+}++const xyz = (v: Vec3): [number, number, number] => [v.x, v.y, v.z];++/** Where a bent chain's tip is, when its second and third joints each turn by `bend`, measured along its first bone and square to it. */+function chainTip(lengths: readonly number[], bend: number): [number, number] {+ const [a, b, c] = lengths as [number, number, number];+ return [a + b * Math.cos(bend) + c * Math.cos(2 * bend), b * Math.sin(bend) + c * Math.sin(2 * bend)];+}++/**+ * The thumb's joints turned so its tip lands on `goal`, its bones curling toward `inward`: the bend found by halving, the plane by where the goal is.+ * Answers each joint's turn from the hand.+ */+function reachThumb(reach: ThumbReach, goal: Vec3, inward: Vec3): [Quat, Quat, Quat] {+ const toGoal = sub(goal, reach.root);+ const total = reach.lengths[0] + reach.lengths[1] + reach.lengths[2];+ const want = Math.min(Math.max(Math.hypot(...xyz(toGoal)), total * 0.35), total - 1e-6);+ let lo = 0, hi = 1.7;+ for (let i = 0; i < 24; i++) {+ const mid = (lo + hi) / 2;+ const [x, y] = chainTip(reach.lengths, mid);+ if (Math.hypot(x, y) > want) lo = mid; else hi = mid;+ }+ const bend = (lo + hi) / 2;+ const [tx, ty] = chainTip(reach.lengths, bend);+ const lean = Math.atan2(ty, tx);+ const u = norm(toGoal);+ const off = sub(inward, scale(u, dot(inward, u)));+ const v = Math.hypot(...xyz(off)) > 1e-6 ? norm(off) : norm(cross(u, { x: 0, y: 0, z: 1 }));+ const along = (angle: number): Vec3 => add(scale(u, Math.cos(angle)), scale(v, Math.sin(angle)));+ const dirs = [along(-lean), along(bend - lean), along(2 * bend - lean)];+ // Each bone turned the least way from where its parent left it: no twist added along it.+ const turns: Quat[] = [];+ let parentNow = reach.parentTurn, parentRest = reach.parentTurn;+ for (let i = 0; i < 3; i++) {+ const carried = q.normalize(q.mul(q.mul(parentNow, q.conjugate(parentRest)), reach.restTurns[i]!));+ const facing = q.rotate(q.mul(parentNow, q.conjugate(parentRest)), reach.restDirs[i]!);+ const turned = q.normalize(q.mul(q.rotationTo(facing, dirs[i]!), carried));+ turns.push(turned);+ parentRest = reach.restTurns[i]!;+ parentNow = turned;+ }+ return turns as [Quat, Quat, Quat];}const NAMED_HAND = /hand|wrist/i;@@ -384,8 +465,10 @@ function holdHand(world: World, state: HandState, poseName: string, weight: numbstate.weight = ease(state.weight, wantedWeight, state, NUMBERS, blend, dt);if (state.weight !== wantedWeight) arrived = false;- const opposition = state.current[NUMBERS - 1]!;- for (const finger of state.fingers) {+ // The thumb last: what it reaches for is where the other fingers have just been put.+ const 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]!;@@ -395,10 +478,16 @@ function holdHand(world: World, state: HandState, poseName: string, weight: numb}for (let i = 0; i < finger.joints.length; i++) {const joint = finger.joints[i]!;- let turn = axisAngle(joint.curlAxis, (i === 0 ? base : curl) * (finger.name === 'thumb' ? THUMB_CLOSED : CLOSED)[i]!);- if (joint.spreadAxis && spread !== 0 && finger.fan !== 0) turn = q.mul(axisAngle(joint.spreadAxis, spread * finger.fan * SPREAD), turn);- if (joint.opposeAxis && opposition > 0) turn = q.mul(axisAngle(joint.opposeAxis, opposition * joint.opposeAngle!), turn);- const target = q.normalize(q.mul(joint.rest, turn));+ let target: Quat;+ if (reached) {+ // From the joint's turn from the hand to its own: its parent is the joint before, or for the first what the thumb hangs from.+ const 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);+ target = q.normalize(q.mul(joint.rest, turn));+ }const local = world.get(joint.entity, Transform) as TransformData;// Moved since this wrote it, a clip is speaking and the pose goes over that; otherwise over how the rig rests.const from = same(local.rotation, joint.written) ? joint.rest : local.rotation;@@ -413,6 +502,32 @@ function holdHand(world: World, state: HandState, poseName: string, weight: numbstate.settled = arrived;}+/**+ * Where the thumb goes this frame, as each joint's turn from the hand: from where it rests toward the middle of the middle finger (or the index tip) as+ * they now stand, on the palm's side of them by a finger's thickness and the pose's gap. Null with no reach asked, which leaves it as it rests.+ */+function thumbTurns(world: World, state: HandState): [Quat, Quat, Quat] | null {+ const reach = state.thumb!;+ const amount = state.current[REACH]!;+ if (amount <= 0) return null;+ const middleOf = (chain: Entity[]): Vec3 | null => {+ if (chain.length < 3) return null;+ const at = fromHand(world, chain).at;+ return scale(add(at[1]!, at[2]!), 0.5);+ };+ const tipOf = (chain: Entity[]): Vec3 | null => (chain.length ? fromHand(world, chain).at[chain.length - 1]! : null);+ // The middle finger's, not the index's: an index finger on a trigger would move the thumb with it.+ const fingers = middleOf(state.middle) ?? middleOf(state.index);+ const index = tipOf(state.index) ?? fingers;+ if (!fingers || !index) return null;+ const toIndex = state.current[TO_INDEX]!;+ const on = add(scale(fingers, 1 - toIndex), scale(index, toIndex));+ const thickness = state.reachUnit * 0.16;+ const contact = add(on, scale(state.palm, thickness + state.current[GAP]! * state.reachUnit));+ const goal = add(scale(reach.restTip, 1 - amount), scale(contact, amount));+ return reachThumb(reach, goal, norm(add(scale(state.across, -0.8), scale(state.palm, 0.6))));+}+function letGo(world: World, state: HandState | null): void {if (!state) return;for (const finger of state.fingers) {diff --git a/sdk/tests/grip-pose-wasm.test.ts b/sdk/tests/grip-pose-wasm.test.tsindex a8518883c..2b3d28464 100644--- a/sdk/tests/grip-pose-wasm.test.ts+++ b/sdk/tests/grip-pose-wasm.test.ts@@ -166,9 +166,10 @@ describe.skipIf(!HAS_WASM)('a grip pose', () => {});it('turns the thumb toward the fingers by its opposition, whatever else it does', async () => {- const none = { curl: 0 };- registerGripPose('thumb-beside', { thumb: { curl: 0, opposition: 0 }, index: none, middle: none, ring: none, pinky: none });- registerGripPose('thumb-across', { thumb: { curl: 0, opposition: 1 }, index: none, middle: none, ring: none, pinky: none });+ // On closed fingers, where a thumb can reach them; it cannot reach the middle of a flat finger, and points at it instead.+ const shut = { curl: 1 };+ registerGripPose('thumb-beside', { thumb: { opposition: 0 }, index: shut, middle: shut, ring: shut, pinky: shut });+ registerGripPose('thumb-across', { thumb: { opposition: 1 }, index: shut, middle: shut, ring: shut, pinky: shut });const s = scene();const beside = buildRig(s.world);hold(s.world, beside, { rightPose: 'thumb-beside' });@@ -178,8 +179,11 @@ describe.skipIf(!HAS_WASM)('a grip pose', () => {await s.tick(2);await t.tick(2);const a = tips(s.world, beside).thumb!, b = tips(t.world, across).thumb!;- expect(b.z).toBeLessThan(a.z - 0.01);- expect(b.y).toBeGreaterThan(a.y);+ // It reaches for the middle of the middle finger: on the palm's side of it, by about a finger's thickness.+ const middleOf = (world: World, rig: ReturnType<typeof buildRig>): V => { const m = rig.bones.middle!; const p = placeOf(world, m[1]!, rig.hand), r = placeOf(world, m[2]!, rig.hand); return { x: (p.x + r.x) / 2, y: (p.y + r.y) / 2, z: (p.z + r.z) / 2 }; };+ expect(dist(b, middleOf(t.world, across))).toBeLessThan(dist(a, middleOf(s.world, beside)) * 0.5);+ expect(dist(b, middleOf(t.world, across))).toBeLessThan(0.02);+ expect(b.z).toBeLessThan(a.z);expect(tips(t.world, across).index!.z).toBeCloseTo(tips(s.world, beside).index!.z, 5);});@@ -416,7 +420,7 @@ describe.skipIf(!HAS_WASM)('a grip pose', () => {});it('takes a pose of the game\'s own, and leaves a name it does not know alone', async () => {- registerGripPose('claw', { thumb: { curl: 1, opposition: 1 }, index: { curl: 1, base: 0 }, middle: { curl: 1, base: 0 }, ring: { curl: 1, base: 0 }, pinky: { curl: 1, base: 0 } });+ registerGripPose('claw', { thumb: { opposition: 1 }, index: { curl: 1, base: 0 }, middle: { curl: 1, base: 0 }, ring: { curl: 1, base: 0 }, pinky: { curl: 1, base: 0 } });expect(gripPoseNames()).toContain('claw');const s = scene();const rig = buildRig(s.world);diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 3e04e0064..9973bcefd 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -4236,6 +4236,8 @@ export const NOTED = {{"note": "Labels no longer come back as black boxes after a change between Plays."},"feat(animation): a rig's hands held in a named pose that fits any skeleton":{"note": "Hands that hold things."},+ "fix(animation): a held hand's thumb reaches for the fingers and lies over them, instead of standing out from the palm":+ {"note": "Hands that hold things."},"feat(sky): clouds that keep time with the game, follow the weather's wind, and have a second layer":{"note": "Clouds that keep time with the game."},"feat(voxel): ground that is a volume, carved while the game runs, with collision that follows and saves by chunk":