A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(animation): a foot-plant constraint keeps a foot on the physics ground under it, slopes and steps included
yhhdb0066372c46
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d7c32e129..3600ee931 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,7 +22,9 @@ published separately; it ships inside the editor.- **Glyphs can be put on the atlas before they are shown.** The first page of a novel is hundreds of new characters, all landing in one frame. `preloadGlyphs(app, label, text, { budgetMs })` makes them ahead of time, a slice a frame, drawn as that `Text` will draw them, and returns `progress`, `done` and `release()`. On a Snapdragon 8 Elite a book's 2992 characters at 28 px took 145 ms over 25 frames with the worst frame at 9.5 ms, after which the first page's frame went from 49 to 11 ms and no page made a new glyph. Preloaded glyphs hold their atlas pages (4 MB each, a few hundred characters at that size) until `release()`.- **Voxel GI lights what the camera does not see, and bounces light more than once.** The cache now reads the sun's shadow map back into the world, so a surface the sun lights behind or beside the camera still sends light into the view. Each surface also gives off again the bounce light it received, so a corner or a floor in shade gets light that took two or more bounces to reach it. A ray now brings what it meets at full strength however far it went (it used to fade with distance, 40% at 4 m with 12 cm voxels). Each voxel is weighed by how much of it a surface covers, so a bright patch no longer lights like the whole voxel around it. Together these keep the result close to a path tracer's whatever the voxel size. In a sunlit test room the whole frame carries 0.95 of Cycles' light at the default size and 0.74 at 12 cm voxels; before, it was 0.54 at the default and darker the finer the grid. With the lit patch behind the camera, the walls went from no bounce light to 25–57%. A closed room the sun only lights from outside stays dark. Two inspector controls tune it: **Off-screen Sun Albedo** (the colour the shadow map cannot give, assumed) and **Multi-bounce**. A fine grid no longer drops every voxel: a count truncated by the cache's ageing had kept them below the two samples a ray asks for. The WebGL2 fallback does the same in its own passes: each voxel asks the sun's map whether a sunlit surface stands in it, and traces two rays through last frame's grid for the light it is given. In the test room it carries 1.00 of Cycles' light at the default size (it was 0.56) and 0.80 at 12 cm; with the lit patch behind the camera 0.20 (it was 0). Its voxel pass costs about 1.3 ms more at 720p on a desktop.-**AI agents can build 3D models in the editor from steps.** The `modeling` tool group writes a `.esmodel`, the steps that build a model (boxes, cylinders and floor plans, then extrude, inset, bevel, slice, array, mirror, paint), and bakes the `.esmesh` a scene draws beside it. Changing one number rebuilds it and whatever draws it follows, Undo takes both files back, and `model_views` shows every side with its silhouette, so an agent can check a shape without a scene. Blockouts, buildings and hard-surface props; and with the `organic` step, creatures, plants and rocks, as one skin over parts that melt into each other, carve, mirror and roughen. `lathe` and `loft` make curved solids from a few points: vases, pipes, handles, hulls. A `rig` of joints gets its weights found over the surface and `animations` of a few keys play as ordinary clips, so a creature can walk, with feet told where to land and a `controller` choosing which clip plays when. `rig.adjust` corrects a weight, `shapes` make expressions a clip can move, and `controller.ik` reaches and looks at goals as the game runs. `subdivide` and a rounded `bevel` smooth what polygons leave hard. A `boolean` step cuts real holes through solids, and a `uv` step or `uvAtlas` lays out how a texture lands.+- **A foot stands on the ground under it.** A `foot-plant` constraint on an Animator looks down from each foot through physics and bends the leg to land on whatever is there, slopes and steps included, keeping any lift the clip gives it, laying the foot along the slope and lowering the hips so the leg can reach.++- **AI agents can build 3D models in the editor from steps.** The `modeling` tool group writes a `.esmodel`, the steps that build a model (boxes, cylinders and floor plans, then extrude, inset, bevel, slice, array, mirror, paint), and bakes the `.esmesh` a scene draws beside it. Changing one number rebuilds it and whatever draws it follows, Undo takes both files back, and `model_views` shows every side with its silhouette, so an agent can check a shape without a scene. Blockouts, buildings and hard-surface props; and with the `organic` step, creatures, plants and rocks, as one skin over parts that melt into each other, carve, mirror and roughen. `lathe` and `loft` make curved solids from a few points: vases, pipes, handles, hulls. A `rig` of joints gets its weights found over the surface and `animations` of a few keys play as ordinary clips, so a creature can walk, with feet told where to land and a `controller` choosing which clip plays when. `rig.adjust` corrects a weight, `shapes` make expressions a clip can move, and `controller.ik` reaches and looks at goals as the game runs. `subdivide` and a rounded `bevel` smooth what polygons leave hard. A `boolean` step cuts real holes through solids, and a `uv` step or `uvAtlas` lays out how a texture lands.- **A model of many parts that moves: `CompositeBatch`.** Put it on the root of a ship, a vehicle or a moving platform assembled from many meshes, and while the game runs its parts are drawn in a few draws parented to the root: a mesh repeated four times or more (a deck plank, a rail post) as one instanced set that copies no vertices, every other part merged by draw state into chunks of the root's own space. Moving, turning or scaling the root moves the whole model and merges nothing again. Adding, removing, re-meshing or re-placing a part re-merges only its chunk within half a second (`CompositeBatchingRes.refresh(root)` looks at once), and a part that keeps moving inside the model is let go to draw itself. The root reports what it drew, and so does `get_stats`. On a model of 2,004 parts, the meshes handed to the renderer went from 2,003 to 5 and the CPU frame from 3.3 ms to 1.2–1.4 ms; a model of about a hundred parts costs the same either way. A part under a composite is never also statically batched.diff --git a/desktop b/desktopindex f3705594c..44cf8f622 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit f3705594c843b4a6e38ad2ef7d2c53e8635d1feb+Subproject commit 44cf8f6225d7532a5658721b1fc08fdfb85afdfadiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 4448d79e1..f4040f676 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": 176,- "experimental": 2841,+ "experimental": 2844,"deprecated": 3},- "total": 3132,+ "total": 3135,"subsystems": [{"id": "mobile-controls",diff --git a/pipeline/src/modeling/index.ts b/pipeline/src/modeling/index.tsindex 81499d19d..e0ccfbb63 100644--- a/pipeline/src/modeling/index.ts+++ b/pipeline/src/modeling/index.ts@@ -13,4 +13,4 @@ export { needsPreparing, prepareModeling } from './booleans';export { bakeModel, type BakedModel, type ModelReport } from './modelBake';export type { FaceSelector } from './polyMesh';export { DEFAULT_MODEL_VIEWS, MODEL_VIEWS, renderModelSheet, renderRigSheet, type ModelSheet, type ModelViewName, type RigViewOptions } from './modelViews';-export { controllerOf, jointPositions, morphedPositions, posedPositions, prefabOf, timelineOf, type AnimationSource, type ControllerSource, type RigSource, type ShapeSource } from './rig';+export { controllerOf, jointPositions, morphedPositions, posedPositions, prefabOf, timelineOf, type AnimationSource, type ControllerSource, type PoseSolve, type PreviewGround, type RigSource, type ShapeSource } from './rig';diff --git a/pipeline/src/modeling/modelBake.ts b/pipeline/src/modeling/modelBake.tsindex 5e18c8c5a..3b3af281e 100644--- a/pipeline/src/modeling/modelBake.ts+++ b/pipeline/src/modeling/modelBake.ts@@ -11,7 +11,7 @@import { MeshChannel, MeshChannelType, packChannels, unwrapLightmapUV, type MeshData, type MeshMorphTargets } from 'esengine';import { triangulateFace } from './triangulate';import { faceUvs } from './modelUv';-import { adjustWeights, bindMatrices, computeWeights, resolveJoints, shapeDeltas, type RigJoint, type SkinWeights } from './rig';+import { adjustWeights, bindMatrices, computeWeights, resolveJoints, shapeDeltas, type ControllerIk, type RigGoal, type RigJoint, type SkinWeights } from './rig';import { buildPolyMesh, validateModelSource, type ModelSource, type StepReport } from './modelSource';import {boundsOf, collectEdges, cross, dot, faceArea, faceNormal, length, normalize, sub,@@ -51,7 +51,7 @@ export interface BakedModel {data: MeshData;report: ModelReport;/** Present on a rigged model. */- rig?: { joints: RigJoint[]; skin: SkinWeights };+ rig?: { joints: RigJoint[]; skin: SkinWeights; ik?: readonly ControllerIk[]; goals?: readonly RigGoal[] };/** Present where a source has shapes: three offsets per surface vertex, for each. */shapes?: { names: string[]; deltas: Float32Array[] };/** One triangle per entry: its three positions' indices, and the face it came from. */@@ -234,7 +234,7 @@ export function bakeModel(raw: unknown): BakedModel {let rig: BakedModel['rig'];if (source.rig) {const joints = resolveJoints(source.rig);- rig = { joints, skin: adjustWeights(mesh, joints, computeWeights(mesh, joints), source.rig.adjust ?? []) };+ rig = { joints, skin: adjustWeights(mesh, joints, computeWeights(mesh, joints), source.rig.adjust ?? []), ik: source.controller?.ik ?? [], goals: source.rig.goals ?? [] };}const shapes = source.shapes ? { names: source.shapes.map((s) => s.name), deltas: source.shapes.map((s) => shapeDeltas(mesh, s)) } : undefined;// A mesh that moves takes no lightmap: a bake holds still.@@ -280,6 +280,11 @@ export function bakeModel(raw: unknown): BakedModel {if (idle.length) warnings.push(`joint${idle.length > 1 ? 's' : ''} ${idle.join(', ')} move${idle.length > 1 ? '' : 's'} no vertex the most: too near another, or outside the surface`);}+ // The engine's delta texture is 2048 square, the most WebGL2 promises; past it the mesh draws, but never changes shape.+ if (shapes && shapes.names.length * unwrapped.vertexCount * 2 > 2048 * 2048) {+ warnings.push(`${shapes.names.length} shapes over ${unwrapped.vertexCount} vertices is more than the engine holds (${2048 * 2048} deltas, two each): it would draw but never change shape. Lower the resolution or use fewer shapes`);+ }+const roundVec = (v: readonly number[]): Vec3 => v.map((x) => Math.round(x * 1e5) / 1e5) as unknown as Vec3;return {poly: mesh,diff --git a/pipeline/src/modeling/modelViews.ts b/pipeline/src/modeling/modelViews.tsindex e98405107..acf345f8a 100644--- a/pipeline/src/modeling/modelViews.ts+++ b/pipeline/src/modeling/modelViews.ts@@ -15,7 +15,7 @@* What the model looks like in the game is what `screenshot` is for.*/import type { BakedModel } from './modelBake';-import { boneLines, jointColor, morphedPositions, posedPositions, shapeWeightsAt, type AnimationSource } from './rig';+import { boneLines, jointColor, morphedPositions, posedPositions, shapeWeightsAt, type AnimationSource, type PoseSolve, type PreviewGround } from './rig';import { add, boundsOf, collectEdges, cross, dot, faceNormal, normalize, selectFaces, sub, type FaceSelector, type PolyMesh, type Vec3 } from './polyMesh';export const MODEL_VIEWS = {@@ -193,6 +193,10 @@ export interface RigViewOptions {/** Draws this clip. With `times`, a strip of one view at each. */animation?: string;times?: readonly number[];+ /** The controller's IK, run as the game runs it. Default on where the model has one. */+ ik?: boolean;+ /** A flat test ground, for foot-plants: in the game they ask physics. Drawn in orange. */+ ground?: PreviewGround;/** Shows this shape at full weight. */shape?: string;/** Colours each face by the joint moving it most, or fades all but one joint's reach. */@@ -230,13 +234,25 @@ export function renderRigSheet(model: BakedModel, animations: readonly Animationconst anim = o.animation === undefined ? null : animations.find((a) => a.name === o.animation);if (o.animation !== undefined && !anim) throw new Error(`no animation "${o.animation}"; there are ${animations.map((a) => a.name).join(', ') || '(none)'}`);const skeleton = rig !== undefined && o.skeleton !== false;+ const solve: PoseSolve | undefined = rig?.ik?.length && o.ik !== false ? { ik: rig.ik, goals: rig.goals ?? [], ...(o.ground ? { ground: o.ground } : {}) } : undefined;+ const groundLines = (): [Vec3, Vec3][] => {+ if (!o.ground) return [];+ const { min, max } = boundsOf(model.poly);+ const [sx, sz] = o.ground.slope ?? [0, 0];+ const h = o.ground.height ?? 0;+ const spot = (x: number, z: number): Vec3 => [x, h + sx * x + sz * z, z];+ const pad = (max[0] - min[0] + (max[2] - min[2])) * 0.15;+ const [a, b, c, d] = [spot(min[0] - pad, min[2] - pad), spot(max[0] + pad, min[2] - pad), spot(max[0] + pad, max[2] + pad), spot(min[0] - pad, max[2] + pad)];+ return [[a, b], [b, c], [c, d], [d, a]];+ };+ const overlayAt = (time: number): [Vec3, Vec3][] => [...(skeleton ? boneLines(rig!.joints, anim ?? null, time, solve) : []), ...groundLines()];const weightsAt = (time: number): number[] => (o.shape !== undefined ? names.map((n) => (n === o.shape ? 1 : 0)) : shapeWeightsAt(names, anim ?? null, time));const posed = (time: number): BakedModel => {const shaped: PolyMesh = model.shapes ? { ...model.poly, positions: morphedPositions(model.poly, model.shapes.deltas, weightsAt(time)) } : model.poly;- return { ...drawn, poly: { ...drawn.poly, positions: rig ? posedPositions(shaped, rig.joints, rig.skin, anim ?? null, time) : shaped.positions } };+ return { ...drawn, poly: { ...drawn.poly, positions: rig ? posedPositions(shaped, rig.joints, rig.skin, anim ?? null, time, solve) : shaped.positions } };};if (!anim) {- return renderModelSheet(posed(0), o.views ?? DEFAULT_MODEL_VIEWS, panel, o.focus, o.wire === true, skeleton ? { overlay: boneLines(rig!.joints, null, 0) } : {});+ return renderModelSheet(posed(0), o.views ?? DEFAULT_MODEL_VIEWS, panel, o.focus, o.wire === true, { overlay: overlayAt(0) });}const times = o.times ?? Array.from({ length: 4 }, (_, i) => (i / 4) * anim.duration);if (times.length === 0) throw new Error('`times` names no moment');@@ -249,7 +265,7 @@ export function renderRigSheet(model: BakedModel, animations: readonly Animationif (framedBy.length === 0) throw new Error(`focus ${JSON.stringify(o.focus)} matched no face`);const frame = boundsOf({ positions: framedBy, faces: [] });const sheets = poses.map((m, i) => renderModelSheet(m, [view], panel, undefined, o.wire === true, {- frame, ...(skeleton ? { overlay: boneLines(rig!.joints, anim, times[i]!) } : {}),+ frame, overlay: overlayAt(times[i]!),}));const width = times.length * panel + (times.length - 1);const height = sheets[0]!.height;diff --git a/pipeline/src/modeling/rig.ts b/pipeline/src/modeling/rig.tsindex 00d3cae36..610013a41 100644--- a/pipeline/src/modeling/rig.ts+++ b/pipeline/src/modeling/rig.ts@@ -706,7 +706,7 @@ function toWorld(joints: readonly RigJoint[], local: Pose['local']): Pose['world}/** Each joint at @p time, with every `reach` solved; the bind pose with no animation. */-function poseAt(joints: readonly RigJoint[], animation: AnimationSource | null, time: number): Pose {+function poseAt(joints: readonly RigJoint[], animation: AnimationSource | null, time: number, solve?: PoseSolve): Pose {const loop = animation?.loop !== false;const at = (keys: readonly (readonly number[])[], t: AnimationTrack): Vec3 => sample(keys, time, animation!.duration, loop, t.phase ?? 0, t.linear === true);const local: Pose['local'] = joints.map((j) => {@@ -720,47 +720,133 @@ function poseAt(joints: readonly RigJoint[], animation: AnimationSource | null,for (const track of animation?.tracks ?? []) {if (!track.reach) continue;const foot = joints.findIndex((j) => j.name === track.joint);- const lower = joints[foot]!.parent, upper = joints[lower]!.parent, above = joints[upper]!.parent;- const target = at(track.reach, track);- const a = world[upper]!.origin, b = world[lower]!.origin, c = world[foot]!.origin;- const upperLen = length(sub(joints[lower]!.at, joints[upper]!.at)), lowerLen = length(sub(joints[foot]!.at, joints[lower]!.at));- const toTarget = sub(target, a);- const near = Math.abs(upperLen - lowerLen) + 1e-4, far = upperLen + lowerLen - 1e-4;- // Out of reach it stretches straight toward the target; the report cannot say so per frame, the strip shows it.- const span = Math.max(near, Math.min(far, length(toTarget)));- const along = normalize(toTarget);- const bent = sub(b, add(a, scale(along, dot(sub(b, a), along))));- const hint = track.pole ?? (length(bent) > upperLen * 0.01 ? bent : [0, 0, 1] as Vec3);- let side = sub(hint, scale(along, dot(hint, along)));- if (length(side) < 1e-6) side = sub([1, 0, 0], scale(along, along[0]));- const toKnee = (upperLen * upperLen - lowerLen * lowerLen + span * span) / (2 * span);- const out = Math.sqrt(Math.max(0, upperLen * upperLen - toKnee * toKnee));- const knee = add(add(a, scale(along, toKnee)), scale(normalize(side), out));- const end = add(a, scale(along, span));- const upperWorld = quatMul(rotationBetween(sub(b, a), sub(knee, a)), world[upper]!.q);- // Where the foot would now be, carried by the upper bone, is what the lower bone turns from.- const carried = rotateBy(rotationBetween(sub(b, a), sub(knee, a)), sub(c, b));- const lowerWorld = quatMul(rotationBetween(carried, sub(end, knee)), quatMul(rotationBetween(sub(b, a), sub(knee, a)), world[lower]!.q));const held = track.rotate ? at(track.rotate, track) : [0, 0, 0] as Vec3;- const footWorld = eulerToQuat(held[0], held[1], held[2]);- const parentWorld = above >= 0 ? world[above]!.q : [0, 0, 0, 1] as Quat;- local[upper] = { ...local[upper]!, q: quatMul(conjugate(parentWorld), upperWorld) };- local[lower] = { ...local[lower]!, q: quatMul(conjugate(upperWorld), lowerWorld) };- local[foot] = { ...local[foot]!, q: quatMul(conjugate(lowerWorld), footWorld) };- world = toWorld(joints, local);+ world = bendLimb(joints, local, world, foot, at(track.reach, track), track.pole, eulerToQuat(held[0], held[1], held[2]));}+ if (solve) world = applyConstraints(joints, local, world, solve);return { local, world };}+/**+ * The two bones above @p foot turned to put it on @p target, leaving `local` changed and answering the world it makes.+ * @p footWorld holds the foot at that orientation; left out it goes on as the clip had it, carried by the turn.+ */+function bendLimb(joints: readonly RigJoint[], local: Pose['local'], world: Pose['world'], foot: number, target: Vec3, pole: Vec3 | undefined, footWorld?: Quat): Pose['world'] {+ const lower = joints[foot]!.parent, upper = joints[lower]!.parent, above = joints[upper]!.parent;+ const a = world[upper]!.origin, b = world[lower]!.origin, c = world[foot]!.origin;+ const upperLen = length(sub(joints[lower]!.at, joints[upper]!.at)), lowerLen = length(sub(joints[foot]!.at, joints[lower]!.at));+ const toTarget = sub(target, a);+ const near = Math.abs(upperLen - lowerLen) + 1e-4, far = upperLen + lowerLen - 1e-4;+ // Out of reach it stretches straight toward the target; the report cannot say so per frame, the strip shows it.+ const span = Math.max(near, Math.min(far, length(toTarget)));+ const along = normalize(toTarget);+ const bent = sub(b, add(a, scale(along, dot(sub(b, a), along))));+ const hint = pole ?? (length(bent) > upperLen * 0.01 ? bent : [0, 0, 1] as Vec3);+ let side = sub(hint, scale(along, dot(hint, along)));+ if (length(side) < 1e-6) side = sub([1, 0, 0], scale(along, along[0]));+ const toKnee = (upperLen * upperLen - lowerLen * lowerLen + span * span) / (2 * span);+ const out = Math.sqrt(Math.max(0, upperLen * upperLen - toKnee * toKnee));+ const knee = add(add(a, scale(along, toKnee)), scale(normalize(side), out));+ const end = add(a, scale(along, span));+ const turn = rotationBetween(sub(b, a), sub(knee, a));+ const upperWorld = quatMul(turn, world[upper]!.q);+ // Where the foot would now be, carried by the upper bone, is what the lower bone turns from.+ const lowerWorld = quatMul(rotationBetween(rotateBy(turn, sub(c, b)), sub(end, knee)), quatMul(turn, world[lower]!.q));+ const parentWorld = above >= 0 ? world[above]!.q : [0, 0, 0, 1] as Quat;+ const keptFoot = footWorld ?? quatMul(conjugate(world[lower]!.q), world[foot]!.q);+ local[upper] = { ...local[upper]!, q: quatMul(conjugate(parentWorld), upperWorld) };+ local[lower] = { ...local[lower]!, q: quatMul(conjugate(upperWorld), lowerWorld) };+ local[foot] = { ...local[foot]!, q: footWorld ? quatMul(conjugate(lowerWorld), keptFoot) : local[foot]!.q };+ return toWorld(joints, local);+}++/** A flat test ground for a preview: `height` at the rig's origin, rising by `slope` per unit of x and z. */+export interface PreviewGround {+ height?: number;+ slope?: readonly [number, number];+}++/** What the game does on top of the clips, for a preview: the controller's constraints, and the ground its foot-plants stand on. */+export interface PoseSolve {+ ik: readonly ControllerIk[];+ goals: readonly RigGoal[];+ /** Foot-plants do nothing without one: the game asks physics, and here there is none. */+ ground?: PreviewGround;+}++const MAX_FOOT_TILT = Math.PI / 4;++/** The engine's constraint pass, on the CPU: foot-plants first and together, the rest in order. Mirrors sdk/src/animation/animatorIK.ts. */+function applyConstraints(joints: readonly RigJoint[], local: Pose['local'], start: Pose['world'], solve: PoseSolve): Pose['world'] {+ let world = start;+ const index = (name: string | undefined): number => (name === undefined ? -1 : joints.findIndex((j) => j.name === name));+ const placeOf = (name: string | undefined): Vec3 | null => {+ if (name === undefined) return null;+ const j = index(name);+ if (j >= 0) return world[j]!.origin;+ const goal = solve.goals.find((g) => g.name === name);+ if (!goal) return null;+ const parent = index(goal.parent);+ if (parent < 0) return goal.at;+ return add(world[parent]!.origin, rotateBy(world[parent]!.q, sub(goal.at, joints[parent]!.at)));+ };+ if (solve.ground) {+ const height = solve.ground.height ?? 0;+ const [sx, sz] = solve.ground.slope ?? [0, 0];+ const normal = normalize([-sx, 1, -sz]);+ const feet = solve.ik.filter((k) => k.kind === 'foot-plant').map((k) => {+ const foot = index(k.tip);+ const at_ = world[foot]!.origin;+ return { k, foot, at: at_, q: world[foot]!.q, lift: height + sx * at_[0] + sz * at_[2] };+ });+ const drops = new Map<string, number>();+ for (const f of feet) if (f.k.pelvis) drops.set(f.k.pelvis, Math.min(drops.get(f.k.pelvis) ?? 0, f.lift * (f.k.weight ?? 1)));+ for (const [name, drop] of drops) {+ if (drop >= 0) continue;+ const p = index(name);+ const parent = joints[p]!.parent;+ const inParent = parent >= 0 ? rotateBy(conjugate(world[parent]!.q), [0, drop, 0]) : [0, drop, 0] as Vec3;+ local[p] = { ...local[p]!, offset: add(local[p]!.offset, inParent) };+ }+ if (drops.size) world = toWorld(joints, local);+ const tilt = Math.acos(Math.min(1, normal[1]));+ const limited = tilt > MAX_FOOT_TILT ? normalize(add(scale([0, 1, 0], Math.sin(tilt - MAX_FOOT_TILT)), scale(normal, Math.sin(MAX_FOOT_TILT)))) : normal;+ for (const f of feet) {+ const weight = Math.min(1, Math.max(0, f.k.weight ?? 1));+ const goal: Vec3 = [f.at[0], f.at[1] + f.lift * weight, f.at[2]];+ const aligned = f.k.align === false ? undefined : quatMul(rotationBetween([0, 1, 0], limited), f.q);+ world = bendLimb(joints, local, world, f.foot, goal, placeOf(f.k.pole) ?? undefined, aligned);+ }+ }+ for (const k of solve.ik) {+ if (k.kind === 'foot-plant') continue;+ const tip = index(k.tip);+ const target = placeOf(k.target);+ if (tip < 0 || !target) continue;+ if (k.kind === 'two-bone') {+ const pole = placeOf(k.pole);+ world = bendLimb(joints, local, world, tip, target, pole ? sub(pole, world[joints[joints[tip]!.parent]!.parent]!.origin) : undefined);+ } else {+ const axis: Vec3 = k.axis === 'x' ? [1, 0, 0] : k.axis === 'y' ? [0, 1, 0] : [0, 0, 1];+ const facing = rotateBy(world[tip]!.q, axis);+ const wanted = quatMul(rotationBetween(facing, sub(target, world[tip]!.origin)), world[tip]!.q);+ const parent = joints[tip]!.parent;+ local[tip] = { ...local[tip]!, q: quatMul(conjugate(parent >= 0 ? world[parent]!.q : [0, 0, 0, 1]), wanted) };+ world = toWorld(joints, local);+ }+ }+ return world;+}+/** Where each joint is in a pose: for checking a foot landed. */-export function jointPositions(joints: readonly RigJoint[], animation: AnimationSource | null, time: number): Record<string, Vec3> {- const { world } = poseAt(joints, animation, time);+export function jointPositions(joints: readonly RigJoint[], animation: AnimationSource | null, time: number, solve?: PoseSolve): Record<string, Vec3> {+ const { world } = poseAt(joints, animation, time, solve);return Object.fromEntries(joints.map((j, i) => [j.name, world[i]!.origin]));}/** The surface's positions in a pose, skinned as the engine skins it. */-export function posedPositions(mesh: PolyMesh, joints: readonly RigJoint[], skin: SkinWeights, animation: AnimationSource | null, time: number): Vec3[] {- const pose = poseAt(joints, animation, time).world;+export function posedPositions(mesh: PolyMesh, joints: readonly RigJoint[], skin: SkinWeights, animation: AnimationSource | null, time: number, solve?: PoseSolve): Vec3[] {+ const pose = poseAt(joints, animation, time, solve).world;return mesh.positions.map((p, v) => {let out: Vec3 = [0, 0, 0];for (let k = 0; k < 4; k++) {@@ -775,8 +861,8 @@ export function posedPositions(mesh: PolyMesh, joints: readonly RigJoint[], skin}/** The bones as lines in a pose, for drawing over a view. */-export function boneLines(joints: readonly RigJoint[], animation: AnimationSource | null, time: number): [Vec3, Vec3][] {- const pose = poseAt(joints, animation, time).world;+export function boneLines(joints: readonly RigJoint[], animation: AnimationSource | null, time: number, solve?: PoseSolve): [Vec3, Vec3][] {+ const pose = poseAt(joints, animation, time, solve).world;return joints.flatMap((j, i) => (j.parent >= 0 ? [[pose[j.parent]!.origin, pose[i]!.origin] as [Vec3, Vec3]] : []));}@@ -913,11 +999,21 @@ export interface ControllerSource {}export interface ControllerIk {- kind: 'two-bone' | 'look-at';+ kind: 'two-bone' | 'look-at' | 'foot-plant';/** The joint the chain ends at. */tip: string;- /** A joint or a rig goal it reaches or looks at. */- target: string;+ /** A joint or a rig goal it reaches or looks at. A foot-plant has none: the ground is its target. */+ target?: string;+ /** foot-plant: the joint lowered so the leg can reach the lower foot. */+ pelvis?: string;+ /** foot-plant: lay the foot along the slope. Default true. */+ align?: boolean;+ /** foot-plant: how far up and down to look for ground, in the model's units. */+ reach?: number;+ /** foot-plant: seconds to settle on a new height. */+ smooth?: number;+ /** foot-plant: the physics layers that count as ground. */+ layers?: number;pole?: string;weight?: number;/** A float parameter scaling the weight, to fade it in. */@@ -986,14 +1082,22 @@ export function checkController(raw: unknown, animations: unknown, rig?: RigSourconst known = new Set([...jointNames, ...(rig?.goals ?? []).map((g) => g.name)]);const every = [...known].join(', ') || '(none)';for (const k of c.ik as ControllerIk[]) {- for (const key of Object.keys(k)) if (!['kind', 'tip', 'target', 'pole', 'weight', 'parameter', 'axis'].includes(key)) return `an ik constraint has an unknown field "${key}"; it takes kind, tip, target, pole, weight, parameter, axis`;- if (k.kind !== 'two-bone' && k.kind !== 'look-at') return `an ik constraint's kind ${JSON.stringify(k.kind)} must be two-bone or look-at`;+ for (const key of Object.keys(k)) if (!['kind', 'tip', 'target', 'pole', 'weight', 'parameter', 'axis', 'pelvis', 'align', 'reach', 'smooth', 'layers'].includes(key)) return `an ik constraint has an unknown field "${key}"; it takes kind, tip, target, pole, weight, parameter, axis, pelvis, align, reach, smooth, layers`;+ if (k.kind !== 'two-bone' && k.kind !== 'look-at' && k.kind !== 'foot-plant') return `an ik constraint's kind ${JSON.stringify(k.kind)} must be two-bone, look-at or foot-plant`;if (!jointNames.has(k.tip)) return `an ik constraint's tip "${k.tip}" is not a joint; there are ${[...jointNames].join(', ')}`;- if (!known.has(k.target)) return `an ik constraint's target "${k.target}" is not a joint or a goal; there are ${every}`;+ if (k.kind === 'foot-plant') {+ if (k.target !== undefined) return `a foot-plant on "${k.tip}" has no target: the ground is what it reaches`;+ if (k.pelvis !== undefined && !jointNames.has(k.pelvis)) return `a foot-plant's pelvis "${k.pelvis}" is not a joint; there are ${[...jointNames].join(', ')}`;+ for (const f of ['reach', 'smooth', 'layers'] as const) if (k[f] !== undefined && !isNum(k[f])) return `a foot-plant's ${f} must be a number`;+ if (k.align !== undefined && typeof k.align !== 'boolean') return 'a foot-plant\'s align must be true or false';+ } else {+ if (k.pelvis !== undefined || k.align !== undefined || k.reach !== undefined || k.smooth !== undefined || k.layers !== undefined) return `pelvis, align, reach, smooth and layers belong to a foot-plant, not a ${k.kind}`;+ if (!known.has(k.target as string)) return `an ik constraint's target "${String(k.target)}" is not a joint or a goal; there are ${every}`;+ }if (k.pole !== undefined && !known.has(k.pole)) return `an ik constraint's pole "${k.pole}" is not a joint or a goal; there are ${every}`;- if (k.kind === 'two-bone') {+ if (k.kind !== 'look-at') {const tip = list.find((j) => j.name === k.tip)!;- if (tip.parent < 0 || list[tip.parent]!.parent < 0) return `two-bone ik needs two bones above "${k.tip}"`;+ if (tip.parent < 0 || list[tip.parent]!.parent < 0) return `${k.kind} ik needs two bones above "${k.tip}"`;}if (k.weight !== undefined && !isNum(k.weight)) return 'an ik constraint\'s weight must be a number';if (k.parameter !== undefined && params.get(k.parameter) !== 'float') return `an ik constraint's parameter "${k.parameter}" must be a float parameter`;@@ -1030,7 +1134,10 @@ export function controllerOf(source: ControllerSource, animations: readonly AniminitialState: source.initial,...(source.any ? { anyStateTransitions: source.any.map(transition) } : {}),// An engine constraint names joints the way a clip does: by path from the root.- ...(source.ik ? { ik: source.ik.map((k) => ({ ...k, tip: pathTo(k.tip), target: pathTo(k.target), ...(k.pole ? { pole: pathTo(k.pole) } : {}) })) } : {}),+ ...(source.ik ? { ik: source.ik.map((k) => ({+ ...k, tip: pathTo(k.tip), target: k.target === undefined ? '' : pathTo(k.target),+ ...(k.pole ? { pole: pathTo(k.pole) } : {}), ...(k.pelvis ? { pelvis: pathTo(k.pelvis) } : {}),+ })) } : {}),states: source.states.map((s, i) => ({name: s.name, x: 80 + (i % 4) * 220, y: 80 + Math.floor(i / 4) * 140,motion: s.blenddiff --git a/pipeline/tests/modeling-preview-ik.test.ts b/pipeline/tests/modeling-preview-ik.test.tsnew file mode 100644index 000000000..c36cdcab4--- /dev/null+++ b/pipeline/tests/modeling-preview-ik.test.ts@@ -0,0 +1,115 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/** The views run the game's IK: feet on a test floor, a head turned to a goal, and what the file then tells the engine. */+import { describe, expect, it } from 'vitest';+import { bakeModel, controllerOf, jointPositions, renderRigSheet, validateModelSource, type AnimationSource, type BakedModel, type ModelStep, type RigSource } from '../src/modeling';++const rig: RigSource = { joints: [+ { name: 'hips', at: [0, 2, 0] },+ { name: 'thigh', at: [0.3, 2, 0], parent: 'hips', mirror: 'x' },+ { name: 'shin', at: [0.3, 1, 0.05], parent: 'thigh', mirror: 'x' },+ { name: 'foot', at: [0.3, 0, 0], parent: 'shin', mirror: 'x' },+ { name: 'head', at: [0, 3, 0], parent: 'hips' },+ { name: 'crown', at: [0, 3.5, 0], parent: 'head' },+], goals: [{ name: 'beacon', at: [4, 3, 0] }] };+const body: ModelStep = { op: 'organic', resolution: 48, blend: 0.1, parts: [+ { tag: 'torso', shape: 'chain', points: [[0, 2, 0, 0.35], [0, 3.4, 0, 0.25]] },+ { tag: 'leg', shape: 'chain', mirror: 'x', points: [[0.3, 2, 0, 0.15], [0.3, 1, 0.05, 0.12], [0.3, 0, 0, 0.1]] },+] };+const clip: AnimationSource = { name: 'stand', duration: 1, tracks: [{ joint: 'crown', rotate: [[0, 0, 0, 0]] }] };+const plant = (side: string, extra = {}) => ({ kind: 'foot-plant', tip: `foot.${side}`, pole: 'beacon', ...extra });+const controller = (ik: unknown[]) => ({ initial: 's', states: [{ name: 's', clip: 'stand' }], ik });+const bake = (ik: unknown[]): BakedModel => bakeModel({ version: 1, rig, animations: [clip], controller: controller(ik), steps: [body] });+const solveOf = (m: BakedModel, ground?: { height?: number; slope?: [number, number] }) => ({ ik: m.rig!.ik!, goals: m.rig!.goals!, ...(ground ? { ground } : {}) });++describe('previewing a foot-plant', () => {+ const m = bake([plant('L', { pelvis: 'hips' }), plant('R', { pelvis: 'hips' })]);+ const at = (ground?: { height?: number; slope?: [number, number] }) => jointPositions(m.rig!.joints, clip, 0, solveOf(m, ground));++ it('with no floor to stand on, does nothing', () => {+ expect(at()['foot.L']).toEqual(jointPositions(m.rig!.joints, clip, 0)['foot.L']);+ });++ it('puts both feet on a raised floor, the knees bending and the hips staying', () => {+ const p = at({ height: 0.4 });+ expect(p['foot.L']![1]).toBeCloseTo(0.4, 4);+ expect(p['foot.R']![1]).toBeCloseTo(0.4, 4);+ expect(p.hips![1]).toBeCloseTo(2, 5);+ });++ it('on a floor below, the hips come down and the feet reach it', () => {+ const p = at({ height: -0.5 });+ expect(p.hips![1]).toBeCloseTo(1.5, 5);+ expect(p['foot.L']![1]).toBeCloseTo(-0.5, 3);+ });++ it('on a slope each foot lands at its own height, and the lower one sets the hips', () => {+ const slope = 0.25;+ const p = at({ slope: [slope, 0] });+ expect(p['foot.L']![1]).toBeCloseTo(0.3 * slope, 3);+ expect(p['foot.R']![1]).toBeCloseTo(-0.3 * slope, 3);+ expect(p.hips![1]).toBeCloseTo(2 - 0.3 * slope, 4);+ });++ it('a sheet shows it: orange floor lines, and a silhouette that follows', () => {+ const orange = (s: { width: number; height: number; rgba: Uint8Array }): number => {+ let n = 0;+ for (let i = 0; i < s.width * s.height; i++) if (s.rgba[i * 4] === 255 && s.rgba[i * 4 + 2] === 0) n++;+ return n;+ };+ const flat = renderRigSheet(m, [clip], { views: ['front'], panel: 128, skeleton: false });+ const floored = renderRigSheet(m, [clip], { views: ['front'], panel: 128, skeleton: false, ground: { slope: [0.3, 0] } });+ expect(orange(flat)).toBe(0);+ expect(orange(floored)).toBeGreaterThan(20);+ expect(floored.rgba).not.toEqual(flat.rgba);+ });++ it('`ik: false` shows the clips alone', () => {+ const on = renderRigSheet(m, [clip], { views: ['front'], panel: 96, ground: { height: 0.6 } });+ const off = renderRigSheet(m, [clip], { views: ['front'], panel: 96, ground: { height: 0.6 }, ik: false });+ expect(on.rgba).not.toEqual(off.rgba);+ });++ it('writes what the engine reads, the joints by path and no target', () => {+ const doc = controllerOf(controller([plant('L', { pelvis: 'hips', layers: 2, smooth: 0.1 })]) as never, [clip], (n) => `${n}.estimeline`, rig) as { ik: Record<string, unknown>[] };+ expect(doc.ik[0]).toEqual({ kind: 'foot-plant', tip: 'hips/thigh.L/shin.L/foot.L', target: '', pole: 'beacon', pelvis: 'hips', layers: 2, smooth: 0.1 });+ });++ it('refuses what cannot run, naming it', () => {+ const check = (ik: unknown) => validateModelSource({ version: 1, rig, animations: [clip], controller: controller([ik]), steps: [body] });+ expect(() => check({ kind: 'foot-plant', tip: 'foot.L', target: 'beacon' })).toThrow(/has no target/);+ expect(() => check({ kind: 'foot-plant', tip: 'foot.L', pelvis: 'nope' })).toThrow(/pelvis "nope" is not a joint/);+ expect(() => check({ kind: 'foot-plant', tip: 'hips' })).toThrow(/foot-plant ik needs two bones above "hips"/);+ expect(() => check({ kind: 'look-at', tip: 'head', target: 'beacon', pelvis: 'hips' })).toThrow(/belong to a foot-plant/);+ expect(() => check({ kind: 'foot-plant', tip: 'foot.L', reach: 'far' })).toThrow(/reach must be a number/);+ });+});++describe('previewing the rest', () => {+ it('a look-at turns the joint to its goal, where the clip left it straight', () => {+ const m = bake([{ kind: 'look-at', tip: 'head', target: 'beacon', axis: 'y' }]);+ const before = jointPositions(m.rig!.joints, clip, 0);+ const after = jointPositions(m.rig!.joints, clip, 0, solveOf(m));+ expect(before.crown![0]).toBeCloseTo(0, 5);+ expect(after.crown![0]).toBeGreaterThan(0.45); // its half-unit bone now leans along +X, toward the beacon+ expect(after.crown![1]).toBeCloseTo(3, 3);+ });++ it('a two-bone puts the tip on a goal', () => {+ const near: RigSource = { ...rig, goals: [{ name: 'grab', at: [0.9, 1, 0.5] }] };+ const m = bakeModel({ version: 1, rig: near, animations: [clip], controller: controller([{ kind: 'two-bone', tip: 'foot.L', target: 'grab' }]), steps: [body] });+ const p = jointPositions(m.rig!.joints, clip, 0, solveOf(m));+ expect(Math.hypot(p['foot.L']![0] - 0.9, p['foot.L']![1] - 1, p['foot.L']![2] - 0.5)).toBeLessThan(1e-3);+ });+});++describe('the shape budget', () => {+ it('warns when the deltas would not fit, since the mesh then never changes shape', () => {+ const shapes = Array.from({ length: 80 }, (_, i) => ({ name: `s${i}`, moves: [{ faces: 'all', push: 0.01 }] }));+ const dense: ModelStep = { op: 'organic', resolution: 96, parts: [{ shape: 'sphere', radius: 1 }] };+ const m = bakeModel({ version: 1, shapes, steps: [dense] });+ expect(m.report.warnings.join()).toMatch(/never change shape/);+ const few = bakeModel({ version: 1, shapes: shapes.slice(0, 2), steps: [dense] });+ expect(few.report.warnings.join()).not.toMatch(/never change shape/);+ });+});diff --git a/pipeline/tests/modeling-shapes-ik.test.ts b/pipeline/tests/modeling-shapes-ik.test.tsindex 995af55ea..b40af1e3c 100644--- a/pipeline/tests/modeling-shapes-ik.test.ts+++ b/pipeline/tests/modeling-shapes-ik.test.ts@@ -225,7 +225,7 @@ describe('goals and ik', () => {const check = (ik: unknown, r: RigSource = rig) => validateModelSource({ version: 1, rig: r, animations: [clip], controller: { ...controller, ik }, steps: [limb] });expect(() => check([{ kind: 'look-at', tip: 'aim', target: 'aim' }])).toThrow(/tip "aim" is not a joint/);expect(() => check([{ kind: 'look-at', tip: 'tip', target: 'nope' }])).toThrow(/target "nope" is not a joint or a goal; there are base, mid, tip, aim, hold/);- expect(() => check([{ kind: 'spin', tip: 'tip', target: 'aim' }])).toThrow(/must be two-bone or look-at/);+ expect(() => check([{ kind: 'spin', tip: 'tip', target: 'aim' }])).toThrow(/must be two-bone, look-at or foot-plant/);expect(() => check([{ kind: 'two-bone', tip: 'mid', target: 'aim' }])).toThrow(/two bones above "mid"/);expect(() => check([{ kind: 'look-at', tip: 'tip', target: 'aim', parameter: 'nope' }])).toThrow(/must be a float parameter/);const dup = { joints, goals: [{ name: 'mid', at: [0, 0, 0] }] };diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 26c4c2ae5..85bdcd447 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 · 164 beta · 2050 experimental · 3 deprecated+Symbols: 115 public · 164 beta · 2053 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -533,6 +533,7 @@ removeEntity: (entity: Entity) => voidresetTrigger: (entity: Entity, name: string) => voidsetBool: (entity: Entity, name: string, value: boolean) => voidsetFloat: (entity: Entity, name: string, value: number) => void+setGroundProbe: (probe: GroundProbe | null) => voidsetSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => void@@ -598,10 +599,15 @@ send: (event: AnimatorEventPayload) => void## AnimatorIK — interface @experimental```+align: boolean | undefinedaxis: "x" | "y" | "z" | undefinedkind: AnimatorIKKind+layers: number | undefinedparameter: string | undefined+pelvis: string | undefinedpole: string | undefined+reach: number | undefined+smooth: number | undefinedtarget: stringtip: stringweight: number | undefined@@ -609,7 +615,7 @@ weight: number | undefined## AnimatorIKKind — type @experimental```-'two-bone' | 'look-at'+'two-bone' | 'look-at' | 'foot-plant'```## AnimatorLayer — interface @experimental@@ -4976,6 +4982,25 @@ static prototype: GridLayoutProvider(x: number, z: number) => { y: number; up: number } | null```+## GroundContext — interface @experimental+```+dt: number+memory: Map<string, { lift: number; normal: Vec3; }>+probe: GroundProbe | null+rest: Map<number, { position: Vec3; rotation: Quat; }> | undefined+```++## GroundHit — interface @experimental+```+normal: Vec3+y: number+```++## GroundProbe — type @experimental+```+(origin: Vec3, drop: number, layers: number) => GroundHit | null+```+## Group — interface @experimental```anchor: Placement@@ -17103,7 +17128,7 @@ ServicesPlugin## solveAnimatorIK — function @experimental```-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver, ground?: GroundContext): void```## spatialDistance — function @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 08eed4d0e..6abb72c5e 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 · 169 beta · 2069 experimental · 3 deprecated+Symbols: 115 public · 169 beta · 2072 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -533,6 +533,7 @@ removeEntity: (entity: Entity) => voidresetTrigger: (entity: Entity, name: string) => voidsetBool: (entity: Entity, name: string, value: boolean) => voidsetFloat: (entity: Entity, name: string, value: number) => void+setGroundProbe: (probe: GroundProbe | null) => voidsetSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => void@@ -598,10 +599,15 @@ send: (event: AnimatorEventPayload) => void## AnimatorIK — interface @experimental```+align: boolean | undefinedaxis: "x" | "y" | "z" | undefinedkind: AnimatorIKKind+layers: number | undefinedparameter: string | undefined+pelvis: string | undefinedpole: string | undefined+reach: number | undefined+smooth: number | undefinedtarget: stringtip: stringweight: number | undefined@@ -609,7 +615,7 @@ weight: number | undefined## AnimatorIKKind — type @experimental```-'two-bone' | 'look-at'+'two-bone' | 'look-at' | 'foot-plant'```## AnimatorLayer — interface @experimental@@ -4984,6 +4990,25 @@ static prototype: GridLayoutProvider(x: number, z: number) => { y: number; up: number } | null```+## GroundContext — interface @experimental+```+dt: number+memory: Map<string, { lift: number; normal: Vec3; }>+probe: GroundProbe | null+rest: Map<number, { position: Vec3; rotation: Quat; }> | undefined+```++## GroundHit — interface @experimental+```+normal: Vec3+y: number+```++## GroundProbe — type @experimental+```+(origin: Vec3, drop: number, layers: number) => GroundHit | null+```+## Group — interface @experimental```anchor: Placement@@ -17369,7 +17394,7 @@ ServicesPlugin## solveAnimatorIK — function @experimental```-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver, ground?: GroundContext): void```## spatialDistance — function @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 2ca93774a..8ee81fb43 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 · 166 beta · 2049 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2052 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -528,6 +528,7 @@ removeEntity: (entity: Entity) => voidresetTrigger: (entity: Entity, name: string) => voidsetBool: (entity: Entity, name: string, value: boolean) => voidsetFloat: (entity: Entity, name: string, value: number) => void+setGroundProbe: (probe: GroundProbe | null) => voidsetSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => void@@ -593,10 +594,15 @@ send: (event: AnimatorEventPayload) => void## AnimatorIK — interface @experimental```+align: boolean | undefinedaxis: "x" | "y" | "z" | undefinedkind: AnimatorIKKind+layers: number | undefinedparameter: string | undefined+pelvis: string | undefinedpole: string | undefined+reach: number | undefined+smooth: number | undefinedtarget: stringtip: stringweight: number | undefined@@ -604,7 +610,7 @@ weight: number | undefined## AnimatorIKKind — type @experimental```-'two-bone' | 'look-at'+'two-bone' | 'look-at' | 'foot-plant'```## AnimatorLayer — interface @experimental@@ -4971,6 +4977,25 @@ static prototype: GridLayoutProvider(x: number, z: number) => { y: number; up: number } | null```+## GroundContext — interface @experimental+```+dt: number+memory: Map<string, { lift: number; normal: Vec3; }>+probe: GroundProbe | null+rest: Map<number, { position: Vec3; rotation: Quat; }> | undefined+```++## GroundHit — interface @experimental+```+normal: Vec3+y: number+```++## GroundProbe — type @experimental+```+(origin: Vec3, drop: number, layers: number) => GroundHit | null+```+## Group — interface @experimental```anchor: Placement@@ -17108,7 +17133,7 @@ ServicesPlugin## solveAnimatorIK — function @experimental```-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver, ground?: GroundContext): void```## spatialDistance — function @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex a62812b30..df82ec697 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 · 164 beta · 2071 experimental · 3 deprecated+Symbols: 115 public · 164 beta · 2074 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -528,6 +528,7 @@ removeEntity: (entity: Entity) => voidresetTrigger: (entity: Entity, name: string) => voidsetBool: (entity: Entity, name: string, value: boolean) => voidsetFloat: (entity: Entity, name: string, value: number) => void+setGroundProbe: (probe: GroundProbe | null) => voidsetSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => void@@ -593,10 +594,15 @@ send: (event: AnimatorEventPayload) => void## AnimatorIK — interface @experimental```+align: boolean | undefinedaxis: "x" | "y" | "z" | undefinedkind: AnimatorIKKind+layers: number | undefinedparameter: string | undefined+pelvis: string | undefinedpole: string | undefined+reach: number | undefined+smooth: number | undefinedtarget: stringtip: stringweight: number | undefined@@ -604,7 +610,7 @@ weight: number | undefined## AnimatorIKKind — type @experimental```-'two-bone' | 'look-at'+'two-bone' | 'look-at' | 'foot-plant'```## AnimatorLayer — interface @experimental@@ -4971,6 +4977,25 @@ static prototype: GridLayoutProvider(x: number, z: number) => { y: number; up: number } | null```+## GroundContext — interface @experimental+```+dt: number+memory: Map<string, { lift: number; normal: Vec3; }>+probe: GroundProbe | null+rest: Map<number, { position: Vec3; rotation: Quat; }> | undefined+```++## GroundHit — interface @experimental+```+normal: Vec3+y: number+```++## GroundProbe — type @experimental+```+(origin: Vec3, drop: number, layers: number) => GroundHit | null+```+## Group — interface @experimental```anchor: Placement@@ -17415,7 +17440,7 @@ ServicesPlugin## solveAnimatorIK — function @experimental```-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver, ground?: GroundContext): void```## spatialDistance — function @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex d8d9d5bd8..403f7ad8f 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 · 164 beta · 2062 experimental · 3 deprecated+Symbols: 115 public · 164 beta · 2065 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -528,6 +528,7 @@ removeEntity: (entity: Entity) => voidresetTrigger: (entity: Entity, name: string) => voidsetBool: (entity: Entity, name: string, value: boolean) => voidsetFloat: (entity: Entity, name: string, value: number) => void+setGroundProbe: (probe: GroundProbe | null) => voidsetSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => void@@ -593,10 +594,15 @@ send: (event: AnimatorEventPayload) => void## AnimatorIK — interface @experimental```+align: boolean | undefinedaxis: "x" | "y" | "z" | undefinedkind: AnimatorIKKind+layers: number | undefinedparameter: string | undefined+pelvis: string | undefinedpole: string | undefined+reach: number | undefined+smooth: number | undefinedtarget: stringtip: stringweight: number | undefined@@ -604,7 +610,7 @@ weight: number | undefined## AnimatorIKKind — type @experimental```-'two-bone' | 'look-at'+'two-bone' | 'look-at' | 'foot-plant'```## AnimatorLayer — interface @experimental@@ -4971,6 +4977,25 @@ static prototype: GridLayoutProvider(x: number, z: number) => { y: number; up: number } | null```+## GroundContext — interface @experimental+```+dt: number+memory: Map<string, { lift: number; normal: Vec3; }>+probe: GroundProbe | null+rest: Map<number, { position: Vec3; rotation: Quat; }> | undefined+```++## GroundHit — interface @experimental+```+normal: Vec3+y: number+```++## GroundProbe — type @experimental+```+(origin: Vec3, drop: number, layers: number) => GroundHit | null+```+## Group — interface @experimental```anchor: Placement@@ -17141,7 +17166,7 @@ ServicesPlugin## solveAnimatorIK — function @experimental```-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver, ground?: GroundContext): void```## spatialDistance — function @experimentaldiff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.tsindex 5f29a91a3..df4ec3e4f 100644--- a/sdk/src/animation/Animator.ts+++ b/sdk/src/animation/Animator.ts@@ -35,7 +35,7 @@ import { MaskReach, type AnimatorMask } from './animatorMask';import {avatarResolver, rebasePose, travelRatio, type AnimatorAvatar, type JointResolver,} from './animatorAvatar';-import { solveAnimatorIK, type AnimatorIK } from './animatorIK';+import { solveAnimatorIK, type AnimatorIK, type GroundContext, type GroundProbe } from './animatorIK';import { AnimatorRootMotion, type AnimatorRootMotionData } from './animatorRootMotion';import type { AnimatorEventSink } from './animatorEvent';import { Transform, type TransformData } from '../ecs/component';@@ -626,6 +626,7 @@ export class AnimatorControllerAPI {private readonly triggers = new Map<Entity, Set<string>>();private readonly runtimes_ = new Map<Entity, AnimatorRuntime>();private readonly motions_ = new MotionRegistry();+ private groundProbe_: GroundProbe | null = null;constructor() {// The kinds the animation core itself can play. Everything else — a@@ -653,6 +654,11 @@ export class AnimatorControllerAPI {return this.motions_.has(kind);}+ /** What foot-plant constraints ask about the ground; a physics plugin wires it. Without one they leave the clip's feet alone. */+ setGroundProbe(probe: GroundProbe | null): void {+ this.groundProbe_ = probe;+ }+/** Inject the Spine driver (SpinePlugin wires SpineManager here). Optional —* without it, spine-targeting states are inert. */setSpineDriver(driver: SpineAnimationDriver | null): void {@@ -805,7 +811,8 @@ export class AnimatorControllerAPI {// between composing and writing — on the pose this frame stated,// never on the world's record of the last one.if (wrote && def.ik?.length) {- solveAnimatorIK(world, entity, rt.composed, def.ik, params, joints);+ solveAnimatorIK(world, entity, rt.composed, def.ik, params, joints,+ this.groundFor(rt, dt));}// One write for the whole stack: a layer states values, and what the// entity ends up as is the stack's answer, not the topmost writer's.@@ -1083,6 +1090,13 @@ export class AnimatorControllerAPI {* not rebuilt: a controller swapped for one with more layers keeps the base* layer mid-clip, which is what the entity is visibly doing.*/+ private groundFor(rt: AnimatorRuntime, dt: number): GroundContext {+ const ground = rt.ground ??= { probe: null, dt: 0, memory: new Map() };+ ground.probe = this.groundProbe_;+ ground.dt = dt;+ return ground;+ }+private runtimeFor(entity: Entity, layers: number): AnimatorRuntime {let rt = this.runtimes_.get(entity);if (!rt) {@@ -1120,6 +1134,8 @@ const IDENTITY_QUAT = { w: 1, x: 0, y: 0, z: 0 };/** One entity's playback state: transient, so it lives here and not on the* component, which is what a scene saves and an inspector shows. */interface AnimatorRuntime {+ /** Where each planted foot had settled, for easing onto a new height. */+ ground?: GroundContext;/** One per layer, the base layer at 0. */layers: LayerRuntime[];/** What the whole stack came to, written to the world once. */diff --git a/sdk/src/animation/animatorGraph.ts b/sdk/src/animation/animatorGraph.tsindex ffd5d78fc..859cd4209 100644--- a/sdk/src/animation/animatorGraph.ts+++ b/sdk/src/animation/animatorGraph.ts@@ -290,5 +290,8 @@ export function updateIK(const merged = { ...current, ...patch };if (merged.kind === 'look-at') delete merged.pole;else delete merged.axis;+ if (merged.kind !== 'foot-plant') {+ delete merged.pelvis; delete merged.align; delete merged.reach; delete merged.smooth; delete merged.layers;+ }return { ...def, ik: def.ik!.map((x, i) => (i === index ? merged : x)) };}diff --git a/sdk/src/animation/animatorIK.ts b/sdk/src/animation/animatorIK.tsindex 9b56e72c6..e2eab8d37 100644--- a/sdk/src/animation/animatorIK.ts+++ b/sdk/src/animation/animatorIK.ts@@ -32,7 +32,7 @@ import type { Pose } from './pose';import type { MotionParams } from './motion';/** What an IK constraint does to the joint it names. */-export type AnimatorIKKind = 'two-bone' | 'look-at';+export type AnimatorIKKind = 'two-bone' | 'look-at' | 'foot-plant';export interface AnimatorIK {kind: AnimatorIKKind;@@ -48,6 +48,38 @@ export interface AnimatorIK {pole?: string;/** look-at: the tip's own axis that ends up pointing at the target. */axis?: 'x' | 'y' | 'z';+ /** foot-plant: a joint lowered so the leg reaching the lowest foot still can: the hips. */+ pelvis?: string;+ /** foot-plant: lay the foot along the slope under it. Default true. */+ align?: boolean;+ /** foot-plant: how far up and down to look for ground, in the rig's units. Default the leg's length. */+ reach?: number;+ /** foot-plant: seconds to settle on a new height, so a step onto a kerb is not a jump. Default 0.06. */+ smooth?: number;+ /** foot-plant: the physics layers that count as ground. Default all of them. */+ layers?: number;+}++/** What is under a point, in the world. */+export interface GroundHit {+ y: number;+ normal: Vec3;+}++/**+ * Asks what ground lies below `origin`, within `drop`. Injected rather than imported:+ * the animation core runs in a game with no physics at all, and with no probe a+ * foot-plant simply leaves the clip's feet where they are.+ */+export type GroundProbe = (origin: Vec3, drop: number, layers: number) => GroundHit | null;++/** What a frame's foot-plants need beyond the pose: the probe, the step, and where each foot had settled. */+export interface GroundContext {+ probe: GroundProbe | null;+ dt: number;+ memory: Map<string, { lift: number; normal: Vec3 }>;+ /** Each joint a foot-plant moves, as it stood before the first one did. */+ rest?: Map<Entity, { position: Vec3; rotation: Quat }>;}interface Vec3 { x: number; y: number; z: number }@@ -235,22 +267,31 @@ function solveTwoBone(const tip = resolveJoint(rigRoot, ik.tip);const target = resolveJoint(rigRoot, ik.target);if (tip === null || target === null) return false;+ const pTarget = place(world, pose, rigRoot, target);+ if (!pTarget) return false;+ return bendChain(world, pose, rigRoot, tip, pTarget.position, ik, weight, resolveJoint) !== null;+}++/** The chain above `tip` bent to put it at `goal`, in the rig's space. Answers the rotation the tip's parent ends at, or null when there is no chain. */+function bendChain(+ world: World, pose: Pose, rigRoot: Entity, tip: Entity, goal: Vec3, ik: AnimatorIK, weight: number,+ resolveJoint: JointResolver,+): Quat | null {const mid = parentOf(world, tip);const root = mid === null ? null : parentOf(world, mid);- if (mid === null || root === null) return false;+ if (mid === null || root === null) return null;const pTip = place(world, pose, rigRoot, tip);const pMid = place(world, pose, rigRoot, mid);const pRoot = place(world, pose, rigRoot, root);- const pTarget = place(world, pose, rigRoot, target);- if (!pTip || !pMid || !pRoot || !pTarget) return false;+ if (!pTip || !pMid || !pRoot) return null;const upper = sub(pMid.position, pRoot.position);const lower = sub(pTip.position, pMid.position);- const reach = sub(pTarget.position, pRoot.position);+ const reach = sub(goal, pRoot.position);const a = len(upper);const b = len(lower);- if (a < 1e-6 || b < 1e-6 || len(reach) < 1e-6) return false;+ if (a < 1e-6 || b < 1e-6 || len(reach) < 1e-6) return null;const c = Math.min(Math.max(len(reach), Math.abs(a - b) + 1e-5), a + b - 1e-5);const along = normalized(reach);@@ -281,8 +322,7 @@ function solveTwoBone(q.mul(carried, pMid.rotation)));const rootActual = leanJoint(world, pose, root, pRoot.parentRotation, rootWanted, weight);- leanJoint(world, pose, mid, rootActual, midWanted, weight);- return true;+ return leanJoint(world, pose, mid, rootActual, midWanted, weight);}/** The first direction that leaves the line; any will do for a straight limb. */@@ -313,17 +353,139 @@ function solveLookAt(return true;}+/** The steepest a foot is laid over, whatever is under it: past this it is a wall, or a ray that found the wrong thing. */+const MAX_FOOT_TILT = Math.PI / 4;+const UP: Vec3 = { x: 0, y: 1, z: 0 };++/** Where the rig stands in the world. A root with no parent is read from what it says this frame, not the record of the last. */+function rigFrame(world: World, rigRoot: Entity): { p: Vec3; r: Quat; s: Vec3 } {+ const t = world.get(rigRoot, Transform) as TransformData;+ return parentOf(world, rigRoot) === null+ ? { p: t.position, r: t.rotation, s: t.scale }+ : { p: t.worldPosition, r: t.worldRotation, s: t.worldScale };+}++/**+ * Feet on the ground the clip did not know about. The clip's height above the rig's+ * floor is kept, so a lifted foot stays lifted, and the floor under each foot is+ * moved to where the ground really is. Every foot is measured first, because the+ * pelvis has to drop for the lowest of them before any leg is solved.+ */+function plantFeet(+ world: World, pose: Pose, rigRoot: Entity, feet: readonly { ik: AnimatorIK; weight: number }[],+ resolveJoint: JointResolver, ground: GroundContext,+): void {+ const frame = rigFrame(world, rigRoot);+ const inverse = q.conjugate(frame.r);+ const toWorld = (v: Vec3): Vec3 => add(frame.p, q.rotate(frame.r, { x: v.x * frame.s.x, y: v.y * frame.s.y, z: v.z * frame.s.z }));+ const toRig = (v: Vec3): Vec3 => {+ const l = q.rotate(inverse, sub(v, frame.p));+ return { x: l.x / frame.s.x, y: l.y / frame.s.y, z: l.z / frame.s.z };+ };+ // A joint no clip keys keeps what was last written to it, which here is last frame's solve: measured as the+ // clip's foot, that would read the lift as already done and take it off again, every other frame.+ const rest = ground.rest ??= new Map();+ const unbend = (joint: Entity | null): void => {+ if (joint === null) return;+ const local = localOf(world, pose, joint);+ if (!local) return;+ if (!rest.has(joint)) rest.set(joint, { position: { ...local.position }, rotation: { ...local.rotation } });+ const was = rest.get(joint)!;+ const track = pose.track(world, joint, Transform);+ if (!track) return;+ if (!track.touched.has('rotation')) { track.data.rotation = { ...was.rotation }; track.touched.add('rotation'); }+ if (!track.touched.has('position')) { track.data.position = { ...was.position }; track.touched.add('position'); }+ };+ for (const { ik } of feet) {+ const tip = resolveJoint(rigRoot, ik.tip);+ if (tip === null) continue;+ const mid = parentOf(world, tip);+ unbend(tip);+ unbend(mid);+ unbend(mid === null ? null : parentOf(world, mid));+ if (ik.pelvis) unbend(resolveJoint(rigRoot, ik.pelvis));+ }++ const planted: { ik: AnimatorIK; weight: number; tip: Entity; at: Vec3; rotation: Quat; lift: number; normal: Vec3 }[] = [];+ for (const { ik, weight } of feet) {+ const tip = resolveJoint(rigRoot, ik.tip);+ if (tip === null) continue;+ const pTip = place(world, pose, rigRoot, tip);+ const mid = parentOf(world, tip);+ const root = mid === null ? null : parentOf(world, mid);+ const pMid = mid === null ? null : place(world, pose, rigRoot, mid);+ const pRoot = root === null ? null : place(world, pose, rigRoot, root);+ if (!pTip || !pMid || !pRoot) continue;++ const reach = ik.reach ?? len(sub(pMid.position, pRoot.position)) + len(sub(pTip.position, pMid.position));+ const foot = toWorld(pTip.position);+ const span = reach * Math.abs(frame.s.y);+ const hit = ground.probe!({ x: foot.x, y: foot.y + span, z: foot.z }, span * 2, ik.layers ?? 0);++ let wantedLift = 0;+ let wantedNormal = UP;+ if (hit) {+ // The same spot with the floor moved: its height above the floor kept, its place over the ground unchanged.+ const landed = toRig({ x: foot.x, y: hit.y + pTip.position.y * frame.s.y, z: foot.z });+ wantedLift = landed.y - pTip.position.y;+ wantedNormal = q.rotate(inverse, hit.normal);+ }+ const key = `${rigRoot}/${ik.tip}`;+ const held = ground.memory.get(key);+ const tau = ik.smooth ?? 0.06;+ const k = !held || tau <= 0 ? 1 : 1 - Math.exp(-ground.dt / tau);+ const lift = held ? held.lift + (wantedLift - held.lift) * k : wantedLift;+ const normal = normalized(held ? add(held.normal, scale(sub(wantedNormal, held.normal), k)) : wantedNormal);+ ground.memory.set(key, { lift, normal });+ planted.push({ ik, weight, tip, at: pTip.position, rotation: pTip.rotation, lift, normal });+ }++ // Each pelvis drops for the lowest foot under it, and only down: on rising ground the knees take it.+ const drops = new Map<string, number>();+ for (const f of planted) {+ if (!f.ik.pelvis) continue;+ drops.set(f.ik.pelvis, Math.min(drops.get(f.ik.pelvis) ?? 0, f.lift * f.weight));+ }+ for (const [path, drop] of drops) {+ if (drop >= 0) continue;+ const pelvis = resolveJoint(rigRoot, path);+ const placed = pelvis === null ? null : place(world, pose, rigRoot, pelvis);+ const track = pelvis === null ? null : pose.track(world, pelvis, Transform);+ if (!placed || !track) continue;+ track.data.position = add(track.data.position as Vec3, q.rotate(q.conjugate(placed.parentRotation), { x: 0, y: drop, z: 0 }));+ track.touched.add('position');+ }++ for (const f of planted) {+ // From where the clip had it, not where the dropped pelvis has carried it to.+ const goal = { x: f.at.x, y: f.at.y + f.lift, z: f.at.z };+ const carrier = bendChain(world, pose, rigRoot, f.tip, goal, f.ik, f.weight, resolveJoint);+ if (!carrier || f.ik.align === false) continue;+ const tilt = angleBetween(UP, f.normal);+ const limited = tilt > MAX_FOOT_TILT ? normalized(add(scale(UP, Math.sin(tilt - MAX_FOOT_TILT)), scale(f.normal, Math.sin(MAX_FOOT_TILT)))) : f.normal;+ leanJoint(world, pose, f.tip, carrier, q.normalize(q.mul(q.rotationTo(UP, limited), f.rotation)), f.weight);+ }+}+/*** Apply every constraint to the stack's answer, in the order they are declared:* one can move a joint another then reads, and an author who wrote them in an- * order meant it.+ * order meant it. Foot-plants go first, together: where the feet land moves the+ * body the others are measured from.*/export function solveAnimatorIK(world: World, rigRoot: Entity, pose: Pose,constraints: readonly AnimatorIK[], params: MotionParams,resolveJoint: JointResolver = (root, path) => resolveChildEntity(world, root, path),+ ground?: GroundContext,): void {+ if (ground?.probe) {+ const feet = constraints.filter((ik) => ik.kind === 'foot-plant')+ .map((ik) => ({ ik, weight: weightOf(ik, params) })).filter((f) => f.weight > 0);+ if (feet.length) plantFeet(world, pose, rigRoot, feet, resolveJoint, ground);+ }for (const ik of constraints) {+ if (ik.kind === 'foot-plant') continue;const weight = weightOf(ik, params);if (weight <= 0) continue;if (ik.kind === 'look-at') solveLookAt(world, pose, rigRoot, ik, weight, resolveJoint);diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.tsindex 41b0bce54..e52d8c676 100644--- a/sdk/src/animation/index.ts+++ b/sdk/src/animation/index.ts@@ -162,6 +162,9 @@ export {export {solveAnimatorIK,type AnimatorIK,+ type GroundContext,+ type GroundHit,+ type GroundProbe,type AnimatorIKKind,} from './animatorIK';diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 169ac8ba3..77f1b0673 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -579,6 +579,9 @@ export {type AnimatorLayerBlend,type AnimatorMask,type AnimatorIK,+ type GroundContext,+ type GroundHit,+ type GroundProbe,type AnimatorIKKind,type AnimatorAvatar,type JointResolver,diff --git a/sdk/src/physics3d/Physics3DPlugin.ts b/sdk/src/physics3d/Physics3DPlugin.tsindex 789d7417b..e7f71698d 100644--- a/sdk/src/physics3d/Physics3DPlugin.ts+++ b/sdk/src/physics3d/Physics3DPlugin.ts@@ -4,6 +4,7 @@* @file Physics3DPlugin.ts* @brief Loads the 3D physics module and drives one world from the ECS.*/+import { AnimatorController } from '../animation/Animator';import { installPlanetGravity } from './planetGravity';import { installRagdolls } from './ragdoll';import { Physics3DRuntime } from './physics3dRuntime';@@ -70,8 +71,15 @@ export class Physics3DPlugin implements Plugin {runtime.module = module;// The character map, not a copy of it: characters are created lazily// by the step, so a snapshot taken here would never hold one.- app.insertResource(Physics3D, new Physics3DQueries(- module, this.config_.pixelsPerUnit, runtime.characters));+ const queries = new Physics3DQueries(module, this.config_.pixelsPerUnit, runtime.characters);+ app.insertResource(Physics3D, queries);+ // What a foot-plant constraint stands on. Beside the queries, because the animation core must not know physics exists.+ if (app.hasResource(AnimatorController)) {+ app.getResource(AnimatorController).setGroundProbe((origin, drop, layers) => {+ const hit = queries.raycast(origin, { x: 0, y: -drop, z: 0 }, layers);+ return hit ? { y: hit.y, normal: { x: hit.normalX, y: hit.normalY, z: hit.normalZ } } : null;+ });+ }app.addSystemToSchedule(Schedule.FixedUpdate, defineSystem([], () => {stepPhysics3D(app, module, runtime.bodies, this.config_,runtime.characters, events, runtime.joints, runtime.pieces,diff --git a/sdk/tests/animatorFootPlant.test.ts b/sdk/tests/animatorFootPlant.test.tsnew file mode 100644index 000000000..d51b92e56--- /dev/null+++ b/sdk/tests/animatorFootPlant.test.ts@@ -0,0 +1,226 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * The claim: a foot stands on the ground the probe reports, measured as a distance,+ * while a foot the clip lifted stays that far off it.+ */+import { describe, it, expect } from 'vitest';+import { Pose, solveAnimatorIK, type AnimatorIK, type GroundProbe } from '../src/animation';+import { Parent, Children, Name, Transform } from '../src/ecs/component';+import { q } from '../src/math/quat';++interface Vec3 { x: number; y: number; z: number }++function makeWorld() {+ const store = new Map<unknown, Map<number, unknown>>();+ const mapOf = (c: unknown) => {+ let m = store.get(c);+ if (!m) { m = new Map(); store.set(c, m); }+ return m;+ };+ return {+ insert(e: number, c: unknown, d: unknown) { mapOf(c).set(e, d); },+ get(e: number, c: unknown) { return mapOf(c).get(e); },+ has(e: number, c: unknown) { return mapOf(c).has(e); },+ set(e: number, c: unknown, d: unknown) { mapOf(c).set(e, d); },+ tryGet(e: number, c: unknown) { return mapOf(c).get(e) ?? null; },+ } as any;+}++const RIG = 1, PELVIS = 2, THIGH = 3, SHIN = 4, FOOT = 5;+const identity = () => ({ w: 1, x: 0, y: 0, z: 0 });++/** Rig on the floor; pelvis at height 2; thigh, shin and foot straight down with a slight knee, so the foot rests at 0. */+function leg(world: any, footAt = 0, rig: Partial<{ position: Vec3; rotation: any; scale: Vec3 }> = {}) {+ const node = (id: number, parent: number | null, name: string, at: Vec3) => {+ world.insert(id, Name, { value: name });+ world.insert(id, Transform, { position: at, rotation: identity(), scale: { x: 1, y: 1, z: 1 } });+ if (parent !== null) {+ world.insert(id, Parent, { entity: parent });+ const held = world.tryGet(parent, Children) as { entities: number[] } | null;+ world.insert(parent, Children, { entities: [...(held?.entities ?? []), id] });+ }+ };+ node(RIG, null, 'Rig', { x: 0, y: 0, z: 0 });+ Object.assign(world.get(RIG, Transform), rig);+ node(PELVIS, RIG, 'Pelvis', { x: 0, y: 2, z: 0 });+ node(THIGH, PELVIS, 'Thigh', { x: 0, y: 0, z: 0 });+ node(SHIN, THIGH, 'Shin', { x: 0, y: -1, z: 0.05 });+ node(FOOT, SHIN, 'Foot', { x: 0, y: -1 + footAt, z: -0.05 });+}++const resolve = (_root: number, path: string): number | null => ({ 'Pelvis/Thigh/Shin/Foot': FOOT, Pelvis: PELVIS } as Record<string, number>)[path] ?? null;+const plant: AnimatorIK = { kind: 'foot-plant', tip: 'Pelvis/Thigh/Shin/Foot', target: '', smooth: 0 };++function rigSpace(world: any, entity: number): { p: Vec3; r: any } {+ const chain: number[] = [];+ for (let at = entity; at !== RIG; at = world.get(at, Parent).entity) chain.unshift(at);+ let p: Vec3 = { x: 0, y: 0, z: 0 };+ let r: any = identity();+ for (const e of chain) {+ const t = world.get(e, Transform);+ const d = q.rotate(r, t.position);+ p = { x: p.x + d.x, y: p.y + d.y, z: p.z + d.z };+ r = q.mul(r, t.rotation);+ }+ return { p, r };+}++const flat = (y: number, normal: Vec3 = { x: 0, y: 1, z: 0 }): GroundProbe => (origin, drop) => (origin.y - drop <= y && origin.y >= y ? { y, normal } : null);++/** The rest of the context a rig keeps between frames, per memory map. */+const rests = new WeakMap<object, Map<any, any>>();+function solve(world: any, ik: AnimatorIK, probe: GroundProbe | null, memory = new Map(), dt = 1 / 60): void {+ const pose = new Pose();+ pose.reset();+ if (!rests.has(memory)) rests.set(memory, new Map());+ solveAnimatorIK(world, RIG, pose, [ik], {}, resolve, { probe, dt, memory, rest: rests.get(memory)! });+ pose.applyTo(world);+}++describe('foot-plant', () => {+ it('with no probe leaves the clip alone: a game with no physics is not broken by one', () => {+ const world = makeWorld();+ leg(world);+ const before = world.get(SHIN, Transform).rotation;+ solve(world, plant, null);+ expect(world.get(SHIN, Transform).rotation).toEqual(before);+ });++ it('stands on raised ground: the foot rises to it and the knee bends', () => {+ const world = makeWorld();+ leg(world);+ solve(world, plant, flat(0.4));+ const { p } = rigSpace(world, FOOT);+ expect(p.y).toBeCloseTo(0.4, 4);+ expect(p.x).toBeCloseTo(0, 4);+ expect(rigSpace(world, SHIN).p.z).toBeGreaterThan(0.2);+ });++ it('is left where it is on the ground it was already on', () => {+ const world = makeWorld();+ leg(world);+ solve(world, plant, flat(0));+ expect(rigSpace(world, FOOT).p.y).toBeCloseTo(0, 4);+ });++ it('a foot the clip lifted stays that far off the ground', () => {+ const world = makeWorld();+ leg(world, 0.2);+ solve(world, plant, flat(0.4));+ expect(rigSpace(world, FOOT).p.y).toBeCloseTo(0.6, 4);+ });++ it('below the leg it stretches as far as it can, and with a pelvis reaches', () => {+ const alone = makeWorld();+ leg(alone);+ solve(alone, plant, flat(-0.5));+ expect(rigSpace(alone, FOOT).p.y).toBeGreaterThan(-0.05);+ const world = makeWorld();+ leg(world);+ solve(world, { ...plant, pelvis: 'Pelvis' }, flat(-0.5));+ expect(rigSpace(world, FOOT).p.y).toBeCloseTo(-0.5, 3);+ expect(rigSpace(world, PELVIS).p.y).toBeCloseTo(1.5, 4);+ });++ it('rising ground leaves the pelvis where it is: the knees take it', () => {+ const world = makeWorld();+ leg(world);+ solve(world, { ...plant, pelvis: 'Pelvis' }, flat(0.4));+ expect(rigSpace(world, PELVIS).p.y).toBeCloseTo(2, 5);+ });++ it('lies along the slope under it, and no steeper than a foot can', () => {+ const up = (w: any) => q.rotate(rigSpace(w, FOOT).r, { x: 0, y: 1, z: 0 });+ const n = { x: 0, y: Math.cos(0.3), z: Math.sin(0.3) };+ const world = makeWorld();+ leg(world);+ solve(world, plant, flat(0, n));+ expect(up(world).z).toBeCloseTo(n.z, 3);+ expect(up(world).y).toBeCloseTo(n.y, 3);+ const wall = makeWorld();+ leg(wall);+ solve(wall, plant, flat(0, { x: 0, y: 0, z: 1 }));+ expect(Math.acos(up(wall).y)).toBeCloseTo(Math.PI / 4, 3);+ const off = makeWorld();+ leg(off);+ solve(off, { ...plant, align: false }, flat(0, n));+ expect(up(off).z).toBeLessThan(0.2); // bent only as far as the leg bends it+ });++ it('with nothing under it goes back to the clip', () => {+ const world = makeWorld();+ leg(world);+ const memory = new Map();+ solve(world, plant, flat(0.4), memory);+ expect(rigSpace(world, FOOT).p.y).toBeCloseTo(0.4, 4);+ solve(world, plant, () => null, memory);+ expect(rigSpace(world, FOOT).p.y).toBeCloseTo(0, 4);+ });++ it('eases onto a new height rather than jumping', () => {+ const world = makeWorld();+ leg(world);+ const memory = new Map();+ const eased = { ...plant, smooth: 0.1 };+ solve(world, eased, flat(0), memory);+ const key = `${RIG}/${plant.tip}`;+ expect(memory.get(key).lift).toBeCloseTo(0, 5);+ solve(world, eased, flat(0.4), memory, 1 / 60);+ const first = memory.get(key).lift;+ expect(first).toBeGreaterThan(0.01);+ expect(first).toBeLessThan(0.2);+ for (let i = 0; i < 120; i++) solve(world, eased, flat(0.4), memory, 1 / 60);+ expect(memory.get(key).lift).toBeCloseTo(0.4, 3);+ expect(rigSpace(world, FOOT).p.y).toBeCloseTo(0.4, 3);+ });++ it('reads a rig scaled and moved in the world', () => {+ const world = makeWorld();+ leg(world, 0, { position: { x: 5, y: 10, z: 0 }, scale: { x: 3, y: 3, z: 3 } });+ const seen: Vec3[] = [];+ solve(world, plant, (o, d) => { seen.push(o); return { y: 10.6, normal: { x: 0, y: 1, z: 0 } }; });+ expect(seen[0]!.x).toBeCloseTo(5, 5);+ // Up by the leg's 2 units, scaled by 3, from where the foot stands at world height 10.+ expect(seen[0]!.y).toBeCloseTo(16, 1);+ expect(rigSpace(world, FOOT).p.y).toBeCloseTo(0.2, 3); // 0.6 in the world is 0.2 in the rig+ });++ it('asks for the layers it was told, and half weight goes half way', () => {+ const world = makeWorld();+ leg(world);+ let layers = -1;+ solve(world, { ...plant, layers: 4 }, (o, d, l) => { layers = l; return { y: 0, normal: { x: 0, y: 1, z: 0 } }; });+ expect(layers).toBe(4);+ const half = makeWorld();+ leg(half);+ solve(half, { ...plant, weight: 0.5, align: false }, flat(0.4));+ const y = rigSpace(half, FOOT).p.y;+ expect(y).toBeGreaterThan(0.05);+ expect(y).toBeLessThan(0.35);+ });++ it('does not feed on itself: a joint no clip keys is measured from its rest, not the solve of the last frame', () => {+ const world = makeWorld();+ leg(world);+ const memory = new Map();+ const heights: number[] = [];+ for (let i = 0; i < 6; i++) {+ solve(world, plant, flat(0.4), memory);+ heights.push(rigSpace(world, FOOT).p.y);+ }+ for (const h of heights) expect(h).toBeCloseTo(0.4, 4);+ });++ it('runs before the others: a look-at reads a body already standing', () => {+ const world = makeWorld();+ leg(world);+ world.insert(9, Name, { value: 'Goal' });+ const pose = new Pose();+ pose.reset();+ const look: AnimatorIK = { kind: 'look-at', tip: 'Pelvis/Thigh/Shin/Foot', target: 'nope' };+ solveAnimatorIK(world, RIG, pose, [look, plant], {}, resolve, { probe: flat(0.4), dt: 1 / 60, memory: new Map() });+ pose.applyTo(world);+ expect(rigSpace(world, FOOT).p.y).toBeCloseTo(0.4, 4);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 7cf288b84..76b0b43d4 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3866,6 +3866,10 @@ export const NOTED = {{"note":"A sea seen from above is no longer scored with straight lines."},"feat(mcp): an agent builds a 3D model in the editor from steps, changes it by one number, and sees every side of it":{"note":"AI agents can build 3D models in the editor from steps."},+ "feat(animation): a foot-plant constraint keeps a foot on the physics ground under it, slopes and steps included":+ {"note":"A foot stands on the ground under it."},+ "feat(mcp): model_write plants feet on the ground, and model_views runs the IK on a test floor":+ {"note":"A foot stands on the ground under it."},"feat(modeling): found weights can be corrected, shapes make expressions, and a controller can reach and look at goals in the game":{"note":"AI agents can build 3D models in the editor from steps."},"feat(mcp): model_write corrects weights, makes shapes and wires ik goals":