@kento/frames

Nested frames, surfaces, carriers, surface locomotion, interaction picking and placement between maps. Depends on the kernel (validation) and @kento/debug (the view types frameEntities fills). index.ts is the public entry. Capabilities: frames, interaction, placement (kento.json).

applyMat4(m, x, y, z) and applyRigidInverse(m, x, y, z) (matrix.ts) move a point through a column-major 4x4 (three.js's elements order) and back through a rigid one, without three.

Map frames

frameGraph(frames) compiles a detached, validated snapshot of rigid frames (unit quaternions, no scale); its reads return owned copies. assertFramePose(pose) is the same validation for one pose, without the graph or the copies: for hot paths (a box sweep validates every proxy on every call).

The frame tree (frames.ts, frameTree.test.ts). Frames nest to any depth (a world, a creature on it, a city on the creature, a walker in the city, a cabin in the walker). A MapFrame is plain data the game keeps in its state: { id, parent, origin, rotation, velocity?, spin? }, its pose in the parent and its motion (origin velocity and angular velocity) in the parent's coordinates. The graph composes motion as well as pose (v = V + W×(R o) + R v, w = W + R w), and every relation between two frames goes through their lowest common ancestor, never the root: relative(of, from), point, direction, rotation, velocity(from, to, p, v?) and handOff(body, to) (a FramedPoint re-expressed in another frame, keeping its world place and world motion: stepping off a moving deck keeps the deck's velocity). advanceFrames(frames, dt) steps every frame by its own motion (one fixed step); frameMotion(a, b, dt) is the motion that takes pose a to pose b (a game posing frames by rule sets each step's motion from its next pose); reparentFrame re-hangs a frame keeping its place and motion. All of it is deterministic double arithmetic in a fixed order: the same frames give the same bits in Node and the browser.

Inertia (inertia.ts): frameInertia(before, after, frame, point, dt, { still, gravity? }) is what a moving frame does to what stands in it: the acceleration of a point it carries, seen from a frame taken as still (from the two snapshots' point velocities, so spin and its centripetal part count), and the gravity a body at rest there feels in the frame's own axes (true gravity less that acceleration), split into the push across its floor and the normal press into it. A deck lurching ahead pushes its riders back; a listing one tips their gravity toward its low side.

Surfaces (surfaces.ts): surfacePicker(frames, surfaces) casts a ray at gameplay rectangles ({ id, frame, width, depth, priority? }, on their frame's y=0 from its origin) and returns the nearest front-facing hit. Hits within SURFACE_TIE (1 µm) tie, and a tie goes to the higher priority, then to the innermost frame (a lift's floor flush with the barge deck it stands on is the lift's), then to the lower id, so the result never depends on how surfaces are named or listed (frames.test.ts). Known gap: a rectangle starts at its frame's origin (no offset).

Scale and precision (frameTree.test.ts): the math is f64, so frame-relative work is exact far from the root (two decks 2 km or 1000 km out give bit-identical relative poses). The limit is downstream, in f32 consumers: a navmesh or a renderer is precise within about 2 km of the frame it is rooted at, so a host roots each at the frame its bodies live in and never works in root coordinates far out. The frame math is tested from a 0.3 m crate in a cabin at the rim of a turning 300 m city, and a frame much larger than 2 km must be split into several frames. Rotations are unit quaternions with no scale: a frame cannot shrink or grow its contents.