RFC-0010 — Ambient characters (NPCs)
Status: draft · proposed 2026-10-11; part of world format 0.9 and IPC 0.23 through
RFC-0011 P2. Characters,
routes, stops, seats and interactions are in the world format, and core runs the rules below
(amendment); open questions 1-3 are resolved, 4 is open. A draft companions amendment (object format 0.10, IPC 0.25) adds a character that follows the user through every world. A draft motion amendment (no wire change) drops the automatic pauses while the world is shown. A draft steering amendment (no wire change) makes characters avoid each other, walk round obstacles on their routes, keep their feet in step at any speed and stand in front of the screens they stop at. The shared clip library amendment (motion packs, IPC 0.28, core 0.10.0) lets any character play the clips of any other on the same skeleton, with per-character styles and companion dances. It builds
on the object system in RFC-0011, which extends the world format 0.8
placed objects of RFC-0004: a character is an object asset with
the character trait, and an NPC is an instance of it bound to a route path or standing on a
spot. Paths, stops, seats, interactions, user-spawned characters and the protection rules are
defined there; this RFC keeps the character spec, the import pipeline and the runtime rules. It
does not add a parallel system.
A few ambient characters make a world feel lived in: they walk between places, pause at points of interest, glance at you and step aside. They are scenery. They never block a window, a screen approach or a doorway, never push the player, and never cost frames when nobody is looking. An off switch, the still setting and reduced motion always win.
Character asset (the artist spec)
Section titled “Character asset (the artist spec)”One .glb per character, checked by hyprune-npc-check (core) with exactly the rules
core applies when it loads the file. Authors get it right in their tool or through the
import step below; the NPC characters page is the author’s version.
| Rule | Value |
|---|---|
| Skeleton | A humanoid with the common auto-rig naming (mixamorig:Hips, mixamorig:Spine …, or plain Hips, Head). A root bone at the feet is the top of the hierarchy (the import step adds it). |
| Bones | 40 is the performance target (a warning above it); finger and accessory bones are fine. Core skins at most 64 joints. |
| Influences | At most 4 per vertex, normalised. |
| Units and axes | Metres, +Y up, facing +Z. |
| Budget | 4,000-8,000 triangles; 16,000 is the hard limit. |
| Materials | 1-3: the base; optionally accent, recoloured per area by the world; optionally one emissive material (visor or eyes). One baked material is a valid character: its area variants are then separate characters. Base colour, normal and metallic-roughness textures at most 1024 px; KTX2 (KHR_texture_basisu) and meshopt as in format 0.7 packages. |
| Mesh nodes | body, head, visor where the character has them. |
| Clips | In the same file, 30 fps: idle and walk required; idle_fidget, run, turn_left, turn_right (90 deg in place), look_around, wave, nod, sit, sit_idle optional; other clips are kept but ignored by core. idle, walk, run and sit_idle loop. idle is the calm standing loop a character spends most of its time in (little arm motion); idle_fidget is a busier idle that core plays through once, rarely, while the player is near. |
| Walk speed | 0.7-1.4 m/s, the range for stylised characters (people walk at 1.2-1.4). Core always moves a character at its walk clip’s measured speed (extras.speed, metres per second; for an in-place clip, the speed of the planted foot), so feet don’t slide whatever the number is. |
| Root motion | None: the Hips stay over the root horizontally and root is never animated. Core moves the character and plays walk/run at speed / extras.speed. Clips that travel when authored (walking turns, sitting down) have the travel removed; placing a character at a seat is a runtime job (RFC-0011 seats). |
| Variants | Characters that share clips share the skeleton template (same bone names and hierarchy). |
Mechanical props (a drone, a sign that turns) don’t need a skeleton: their spin and float
are format 0.8 node animations, and a prop that travels is an RFC-0011 mover on a track.
Import pipeline (worlds tooling)
Section titled “Import pipeline (worlds tooling)”tools/npc-import SOURCE OUT.glb runs on the bake host (Blender is never run on a laptop)
and requires a provenance note next to the source (source, author, licence, where the
animations came from, and a statement that the design resembles no third-party character).
It normalises units and axes, adds root, drops object-level and non-hips translation keys,
holds the hips in place (keeping the travel it had as extras.speed, or for in-place clips
measuring the planted-foot speed), renames clips by a mapping file (priority aliases per
canonical name; idle can be the calmest of several candidates, measured by the arms’ mean
angular speed, with a busier one mapped to idle_fidget), resamples to 30 fps,
limits weights, decimates to the budget, scales textures to 1024 px and compresses
(meshopt, KTX2). With --render it also renders a check video: a turntable, then the walk
over a floor that scrolls at the clip speed so foot sliding is visible.
--clips-from OTHER.glb gives a character the clips of another on the same template: for
every shared bone the rotation’s change from the source’s rest pose, taken in world space,
is applied to the target’s own rest pose; bones the source lacks (fingers, accessories)
stay at rest; the hips translation is scaled by the ratio of hip heights. Measured on four
production test characters against each one’s own clips from the authoring tool, this
matched with a median of 2.5-8 deg per bone, and planted feet slid no more than with the
tool’s own clips (spread of planted-foot speed 0.04-0.16 vs 0.15-0.24 for walking). A
two-bone leg IK onto the source’s foot path made both worse and is off unless asked for.
The worlds repository publishes the first four characters made this way, resident-blue,
resident-crimson, resident-desert and resident-ember (characters/, CC-BY-4.0): one
skeleton template, one authored clip set shared by retargeting, 8,000 triangles and about
2.7-2.8 MB each. Core’s nested NPC test walks one of them through Switchyard.
World format: characters are RFC-0011 objects
Section titled “World format: characters are RFC-0011 objects”The format change is RFC-0011’s world format 0.9; nothing here adds fields of its own. A
character is an object directory whose object.json has the character trait (its clips
carry the measured walk speed and seat height); an NPC is an objects[] instance bound to a
route path, or standing on a spot with an optional permanent seat.
"objectAssets": [ {"id": "resident", "dir": "characters/resident-blue"}],"paths": [ {"id": "porter-loop", "use": "route", "closed": true, "points": [{"position": [-6.5, 0, 7], "type": "line"}, {"position": [-6.5, 0, -3], "type": "line"}, {"position": [5, 0, -3], "type": "line"}, {"position": [5, 0, 7], "type": "line"}], "stops": [{"point": 1, "seconds": 3, "clip": "look_around"}, {"point": 2, "seconds": 20, "seat": "court-bench-2"}]}],"objects": [ {"id": "porter-1", "asset": "resident", "path": "porter-loop", "speed": 1, "phase": 0.25, "accent": [0.9, 0.5, 0.1], "interactions": [{"id": "talk", "label": "Talk", "action": {"type": "say", "lines": ["Lifts run every few minutes."]}}]}]Where things are defined:
| Topic | RFC-0011 section |
|---|---|
The character trait, its clips and the allowed trait combinations |
Traits |
Routes, stops, segment geometry, walkability and bindings (replacing this draft’s inline route) |
Paths |
| Sitting at seat anchors (open question 6 of the first draft) | Seats and sitting |
Predefined interactions (say, waypoint, guide, travel, panel, RFC-0012 quest) |
Interactions |
| Characters can’t be carried, pushed, thrown, dropped off ledges or moved out of the playable volume | Characters are protected |
| User-spawned characters, their placement and hiding authored ones | User-spawned characters |
| Probe lighting along a route (open question 7 of the first draft) | Walkability |
What stays as this draft proposed: speed scales both pace and clip rate so feet stay planted;
phase is the fraction of the route at which a character starts; accent recolours the
accent material; characters count toward the 32-asset limit and at most 16 authored character
instances per world (user characters: 8 more); glTF clips are used only for characters; a
character instance’s 0.8 swept-bounds sphere is its current pose’s bounds grown by 0.6 m, and
region visibility follows its current position. The shared clip library below would be an
RFC-0011 library.
Runtime rules (normative once accepted)
Section titled “Runtime rules (normative once accepted)”- Never in the way, never moved by the player. NPCs have no collision with the player. An NPC whose next step would come within its personal space (1.2 m) of the player steps aside, or waits when neither side is walkable. Characters avoid each other and walk round what blocks their routes (steering amendment). Routes never cross a screen approach.
- Frames only when someone is looking. An NPC animates whenever the world is shown: it pauses only while the world is inactive or loading and in focus (the desktop layout covers the world). It does not pause for the power supply, idle time, typing or the free cursor (motion amendment); users pause characters with the motion setting. An animating NPC keeps frames coming only while it is in view and not hidden behind opaque geometry, through the same render-on-demand rule as animated objects (one rule, one code path); paused or still, its pose stays out of the frame key, so render on demand presents nothing.
- Protected. No gesture, tool or IPC method carries, pushes, throws, scales or pockets a character, and nothing moves one off walkable ground, off a ledge or out of the playable volume (RFC-0011).
- Interactions. A character with interactions shows its prompt through the interaction-prompt
path when aimed at within use distance, stops and faces the player while one runs, and
resumes its route afterwards (RFC-0011). Hidden characters
and
npc.motion = offoffer none. - Idle and fidget. At a route point an NPC plays
idle. If the character hasidle_fidgetand the player is within 4 m, it plays the fidget through once instead, at most once every 45 s, and then returns toidle. - Settings:
npc.motion=auto(the rules above),always(the same asauto, kept for compatibility),still(posed, never moving; seated at a seat stop) oroff(hidden). Reduced motion poses them still. Hiding one authored character is a per-world overlay setting (RFC-0011). - Render-pass safety: posing and agent updates run in the tick, never in the render pass; the draw saves and restores GL state like every other pass.
- Cost. Skinning is linear blend with 4 influences from a 64-joint uniform block, drawn with the world shader (same light, fog and ink). Measured in the prototype (Intel iGPU, 4K output, continuous rendering, one 5.4k-triangle character close to the camera): the difference was inside the noise (+0.11 ms at native scale, -0.18 ms at scale 0.5, frames of 8-10 ms). The real cost of an NPC is that it keeps frames coming: about 60 frames per second while one walks in view, none while paused.
Shared clip library
Section titled “Shared clip library”Instead of copying clips into every character at import time, clips can live once per skeleton and every character on it plays them: the shared clip library amendment (motion packs, core retargets at load, character styles and companion dances in IPC 0.28).
Open questions
Section titled “Open questions”Resolved by RFC-0011: the 0.9 shape (characters as objects, routes as paths), seat anchors and probe lighting along a route. Questions 1-3 are resolved by the runtime in core (world format 0.9, amendment).
- Glance at the player (resolved). The head and neck look towards the player’s eye within 4 m, clamped to 45 deg yaw and 20 deg pitch and eased (about 0.35 s to settle), only while the player is in front (within 110 deg of the facing) and never while the player reads a window (typing or focus).
- Stepping aside and avoidance (resolved, amended). A walking character steps aside with a lateral offset from its route of at most 1 m that leaves 0.85 m between the player and its line, on whichever side is walkable; when neither side is, it waits. Characters avoid each other with a local steering layer (sampled offsets and speeds against everyone’s predicted positions, keeping right, a priority rule so two never wait for each other for good) and walk round obstacles on their routes with detours planned on the standing-spot grid.
autoand the power supply (resolved, amended).autodoesn’t depend on the power supply: characters animate on battery, USB-C and unknown supplies as on mains power. Render on demand and the occlusion test keep the cost to characters in view; a still player with none in view gets no frames. Users who want them stopped choosestilloroff. (First resolved as following the offload power profile, pausing on battery, USB-C and unknown supplies.)- Licensing of animation clips that come from an authoring tool’s preset library: allowed in public packages?
Amendment: runtime in core
Section titled “Amendment: runtime in core”World format 0.9 and IPC 0.23 (RFC-0011 P2) put the rules above into core. Where they were open or provisional, core does this:
- Glance and step aside as resolved in open questions 1 and 2. A stepping-aside
character keeps its offset until the player is behind it, then returns to its line. Glance
stops in
stillandoff. - Motion setting.
npc.motion(Lua) andgraphics.npc_motion(IPC 0.23) are one value, persisted ingraphics.json.autopauses while the world is inactive or loading, in focus and under reduced motion (motion amendment; it first also paused while typing, in the free cursor, after 30 s without input and on battery, USB-C or unknown power); thenpcsstate key reports the reason. Paused, still or off, characters cost zero frames: their pose is not in the frame key. - Seats. A character approaches (route point, approach point, anchor), aligns over 0.25 s
(a correction over 0.15 m abandons the seat for a plain stop), plays
sitonce, loopssit_idlefor the stop’s seconds, stands (stand, orsitreversed) and walks back. - Seat fit. This replaces RFC-0011’s ±0.08 m
seatHeighttolerance. Seated, core lifts the root by the anchor’s height minus thesitclip’s seat height:clips.sit.seatHeightfromobject.json, else measured as the lowest thigh vertex above the root in the clip’s final pose. The feet then hang at that lift minus the clip’s ankle sink (how far the ankles end below theiridleheight in the final pose). Core accepts the anchor when this clearance is between -0.03 and 0.45 m; otherwise the stop is a plain stop. A clip authored for a lower seat therefore still sits on a higher one, with the feet off the floor.hyprune-npc-checkreports the measured seat height and ankle sink. - Offload. The offload worker (RFC-0009) draws characters like the in-process renderer: it loads character assets with the package and catalog assets and receives per-frame pose parameters (clips, times, fade, look-at, model), then evaluates the same skinning.
Amendment: motion follows the user’s settings (draft)
Section titled “Amendment: motion follows the user’s settings (draft)”Status: draft, 2026-10-13; no wire change. auto paused characters behind the user’s
back while the world was on screen: on battery, USB-C and unknown supplies (USB-C power
delivery included), after 30 s without input, while typing and in the free cursor. A
request accepted during such a pause (a guide) was never carried out. The motion setting is
how users pause characters, so auto no longer does it for them.
- When characters animate. With
autooralways, whenever the world is shown. They pause only while the world is inactive or loading (npcs.reasoninactive) and in focus (focus, the desktop layout covers the world).autoandalwaysare now equivalent; both stay in thenpc_motionenum.npcs.reasonreportsinactive,focusorreduced motion;battery,usb-c power,power unknown,typing,free cursorandidleare no longer sent. - Cost. Unchanged in kind: render on demand plus the occlusion test. A character keeps frames coming only while it is drawn (in the view and not hidden behind opaque geometry), so a still player with no character in view gets no frames whatever the characters are doing.
- The user’s settings refuse requests.
still, reduced motion andoffstop characters, and a request they would leave undone is refused instead of accepted:interaction.choose(or E on the aimed character) for aguidereturns -32005 with the reason in the message (characters are paused (motion still),… (reduced motion),… (motion off)); E reports it as theruntime.noticeinteraction.refused. Underoffevery interaction is refused, the companion’s included. Talk (say), waypoints and panels need no motion and still run understilland reduced motion; the companion under them keeps following by teleporting out of view (companions, motion settings). A guide in progress ends when the setting changes tostill, reduced motion oroff. - The prompt says why. While characters are posed still or under reduced motion, a shell shows the reason and where to change it with the aimed character’s prompt (for example “Posed still · Objects › Characters”).
Amendment: steering, detours and gait (draft)
Section titled “Amendment: steering, detours and gait (draft)”Status: draft, 2026-10-13; no wire change. Characters walked through each other and through objects placed on their routes, their feet slid when they sped up, and a stop facing a screen looked at it from wherever the route point was (often its side). This amendment closes open question 2.
Movers. Each tick core takes one snapshot of every active character (residents, user characters, the companion): position, velocity over the last tick, radius, facing, whether it is held up, and a priority (residents and user characters in world order, the companion lowest). Every agent decides from that snapshot, so the order they update in changes nothing, and the same snapshot and tick give the same result (no clocks, no randomness).
Steering. A character walking its route scores up to six lateral offsets from its line (its last choice, 0, ±0.45 m, ±0.9 m; an offset counts only where the floor beside the route is walkable here and 0.5, 1.2 and 2 m ahead) times three speeds (full, half, stop) by predicting its own position and everyone else’s over the next 2 s in 0.25 s steps. Others move on at their velocity; one that is held up is predicted on its way at 0.8 m/s. A motion that brings two bodies within 0.12 m of touching costs most, the sooner the more; otherwise the cost grows with the offset, with slowing (less for the lower priority of the two, who gives way) and with a change from last tick’s choice; an offset to the left costs slightly more, so two characters meeting head-on both keep right. It moves sideways at 1 m/s, standing too, and its position never jumps (at a corner, where the offset changes side, it eases over at most its pace plus 1.2 m/s). Whatever the prediction, a step that would bring two bodies within 2 cm while they get closer is not taken. A stop it reaches while stepped aside, or with someone standing on it, is walked past that time. The player keeps priority: the existing sidestep chooses the offset first and steering only picks the speed.
Nobody waits for good. A character stopped for 1 s by a higher-priority one that is also held up ahead of it (within 2.5 m beyond both radii) backs off: it walks its route the other way, stands aside where the floor allows and waits there, and turns back once the other has passed (at most 10 s). Between two characters of which neither yields first, the lower waits 3-6 s (it differs per character) before it does the same. The companion never waits on a resident: when a resident comes through where it stands, or waits in front of it, it walks to the nearest free spot beside that resident’s way (here, or 1-3 m ahead of it and aside) and waits there until the resident has passed.
Detours. Route walkability (RFC-0011) is checked every 0.25 m as before. A run of samples where the body hits collision (a placed object, a pillar) no longer leaves the route unwalkable: core plans a way round on the 0.5 m standing-spot grid from 0.6 m before the stretch to 0.6 m after it (moved out until both ends are clear, up to 2.5 m) and the character walks it, both ways, rejoining the route where it ends. Stops inside such a stretch are skipped. A stretch with no way round, and the other problems (no floor, a ledge, outside the playable volume, a screen approach), leave the route unwalkable as before; guides still need a path without detours. For characters only, user-placed objects without a collision proxy count as their bounds. Detours are planned when the route or the placed objects change, not per tick.
Gait. Locomotion eases its ground speed (2.5 m/s² up, 4 m/s² down) and plays it with the feet in step: below the walk clip’s measured speed the walk plays slower (not below 0.3 x), between the walk and run clips’ speeds the two blend by speed, and above the run speed the run plays faster, up to 1.8 x (the fastest a character goes). Walk and run share one cycle phase that advances by ground speed over the blended stride (the clips’ speed x duration), so the planted foot moves with the floor at every speed, catching up or slowing down. Seats, legs, guides, detours and the companion use the same gait.
Stops facing a screen. A stop with face: {anchor} stands in front of the screen: on the
anchor’s normal through its centre, just outside its approach zone (1.5 m + the body’s radius
- 0.15 m, else 2.3 m or 2.8 m), on the floor, when that spot is walkable and reachable from the
route point within 10 m on the standing-spot grid (round the approach zone, which a route point
beside or behind the screen would cut through in a straight line). The character walks there,
turns to the screen, waits the stop’s seconds and walks back the same way. Without such a spot it stops on the route point and
turns to the screen from there (
npc.suspendednotice). Floor and ceiling screens have no front.
Companion pace. Its E menu offers Run with me or Walk with me (interaction ids
run and walk, type companion, chosen with interaction.choose as Stay and Follow). Core
keeps the choice with the companion (companion.json pace: "run"; walking is the default and
not written) and the companion state does not report it.
Cost. Steering runs only for characters with another one within 6 m (a few predictions per tick); detours are planned once per change. Neither draws: a character still requests frames only while it moves in view (render on demand and occlusion).
Amendment: companions (draft)
Section titled “Amendment: companions (draft)”Status: draft · proposed 2026-10-12. Object format 0.10 (draft) gains an optional
companion block and IPC 0.25 adds the companion methods and state. Nothing here changes
world formats: a companion is the user’s, not the world’s.
A companion is one character the user picks from their installed catalog. It follows them
through every world, independent of the world’s authored paths, and comes along on world
switches. It is a character like any other (this RFC’s spec, RFC-0011’s character trait and
protection, the same agent, posing, drawing and offload path), with its own movement rules
below. There is at most one companion per session.
Companion-capable characters
Section titled “Companion-capable characters”Any catalog entry that passes every rule is companion-capable; core reports the verdict and the
first failing rule per catalog entry (IPC 0.25 companion on objects.catalog entries).
| Rule | Value |
|---|---|
| Source | A library or user catalog entry in state ready. package assets belong to one world and can’t be companions. |
| Character | The character trait, and the character spec above as hyprune-npc-check applies it: no errors. |
| Clips | idle and walk required (as for every character). Optional and used: run (catching up), the block’s idle variants, talk (new canonical name: a loop played while a say line is shown; else nod once, else idle), wave (once, when it rejoins the player after a world switch and is in view), and sit, sit_idle, stand (seat stops of a route it is put on). |
| Size | height at most 2.0 m (doorways), radius at most 0.45 m. |
| Budget | At most 16,000 triangles (8,000 recommended), 64 skinned joints, textures at most 1024 px, at most 32 MiB of estimated GPU memory (the catalog’s gpuBytes). KTX2 textures are recommended: they stay compressed on the GPU. |
| Walk | A measured walk speed of 0.7-1.4 m/s (the spec’s range). |
The companion block (object format 0.10, draft)
Section titled “The companion block (object format 0.10, draft)”Optional, only on objects with the character trait. A character without it is still
companion-capable and uses the defaults.
"traits": {"character": {"clips": {"idle": {}, "idle_alt1": {}, "idle_alt2": {}, "walk": {"speed": 0.92}, "run": {"speed": 2.6}}, "height": 1.78}},"companion": { "name": "Pip", "followDistance": 2.0, "idles": ["idle_alt1", "idle_alt2"], "say": ["Nice place.", "Where to next?", "I'll wait here if you need me to."]}| Field | Rules |
|---|---|
name |
Display name, 1-32 characters. Default: the object’s name. |
followDistance |
Metres behind the player, 1.5-2.5, default 2.0. |
idles |
0-4 idle variants: clip names listed in traits.character.clips, other than the canonical names of this RFC. Played through once now and then while it stands idle. |
say |
0-8 lines of at most 160 characters. Each Talk shows the next line (wrapping round). Without lines, the companion offers no Talk. |
Behaviour (normative once accepted)
Section titled “Behaviour (normative once accepted)”Following. The companion keeps to a follow slot: followDistance from the player’s feet,
40 deg to one side of straight behind their direction of travel (the last one while they stand
still: turning round to look at the companion doesn’t move it; after a warp, their view). It keeps the side it has while that slot is free and changes side only when the
slot is not. A slot is free when it is a walkable standing spot for the companion’s body (the
reachable-floor rule residents use: floor within 0.35 m, capsule clear, playable union),
outside approach zones, placementZones, keepClear volumes and spawn capsules, and outside
the view corridor (below). Otherwise core tries the other side, then the slot straight behind,
then 1.5 m and 2.5 m variants, then the nearest free spot within 3 m of the player.
- It walks there on walkable ground: a path over a 0.5 m grid of standing spots around the player, each step checked as a leg like a seat approach (floor within 0.35 m of the previous step, capsule clear). Steps and stairs are walkable as for residents; ladders, gaps and drops are not. Paths are planned at most twice a second and only while the slot moved by more than 0.5 m or the way became blocked.
- Hysteresis. It starts moving when the slot is more than 0.8 m away or the player more than
followDistance+ 1 m away, and stops within 0.3 m of the slot, so small player motions don’t make it shuffle. - Pace. Its ground speed eases (2.5 m/s² up, 4 m/s² down) towards its pace’s cruising
speed (walk: 1.25 x its walk clip’s speed; run: its run clip’s speed, or 1.5 x walk without
run), plus 0.6 m/s for every metre its way to the slot is longer than 3 m, at most its run clip at 1.8 x, braking to arrive. The gait follows the ground speed with the feet in step (steering amendment). The pace is chosen in its E menu (below); it walks by default. - Personal space. It never comes within 1.0 m of the player’s feet. A player walking into it makes it step out of the way (towards the free side), never the reverse: the companion has no collision with the player and never pushes them.
- Idle. At its slot with the player still, it plays
idle; every 8-20 s (varying) it plays one of its idle variants (oridle_fidget) through once. When the player looks at it (aim within 0.5 m of its capsule, at most 8 m away) it turns its body to face them at 180 deg/s, and glances as residents do.
The view corridor. The companion never stands between the player and a screen they face. While the player aims at a window, a workspace wall or an anchor within 8 m, the corridor is the capsule of radius 0.6 m from their eye to the aimed point; the companion’s capsule must stay out of it, and a companion inside it leaves it first. Approach zones already keep it off the 1.5 m in front of every screen.
Catching up and teleporting. The companion is never seen appearing or vanishing.
- It teleports when it is more than 20 m from the player, when no walkable way to its slot
exists for 1.5 s, right after the player warps or travels (a jump of more than 3 m in one tick:
home switches,
travel, respawn), and when a world loads. - While the player flies (noclip) or climbs, it waits at the last spot it could reach, looking at them; if they land somewhere it can’t walk to within 2 s, or more than 20 m away, it teleports.
- A teleport target is a free spot 2-6 m from the player that is out of view: outside the
camera frustum widened by 10 deg, or hidden behind collision from the player’s eye, and with
a walkable way to the player. The one nearest the follow slot wins. When there is none, the
companion stays hidden (state
waiting) and is placed as soon as one exists, checked twice a second. After a world switch it playswaveonce if the player then looks at it. - No free spot near the player (amendment, core 0.8.4, no wire change). Where every spot
near the player is refused by the free-spot rules (a doorway, the foot of a ramp covered by a
keepClearvolume, an approach or placement zone), the follow slot and the teleport target fall back to standing spots by the walking rules alone (floor, capsule, playable union), still 1 m from the player and outside the view corridor; a free spot is taken again as soon as one exists. With no spot at all and more thanfollowDistance+ 1 m away, it walks towards the player until it is withinfollowDistance, and with no walkable way there it counts as blocked (teleport after 1.5 s). In follow mode it never stands idle further away. Before 0.8.4 it stood idle wherever it was until the player was 20 m away.
Focus and home views. While a window is focused or fullscreen (characters pause, RFC-0010), a companion inside the focused view (the final focus camera’s frustum, or the corridor between the player and the focused wall) is moved to a free spot out of that view when the focus transition starts, and resumes following when focus ends. In a home view it follows like anywhere else; approach zones and the view corridor keep it off the screens.
Motion settings. npc.motion = off hides the companion. When characters are still or
under reduced motion, the companion is posed still and only teleports, out of view, to its
slot when the slot is more than 4 m away; it never walks. While the world is inactive it
stands where it is (focus: above). It is not paused for power, idle time, typing or the free
cursor (motion amendment).
Frames. The companion keeps frames coming only while it moves (walks, runs, turns, is carried) and is in view, through the same render-on-demand rule as residents. Standing at its slot it requests no frames; its idle advances only when something else draws.
Protected, with one exception. RFC-0011’s protection applies: no distance, rotate, scale, gizmo, pocket, push or throw gesture targets it, and nothing puts its root off walkable ground. The one exception is carry (Super+LMB on the companion), which picks it up so the user can set it down (below). It is not pocketed and never carried into a window.
Interactions
Section titled “Interactions”E on the companion (aimed within the use distance) offers, as a choice list when there are
several: Talk (when it has say lines), Stay or Follow, whichever is not the
current mode, and while following Run with me or Walk with me, whichever pace it isn’t
keeping (steering amendment). Talk shows one line as a say caption, faces the player and plays talk; walking
4 m away ends it.
Modes: following, staying, walking a route
Section titled “Modes: following, staying, walking a route”| Mode | What it does | Set by |
|---|---|---|
follow |
The behaviour above. The default. | companion.mode {mode: "follow"}, the E menu, the picker. |
stay |
Stands at a spot, idles and glances; no frames while idle. | companion.mode {mode: "stay"} (where it stands), npcs.bind {id: "companion", pose}, the E menu, or setting it down on walkable ground away from routes. |
route |
Walks a route of this world like a resident: loops or goes to the end and back, honours stops and seats, steps aside. | npcs.bind {id: "companion", path}, paths.draw {bind: "companion"} (tool 3: “Put companion on this path”), or setting it down on a route. |
- Tool 3. While drawing or selecting a route, “Put companion on this path” binds it
(
paths.draw {bind: "companion"}for a new route,npcs.bindfor an existing one). The route must pass the walkability check and has room for it (8 characters per path; the companion counts). - Setting it down. Carrying it, the companion hangs from the grab point with its feet
0.1 m above the floor under the aim, playing
idle. When that floor point is within 0.75 m (horizontally) of a route of this world (or a path the user drew, which then becomes a route: RFC-0011 amendment, core 0.8.4), at a walkable point of it, the route is highlighted and the companion snaps to its nearest point, as mounts snap to walls; releasing binds it to the route withphaseat that point. Released on a free standing spot away from routes, it stays there. Anywhere else (a wall, a ledge, an approach zone) the reticle isinvalidand releasing puts it back where it was picked up. Release velocity is ignored: it is never thrown. - Who keeps which path. Authored residents keep their world’s routes; the user never rebinds them. Characters the user puts in the world, the companion included, stay on the user path they were put on (tool 3, or carried and set down near it as above) until they are moved again or, for the companion, told to Follow.
- Back to following. Follow (E menu, picker,
companion.mode) unbinds it and it walks back to the player (or teleports, by the rules above). - Persistence. The chosen companion is user state (
$XDG_CONFIG_HOME/hyprune/companion.json): it survives restarts and world switches. Astayspot or route binding is per world, in the overlay (editor.jsoncompanions, one record per world, with its path ref,phase,speedandreverse, or its spot). Loading a world restores that world’s binding when its path still exists and is walkable (else its spot, when still free); otherwise the companion follows. A world switch therefore keeps a binding only in the world its path belongs to; in other worlds the companion follows. Removing a bound user path (paths.removewithunbind) returns it to following.
IPC 0.25
Section titled “IPC 0.25”Grants: the companion methods need objects.control (as user characters); reads need
state.read. No new grant.
| Method | Params → result | Grant |
|---|---|---|
companion.set |
{ref}: a companion-capable catalog ref → {revision} |
objects.control |
companion.clear |
{} → {revision} |
objects.control |
companion.mode |
{mode: "follow" | "stay"} → {revision} |
objects.control |
Existing methods that take the companion, by the reserved object id companion:
npcs.bind {id: "companion", path?, pose?, phase?, speed?, reverse?}: a route (moderoute) or a standing spot (modestay), checked as for user characters.accentis refused.paths.draw {bind: "companion"}: draws a new route with tool 3 and binds the companion to it on finish.interaction.choose {objectId: "companion", interactionId}:talk,stayorfollow, and (steering amendment, no wire change: ids of the existingcompaniontype)runorwalk.npcs.disable,npcs.remove,objects.*oncompanionare refused (-32005; usecompanion.clear).
companion.set doesn’t need a loaded world; the companion appears when one is. Errors: -32004
unknown ref; -32005 not companion-capable (the message names the rule), or no companion set
(companion.mode); -32007 a placement or walkability rule (as npcs.bind).
State. companion (new, required):
"companion": { "ref": "library/io.github.ada.pip@0.1.0/pip", "name": "Pip", "state": "active", "reason": null, "mode": "follow", "path": null, "activity": "following", "position": [3.2, 0, -4.1], "carried": false}| Field | Values |
|---|---|
ref, name |
The chosen ref and display name, or null when none is set. |
state |
none (no companion), loading, unavailable (the ref is not installed or no longer capable; reason says why), active, waiting (no out-of-view spot yet) or hidden (npc.motion = off, no world). |
reason |
Null or at most 64 characters. |
mode |
follow, stay or route. |
path |
The bound route’s ref in mode route, else null. |
activity |
Null, or following, walking, running, idle, talking, sitting, waiting or carried. |
position |
The root position (published at most twice a second while it moves), or null. |
carried |
True while the user carries it. |
objects.catalog entries gain companion: null for non-characters, else
{capable, name, reason} (reason null when capable). npcs.aimed and npcs.interaction may
name the companion (objectId: "companion"), whose interaction type is say or companion
(Stay and Follow). paths.list bound may contain companion. The companion is not an
objects.instances entry. Notices (runtime.notice codes): companion.set,
companion.cleared, companion.unavailable, companion.bound, companion.following,
companion.staying.
Peers below 0.25 see none of this: no companion key, no catalog companion field, no
companion in npcs.aimed, npcs.interaction or paths.list bound; the companion is still
drawn for everyone.
Open questions
Section titled “Open questions”- Should a companion offer its own
panelinteractions (asset-level, as residents), or only Talk, Stay and Follow? - Several companions (a pair, a pet and a person)? This draft allows one.
- Should the per-world
stayspot persist, or should Stay end with the session like a world switch?
Amendment: shared clip library
Section titled “Amendment: shared clip library”Status: accepted · proposed 2026-10-15; implemented in core 0.10.0 with IPC 0.28 and motion
format 0.1 (@hyprune/schema 0.14.0). A new motion format 0.1 (@hyprune/schema
motion/v0.1/motion.schema.json) and IPC 0.28. No world or object format change:
core infers a character’s skeleton from its bones.
A clip authored on one character plays on any character with the same skeleton. Clips live in motion packs, tagged by role and style; when a character loads, core adds the pack clips it lacks, retargeted to its body. One walk improves every character on the skeleton, a character picks a walk, run and idle style, and a companion can dance.
Skeletons
Section titled “Skeletons”A skeleton id names a bone set. mixamo-v1 is the humanoid Mixamo set: Hips, Spine,
Head, LeftArm, RightArm, LeftUpLeg, LeftLeg, LeftFoot, RightUpLeg, RightLeg and
RightFoot (with any namespace prefix, mixamorig:Hips). Bones match by canonical key:
the name after the last :, lower case (mixamorig:LeftUpLeg, LeftUpLeg and
Armature:LeftUpLeg are all leftupleg). Core gives a character mixamo-v1 when it has
those bones; the characters made by tools/npc-import all do. A declared skeleton
(traits.character.skeleton {id, aliases}, an alias map from canonical key to the
character’s own bone name for renamed bones) is reserved for a later object format; core
already reads it when present.
Motion packs
Section titled “Motion packs”A pack is a directory motion/<id>/ with motion.json and one or more clips-only rigs
(glTF with a skin and its animations, no mesh):
{ "motionVersion": "0.1", "id": "starter-motion", "name": "Starter motions", "skeleton": {"id": "mixamo-v1"}, "license": "CC-BY-4.0", "attribution": [{"path": ".", "author": "Hyprune contributors", "license": "CC-BY-4.0"}], "rigs": [{"id": "desert", "scene": "desert.glb"}], "clips": [ {"name": "walk-stroll", "role": "walk", "style": "stroll", "rig": "desert"}, {"name": "sit-down", "role": "sit-down", "rig": "desert", "loop": false} ]}| Field | Rule |
|---|---|
id, name |
A slug (the directory’s name) and a display name. |
skeleton.id |
The skeleton its rigs share. |
license, attribution |
SPDX and per-path attribution, as objects. |
rigs |
1-8 {id, scene}; scene a .glb in the pack, at most 32 MiB. |
clips |
1-128 {name, role, style?, rig, clip?, loop?}: clip names the rig’s animation (default name); loop defaults to true. |
Roles and the clip name a character plays them under: idle, walk, run, wave,
talk, guide, dance by their own name; sit-down as sit, stand-up as stand,
seated-idle as sit_idle. A style appends _<style> with - as _ (walk style
stroll plays as walk_stroll, dance style hip-hop as dance_hip_hop). A dance always has
a style; no two clips of a pack play under the same name. A pack holds nothing but
motion.json and its rigs; motion.json is at most 256 KiB.
Where packs come from, first found first: the world package (motion/ beside
world.json), each installed library (motion/ in the library, the newest version of a
library first), then the user’s folder ($XDG_DATA_HOME/hyprune/motion/). At most 16 packs
load; the first pack of an id wins; an invalid pack is skipped and reported.
Binding. When a character asset loads, each pack on its skeleton adds the clips the
character lacks, by played name: embedded clips win, and an earlier pack wins over a later
one. A character can drop a clip of its own to take a pack’s instead (the starter residents
1.1.0 dropped their sit and sit_idle for the pack’s).
Retargeting (core, at load; the same code in hyprune-npc-check --motion):
- Each target bone takes its source bone (by canonical key or alias); unmatched bones keep their rest pose.
- Rotations transfer through both rest poses, in world space: the source’s change from rest is
applied to the target’s rest,
L = inv(Rt(parent)) · Rs(parent) · A · inv(Rs(bone)) · Rt(bone), so rigs whose bones point differently at rest still agree. - Only the hips take a translation: the source’s hips path in world space, its change from rest scaled by the ratio of hip heights (hips above the lowest leg joint at rest), from the target’s rest hips. Every other bone keeps the target’s lengths.
- A walk’s or run’s speed (
extras.speed) scales by the same ratio. A sit-down’s or stand-up’s travel does not: it is the distance from a seat anchor onto the seat, which anchors are placed for. - The seat fit (
sit’s seat height and sink) is measured on the retargeted pose; for a retargeted sit, the seat is at most a fifth of the hip height below the hip joints (clothing skinned to the thighs hangs lower than what the character sits on).
Grounding (every character, own and bound clips, at load). Some exporters keep the hips at
rest height while the knees bend, so a walk floats. A standing clip (walk, run, idle,
talk, wave, turn_*, look_around, nod, guide and their styles; not a sit, a stand or
a dance, whose feet may leave the floor on purpose) whose lowest foot or toe joint never comes
within 2 cm of the character’s ground (the lowest over its idle, else at rest) is lowered by
the difference. Clips are never raised. hyprune-npc-check lists the clips it lowers.
Styles and dances
Section titled “Styles and dances”A character plays a style per role: {walk?, run?, idle?}, each a style it has (its own
walk_<style> clip or a pack’s). A styled clip plays under the role’s name, at its own speed;
a role without a style plays its plain clip. User characters take a style through
npcs.spawn and npcs.bind, the companion through companion.mode (kept across modes and
companions); authored characters keep their own clips.
Dances (role dance) are the companion’s: with any dance_* clip it offers Dance in
its E menu (interaction type dance, its dances as options, at most 16). Choosing one dances it
for twice the clip’s length (8-20 s), facing the player; Dance without an option picks one at
random. A dance ends when the player talks to it, walks off (5 m) or motion stops. While idle,
now and then (every 40-90 s) it dances a few seconds of one (at most 6 s). While talking, its
talk_* clips (role talk with a style) play now and then as reactions.
IPC 0.28
Section titled “IPC 0.28”No new method, grant or event.
| Where | Change |
|---|---|
objects.catalog entries |
motion (required): null for non-characters, else {skeleton, styles: {walk, run, idle}, dances, packs}: the styles and dances it can play, own and bound, and the packs they come from. |
objects.instances |
style (required): a user character’s style, else null. |
npcs.spawn, npcs.bind |
style: a style, or null for plain. |
companion.mode |
style: as above, kept across modes and companions. |
companion state |
style and dance (required; the dance playing, or null); activity dancing. |
npcs.aimed interactions |
options (required): null, or a dance interaction’s dances [{id, label}]. |
interaction.choose |
option: the dance to dance (an option id); only a dance interaction takes one. |
Errors: -32602 an unknown dance or an option on another interaction; -32005 the companion has
no dances or can’t dance now. Peers below 0.28 see none of it: no motion, style, dance or
options fields, no dance interaction among the aimed ones, and a dancing companion as
idle. (The E menu’s choice list still offers Dance to them; chosen, it dances one at random.)
Packaging
Section titled “Packaging”The official starter kit (com.hyprune.starter 0.3.0) ships starter-motion: plain and
styled walks, runs and idles, wave, sit, seated idle, stand-up and talk reactions. The optional
official library com.hyprune.companions (0.1.0: Muse, Ember and Starlit) ships its companions
and companion-moves (fourteen dances): a companion library may ship its own clips, and the
shared starter motions stay in the starter kit. A world package may ship packs for its own characters (Lumen Reach ships
starter-motion so its residents sit on any core with the library). tools/gltf/motion-pack.mjs
(worlds) builds a pack from rigged exports; hyprune motion check (SDK) and the library check
validate one; hyprune-npc-check CHARACTER --motion DIR lists the clips a pack gives a
character, with speed and foot slip.
Open questions
Section titled “Open questions”- Declared skeletons and alias maps in the object format (
traits.character.skeleton): for rigs whose bone names differ. - Foot locking: clips retargeted to very different proportions slide a little (no IK).
- Should authored characters take styles from the world (
objects[].character.style)?