World manifest 0.9
Schema reference / World manifest / 0.9
The data-only world.json at the root of every world package: scene entry, spawns, areas, anchors, mounts, collision, playable bounds, atmosphere and provenance.
Raw schema
Loading world.schema.json…Changes since 0.8
Changelog · IPC 0.23: characters, paths and interactions (RFC-0011 P2)
- Required state key
npcs {motion (auto|always|still|off), state (none|animating|paused|still|off), reason (null or up to 64 characters, e.g. battery), usage {authored, user}, limits {authored (<=16), user (<=8)}, drawing, aimed, interaction}.drawingis null or{pathId, use, spawn: null|{ref}, bind: null|objectId}(apaths.drawin progress);aimedis null or{objectId, name, prompt, interactions[<=8] {id, label, type}};interactionis null or{objectId, interactionId|null, type (choose|say|waypoint|guide|panel), label, choices[<=8] {id, label}, line|null, lineIndex, lineCount, panel|null}.objects.instances[]gain requiredcharacter(boolean) andaccent(null or linear RGB);pathis null or a qualified path ref (package/<id>,user/<id>),activitynull oridle|walking|running|stopped|sitting|guiding|interacting|suspended,seatnull or a seat ref (up to 192 characters).editor.paths[]gain requireduse(route|track|generic),name(string|null),speed(number|null) andstops(at most 32, the world 0.9 stop shape).interaction.reticle.actiongainsinteract.graphicsConfigandgraphicsPatchgainnpc_motion(auto,always,still,off).- Methods:
npcs.spawn {ref, path?, pose?, phase?, speed? (0.25..2), accent?, reverse?}({revision, id}; path and pose exclusive, reverse needs a path);npcs.bind {id, path?, pose?, phase?, speed?, accent?, reverse?}(at least one setting);npcs.disable {id, disabled};npcs.remove {id}|{all:true};paths.list {}({paths[<=192]}:{ref, source (package|user), id, name, use, closed, points, speed, stops, walkable (null for non-routes), problems[<=8], bound[<=8]});paths.set {path: {id?, name?, use, closed, points[2..256], speed?, stops?}}({revision, id});paths.remove {id, unbind?};paths.draw {use?, name?, spawn? {ref, phase?, speed?, accent?}, bind?}({revision, id}; spawn and bind exclusive);paths.finish {}({revision, id|null, bound|null});interaction.choose {objectId, interactionId|null}. Path params take a qualified ref or a bare id (package/<id>);paths.set/remove/draw/finishids are user path ids. Grants:npcs.*andpaths.set/remove/draw/finishneedobjects.control,paths.listneedsstate.read,interaction.chooseneedsworld.control.- Everything else is inherited from 0.22 unchanged (no new grant or event);
session.helloreports0.23and lists the ten methods. Inheritance test included.
Changelog · @hyprune/schema 0.8.0 (2026-10-12)
Publishes IPC 0.23 and world format 0.9: characters and NPC instances, authored paths (route/track/generic) with stops, seats, keepClear volumes and NPC interactions.
Structural diff against 0.8: 16 definitions added, 1 definition changed. Descriptions and $id changes are ignored.
17 changes
- added
animation - added
dirObjectAsset - added
inlineObjectAsset - added
instanceInteraction - added
interaction - added
keepClearBox - added
libraryObjectAsset - added
objectSlots - added
objectTraits - added
path - added
pathPoint - added
pathStop - added
seatAnchor - added
seatRef - added
slotPose - added
worldSeat - changed
top-level fields- ~
formatVersion"0.8" (required) → "0.9" (required) - ~
objectAssetsany of 2[] · items ≤ 32 → (inlineObjectAsset | dirObjectAsset | libraryObjectAsset)[] · items ≤ 32 - ~
objects[].posepose (required) → pose - +
objects[].pathslug - +
objects[].reverseboolean - +
objects[].seatseatRef - +
objects[].accentnumber[3] · each ≥ 0 · each ≤ 1 - +
objects[].interactionsinstanceInteraction[] · items 1–8 - +
objects[].lockedboolean - +
pathspath[] · items ≤ 64 - +
seatsworldSeat[] · items ≤ 64 - +
keepClearkeepClearBox[] · items ≤ 64 - −
objectAssets[].id - −
objectAssets[].scene - −
objectAssets[].library - −
objectAssets[].animations - −
objectAssets[].animations[].node - −
objectAssets[].animations[].type - −
objectAssets[].animations[].axis - −
objectAssets[].animations[].pivot - −
objectAssets[].animations[].amplitude - −
objectAssets[].animations[].period - −
objectAssets[].animations[].phase - −
objectAssets[].collision - −
objectAssets[].collision.node - −
objectAssets[].lighting - −
objectAssets[].lighting.mode - −
objectAssets[]|1 - −
objectAssets[]|1.scene - −
objectAssets[]|2 - −
objectAssets[]|2.library
- ~
Manifest fields
| Field | Type | Constraints |
|---|---|---|
formatVersionrequired | "0.9" | |
idrequired | id | |
versionrequired | version | |
namerequired | string | length 1–256 |
description | string | length 0–4096 |
licenserequired | string | length 1–256 |
scenerequired | path & string | |
preview | path | |
defaultSpawnrequired | slug | |
spawnsrequired | object[] | items ≥ 1 |
idrequired | slug | |
poserequired | pose | |
node | index | |
attributionrequired | object[] | items ≥ 1 |
pathrequired | path | "." | |
authorrequired | string | length 1–256 |
licenserequired | string | length 1–256 |
source | string | length 1–2048 · pattern ^https:// |
zones | object[] | items ≥ 0 |
idrequired | slug | |
namerequired | string | length 1–256 |
boundsrequired | object | |
minrequired | number[3] | |
maxrequired | number[3] | |
anchors | object[] | items ≥ 0 |
idrequired | slug | |
poserequired | pose | |
sizerequired | number[2] | each > 0 |
screenTyperequired | id | |
node | index | |
mount | mount | |
navigation | object | |
kindrequired | "mesh" | |
noderequired | index | |
agentRadiusrequired | number | > 0 |
agentHeightrequired | number | > 0 |
collision | object[] | items ≥ 0 |
noderequired | index | |
shaperequired | "mesh" | "convex" | |
layerrequired | "static" | |
audio | object[] | items ≥ 0 |
idrequired | slug | |
pathrequired | path & string | |
positionrequired | number[3] | |
radiusrequired | number | > 0 |
gainrequired | number | ≥ 0 · ≤ 1 |
looprequired | boolean | |
lightmaps | object[] | items ≥ 0 |
materialrequired | index | |
texturerequired | index | |
texCoordrequired | 1 | |
encodingrequired | "linear" | "srgb" | |
intensityrequired | number | ≥ 0 |
extensions | extensions | |
requiredExtensions | id[] | items ≥ 0 · unique items |
areas | object[] | items ≤ 32 |
idrequired | slug | |
workspaceSlotrequired | string | pattern ^[0-9]{2,4}$ |
primaryAnchorrequired | slug | |
toolAnchorsrequired | slug[] | items ≤ 128 |
dataAnchorsrequired | slug[] | items ≤ 128 |
themerequired | string | length ≤ 256 |
spawnId | slug | |
freePlacementZones | slug[] | items ≤ 32 |
playable | object | requires at least one of volumes, maxFlyHeight |
volumesrequired | any of 2[] | items 1–8 |
when type = "box" | object | |
typerequired | "box" | |
minrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
maxrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
when type = "convex" | object | |
typerequired | "convex" | |
pointsrequired | (number[3])[] | items 4–16 · unique items · each each ≥ -100000 · each each ≤ 100000 |
maxFlyHeight | number | ≥ -100000 · ≤ 100000 |
atmosphere | object | |
fogrequired | object | |
colorrequired | vec3 | |
densityrequired | number | ≥ 0 · ≤ 1 |
heightFalloffrequired | number | ≥ 0 · ≤ 10 |
baseHeightrequired | number | ≥ -10000 · ≤ 10000 |
excludeUnlitrequired | boolean | |
skyrequired | object | |
zenithrequired | vec3 | |
horizonrequired | vec3 | |
groundrequired | vec3 | |
sunrequired | object | |
directionrequired | vec3 | |
colorrequired | vec3 | |
intensityrequired | number | ≥ 0 · ≤ 10000 |
angularRadiusrequired | number | ≥ 0.001 · ≤ 1 |
environment | object | |
facesrequired | path[6] | |
encodingrequired | "srgb" | "linear" | |
intensityrequired | number | ≥ 0 · ≤ 10000 |
rotationrequired | number | ≥ -6.283186 · ≤ 6.283186 |
maxResolutionrequired | integer | ≥ 16 · ≤ 512 |
exposurerequired | number | ≥ 0.01 · ≤ 100 |
toneMappingrequired | "aces" | "reinhard" | "linear" | |
bloomrequired | object | |
strengthrequired | number | ≥ 0 · ≤ 2 |
thresholdrequired | number | ≥ 0 · ≤ 100 |
radiusrequired | number | ≥ 1 · ≤ 8 |
outline | object | |
enabledrequired | boolean | |
colourrequired | number[3] | each ≥ 0 · each ≤ 1 |
widthPxrequired | number | ≥ 1 · ≤ 4 |
depthThresholdrequired | number | ≥ 0.0001 · ≤ 1 |
normalThresholdrequired | number | ≥ 0.001 · ≤ 2 |
placementZones | placementZone[] | items ≤ 32 |
dataObjects | dataObject[] | items ≤ 128 |
climbables | object[] | items ≤ 128 |
idrequired | slug | |
typerequired | "ladder" | "rope" | "vines" | "chain-link" | |
bottomrequired | number[3] | each ≥ -10000 · each ≤ 10000 |
toprequired | number[3] | each ≥ -10000 · each ≤ 10000 |
facingrequired | number[3] | each ≥ -10000 · each ≤ 10000 |
widthrequired | number | ≥ 0.6 · ≤ 32 |
depthrequired | number | ≥ 0.1 · ≤ 2 |
speed | number | ≥ 0.1 · ≤ 8 |
exitsrequired | object | |
toprequired | number[3] | each ≥ -10000 · each ≤ 10000 |
bottomrequired | number[3] | each ≥ -10000 · each ≤ 10000 |
visibility | object | |
areasrequired | object[] | items ≤ 256 |
idrequired | string | length 1–128 |
boundsrequired | object | |
minrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
maxrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
nodesrequired | integer[] | items ≤ 10000 · unique items · each ≥ 0 · each ≤ 9999 |
visibleFromrequired | string[] | items ≤ 256 · unique items · each length 1–128 |
playable | object | requires at least one of volumes, maxFlyHeight |
volumes | any of 2[] | items 1–8 |
when type = "box" | object | |
typerequired | "box" | |
minrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
maxrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
when type = "convex" | object | |
typerequired | "convex" | |
pointsrequired | (number[3])[] | items 4–16 · unique items · each each ≥ -100000 · each each ≤ 100000 |
maxFlyHeight | number | ≥ -100000 · ≤ 100000 |
backdrop | object | |
farCardsrequired | integer[] | items ≤ 256 · unique items · each ≥ 0 |
objectAssets | (inlineObjectAsset | dirObjectAsset | libraryObjectAsset)[] | items ≤ 32 Object assets (RFC-0004 world 0.8, RFC-0011 world 0.9): exactly one source each, an inline package glTF, a package object directory or a library object. |
objects | object[] | items ≤ 256 Placed instances of objectAssets (RFC-0004 world 0.8, RFC-0011 world 0.9). pose is required unless path is set and forbidden with it; at most 16 character instances. |
idrequired | slug | |
assetrequired | slug | |
pose | pose | |
scale | number | ≥ 0.01 · ≤ 100 |
speed | number | ≥ 0 · ≤ 10 |
phase | number | ≥ 0 · < 1 |
ambient | number[3] | each ≥ 0 · each ≤ 16 |
path | slug | A paths[] slug with use route (characters only); pose is omitted. |
reverse | boolean | Only with path: start walking towards decreasing arc length. |
seat | seatRef | Characters without path: sits there permanently. |
accent | number[3] | each ≥ 0 · each ≤ 1 Characters only: linear RGB for the accent material. |
interactions | instanceInteraction[] | items 1–8 Characters only; replaces the asset's list. Ids unique per list. |
locked | boolean | Movable assets only. |
paths | path[] | items ≤ 64 Authored paths (RFC-0011 Paths): at most 64, 1,024 points in total. |
seats | worldSeat[] | items ≤ 64 World seat anchors (RFC-0011 Seats and sitting). |
keepClear | keepClearBox[] | items ≤ 64 Boxes that objects may not block and route stops avoid. |
Definitions
animationslotPoseinteractionseatAnchorobjectTraitsobjectSlotsinstanceInteractionseatRefpathPointpathStoppathworldSeatkeepClearBoxinlineObjectAssetdirObjectAssetlibraryObjectAsset
animation#
A world 0.8 declarative node animation (spin, orbit or bob).
object
| Field | Type | Constraints |
|---|---|---|
noderequired | string | length 1–128 |
typerequired | "spin" | "orbit" | "bob" | |
axisrequired | number[3] | each ≥ -1.001 · each ≤ 1.001 |
pivot | number[3] | each ≥ -10000 · each ≤ 10000 |
amplitude | number | > 0 · ≤ 10 |
periodrequired | number | ≥ 0.5 · ≤ 3600 |
phase | number | ≥ 0 · < 1 |
interaction#
Asset-level character interaction: only say and panel, which reference nothing in a world.
object
| Field | Type | Constraints |
|---|---|---|
idrequired | slug | |
labelrequired | string | length 1–32 · pattern ^[^\u0000-\u001f\u007f]+$ |
prompt | string | length 1–64 · pattern ^[^\u0000-\u001f\u007f]+$ |
actionrequired | one of 2 | |
when type = "say" | object | |
typerequired | "say" | |
linesrequired | string[] | items 1–8 · each length 1–160 · each pattern ^[^\u0000-\u001f\u007f]+$ |
when type = "panel" | object | |
typerequired | "panel" | |
panelrequired | slug |
seatAnchor#
Where the sitter's root stands at the start of sit (asset space), facing yaw degrees about +Y from +Z. perch, lean and ground uses are reserved.
object
objectTraits#
Inline object asset traits (object.json 0.9 shapes). Unknown or reserved names reject the world.
object
| Field | Type | Constraints |
|---|---|---|
decorative | object | |
animationsrequired | animation[] | items 1–16 |
collidable | object | The 0.8 static collision proxy: a mesh node, not animated, not in an animated subtree. |
noderequired | string | length 1–128 |
movable | object | Offered for user placement. Defaults: surfaces ["floor"], upright true for floor and ceiling, scale [1, 1]. |
surfaces | ("floor" | "wall" | "ceiling" | "any")[] | items 1–4 · unique items |
upright | boolean | |
scale | number[2] | each ≥ 0.25 · each ≤ 4 |
character | object | RFC-0010 character: clips with measured values (walk and idle required), height and radius in metres. |
clipsrequired | object | entries ≤ 64 · keys: length 1–64, pattern ^[a-z][a-z0-9_]*$ · extra keys allowed |
walkrequired | object | Values the import step measured; speed must match the clip's extras.speed within 2%. |
speed | number | > 0.05 · ≤ 15 |
seatHeight | number | ≥ 0.2 · ≤ 1 |
idlerequired | object | Values the import step measured; speed must match the clip's extras.speed within 2%. |
speed | number | > 0.05 · ≤ 15 |
seatHeight | number | ≥ 0.2 · ≤ 1 |
speed | number | > 0.05 · ≤ 15 |
seatHeight | number | ≥ 0.2 · ≤ 1 |
heightrequired | number | ≥ 1.2 · ≤ 2.2 |
radius | number | ≥ 0.25 · ≤ 0.5 |
accent | boolean | |
interactions | interaction[] | items 1–8 |
seat | object | |
anchorsrequired | seatAnchor[] | items 1–8 |
capacity | integer | ≥ 1 · ≤ 8 |
mount | any | Reserved (RFC-0011 P4): a prop that holds a window. Rejected in world format 0.9. |
machine | any | Reserved for RFC-0013 (live objects). Rejected in world format 0.9. |
interactive | any | Reserved (RFC-0011 P4): use actions on ordinary objects. Rejected in world format 0.9. |
mover | any | World format 0.10 (RFC-0011 P3). Rejected in world format 0.9. |
objectSlots#
Inline object asset slots (object.json 0.9 shapes): authored parts that RFC-0013 drives. Validated and inert in 0.9.
object
| Field | Type | Constraints |
|---|---|---|
states | one of 2[] | items 1–8 |
idrequired | slug | |
materials | string[] | items 1–16 · unique items · each length 1–128 |
nodes | string[] | items 1–16 · unique items · each length 1–128 |
paletterequired | object[] | items 1–16 |
idrequired | slug | |
colourrequired | number[3] | each ≥ 0 · each ≤ 1 Linear RGB, 0-1. |
emissionrequired | number | ≥ 0 · ≤ 16 |
variant 1 | object | |
materialsrequired | any[] | |
variant 2 | object | |
nodesrequired | any[] | |
labels | object[] | items 1–8 |
idrequired | slug | |
poserequired | slotPose | |
sizerequired | number[2] | each > 0 · each ≤ 16 |
maxCharsrequired | integer | ≥ 1 · ≤ 64 |
spawns | object[] | items 1–8 |
idrequired | slug | |
poserequired | slotPose | |
effects | object[] | items 1–8 |
idrequired | slug | |
poserequired | slotPose |
instanceInteraction#
Instance-level character interaction: say, waypoint (zone, position, anchor or object), guide (a route path) or panel. travel and quest are reserved and rejected in world 0.9.
object
| Field | Type | Constraints |
|---|---|---|
idrequired | slug | |
labelrequired | string | length 1–32 · pattern ^[^\u0000-\u001f\u007f]+$ |
prompt | string | length 1–64 · pattern ^[^\u0000-\u001f\u007f]+$ |
actionrequired | one of 4 | |
when type = "say" | object | |
typerequired | "say" | |
linesrequired | string[] | items 1–8 · each length 1–160 · each pattern ^[^\u0000-\u001f\u007f]+$ |
when type = "waypoint" | object | |
typerequired | "waypoint" | |
targetrequired | one of 4 | |
variant 1 | object | |
zoneIdrequired | slug | |
variant 2 | object | |
positionrequired | vec3 | |
variant 3 | object | |
anchorrequired | slug | |
variant 4 | object | |
objectrequired | slug | |
when type = "guide" | object | Walk the player along a route path (the slug of a paths[] entry with use route). |
typerequired | "guide" | |
pathrequired | slug | |
when type = "panel" | object | |
typerequired | "panel" | |
panelrequired | slug |
seatRef#
A world seats[] id, <objectId>/<anchorId> or <objectId> (any free anchor of a seat object).
string · length 1–129 · pattern ^[a-z][a-z0-9-]*(/[a-z][a-z0-9-]*)?$
pathPoint#
The segment type arriving at this point; an open path ignores its first point's type, a closed path uses it for the closing segment.
object
| Field | Type | Constraints |
|---|---|---|
positionrequired | vec3 | |
typerequired | "line" | "curve" | "arc" |
pathStop#
A stop at a point index (one per point, below the point count): seconds (default 3) and at most one of clip, face or seat. Track stops take only point and seconds; generic paths have no stops.
object
worldSeat#
A world-space seat anchor: pose is where the sitter's root stands at the start of sit, facing the pose's +Z; height is the seat surface above it; approach (default 0.6 m) the free floor in front.
object
keepClearBox#
An axis-aligned box objects may not block (doorways, stairs, passages); min below max on every axis.
object
inlineObjectAsset#
A package glTF asset: animations is shorthand for traits.decorative.animations and collision for traits.collidable (giving both forms of one is invalid).
object
| Field | Type | Constraints |
|---|---|---|
idrequired | slug | |
scenerequired | path & string | |
animations | object[] | items ≤ 16 |
noderequired | string | length 1–128 |
typerequired | "spin" | "orbit" | "bob" | |
axisrequired | number[3] | each ≥ -1.001 · each ≤ 1.001 |
pivot | number[3] | each ≥ -10000 · each ≤ 10000 |
amplitude | number | > 0 · ≤ 10 |
periodrequired | number | ≥ 0.5 · ≤ 3600 |
phase | number | ≥ 0 · < 1 |
collision | object | |
noderequired | string | length 1–128 |
lighting | object | |
moderequired | "probe" | "unlit" | |
traits | objectTraits | |
slots | objectSlots |
dirObjectAsset#
A package object directory (no trailing slash) holding object.json (object format at most the world's) and its scene.
object
Mirrored byte-for-byte from hyprune/schema at 34849da45183 (2026-10-15). SHA-256 268d6c7cf7ad2e9733b77d4867e012cc7abccfbbb732f8d62c224a5454f6f357.