Skip to content

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.

Status
Frozen · latest is 0.11
Published
2026-10-12
Title
“Hyprune world 0.9: characters, paths, seats and keepClear; object assets from package directories and libraries; 0.8 objects otherwise”
Dialect
JSON Schema 2020-12 · unknown fields rejected unless marked
Raw schemaworld.schema.json · 2,390 lines · 61 KB
DownloadOpen rawsha256 268d6c7cf7ad…
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}. drawing is null or {pathId, use, spawn: null|{ref}, bind: null|objectId} (a paths.draw in progress); aimed is null or {objectId, name, prompt, interactions[<=8] {id, label, type}}; interaction is 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 required character (boolean) and accent (null or linear RGB); path is null or a qualified path ref (package/<id>, user/<id>), activity null or idle|walking|running|stopped|sitting|guiding|interacting|suspended, seat null or a seat ref (up to 192 characters).
  • editor.paths[] gain required use (route|track|generic), name (string|null), speed (number|null) and stops (at most 32, the world 0.9 stop shape).
  • interaction.reticle.action gains interact. graphicsConfig and graphicsPatch gain npc_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/finish ids are user path ids. Grants: npcs.* and paths.set/remove/draw/finish need objects.control, paths.list needs state.read, interaction.choose needs world.control.
  • Everything else is inherited from 0.22 unchanged (no new grant or event); session.hello reports 0.23 and 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
  • addedanimation
  • addeddirObjectAsset
  • addedinlineObjectAsset
  • addedinstanceInteraction
  • addedinteraction
  • addedkeepClearBox
  • addedlibraryObjectAsset
  • addedobjectSlots
  • addedobjectTraits
  • addedpath
  • addedpathPoint
  • addedpathStop
  • addedseatAnchor
  • addedseatRef
  • addedslotPose
  • addedworldSeat
  • changedtop-level fields
    • ~ formatVersion "0.8" (required) → "0.9" (required)
    • ~ objectAssets any of 2[] · items ≤ 32 → (inlineObjectAsset | dirObjectAsset | libraryObjectAsset)[] · items ≤ 32
    • ~ objects[].pose pose (required) → pose
    • + objects[].path slug
    • + objects[].reverse boolean
    • + objects[].seat seatRef
    • + objects[].accent number[3] · each ≥ 0 · each ≤ 1
    • + objects[].interactions instanceInteraction[] · items 1–8
    • + objects[].locked boolean
    • + paths path[] · items ≤ 64
    • + seats worldSeat[] · items ≤ 64
    • + keepClear keepClearBox[] · 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

FieldTypeConstraints
formatVersionrequired"0.9"
idrequiredid
versionrequiredversion
namerequiredstringlength 1–256
descriptionstringlength 0–4096
licenserequiredstringlength 1–256
scenerequiredpath & string
previewpath
defaultSpawnrequiredslug
spawnsrequiredobject[]items ≥ 1
idrequiredslug
poserequiredpose
nodeindex
attributionrequiredobject[]items ≥ 1
pathrequiredpath | "."
authorrequiredstringlength 1–256
licenserequiredstringlength 1–256
sourcestringlength 1–2048 · pattern ^https://
zonesobject[]items ≥ 0
idrequiredslug
namerequiredstringlength 1–256
boundsrequiredobject
minrequirednumber[3]
maxrequirednumber[3]
anchorsobject[]items ≥ 0
idrequiredslug
poserequiredpose
sizerequirednumber[2]each > 0
screenTyperequiredid
nodeindex
mountmount
navigationobject
kindrequired"mesh"
noderequiredindex
agentRadiusrequirednumber> 0
agentHeightrequirednumber> 0
collisionobject[]items ≥ 0
noderequiredindex
shaperequired"mesh" | "convex"
layerrequired"static"
audioobject[]items ≥ 0
idrequiredslug
pathrequiredpath & string
positionrequirednumber[3]
radiusrequirednumber> 0
gainrequirednumber≥ 0 · ≤ 1
looprequiredboolean
lightmapsobject[]items ≥ 0
materialrequiredindex
texturerequiredindex
texCoordrequired1
encodingrequired"linear" | "srgb"
intensityrequirednumber≥ 0
extensionsextensions
requiredExtensionsid[]items ≥ 0 · unique items
areasobject[]items ≤ 32
idrequiredslug
workspaceSlotrequiredstringpattern ^[0-9]{2,4}$
primaryAnchorrequiredslug
toolAnchorsrequiredslug[]items ≤ 128
dataAnchorsrequiredslug[]items ≤ 128
themerequiredstringlength ≤ 256
spawnIdslug
freePlacementZonesslug[]items ≤ 32
playableobjectrequires at least one of volumes, maxFlyHeight
volumesrequiredany of 2[]items 1–8
when type = "box"object
typerequired"box"
minrequirednumber[3]each ≥ -100000 · each ≤ 100000
maxrequirednumber[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
maxFlyHeightnumber≥ -100000 · ≤ 100000
atmosphereobject
fogrequiredobject
colorrequiredvec3
densityrequirednumber≥ 0 · ≤ 1
heightFalloffrequirednumber≥ 0 · ≤ 10
baseHeightrequirednumber≥ -10000 · ≤ 10000
excludeUnlitrequiredboolean
skyrequiredobject
zenithrequiredvec3
horizonrequiredvec3
groundrequiredvec3
sunrequiredobject
directionrequiredvec3
colorrequiredvec3
intensityrequirednumber≥ 0 · ≤ 10000
angularRadiusrequirednumber≥ 0.001 · ≤ 1
environmentobject
facesrequiredpath[6]
encodingrequired"srgb" | "linear"
intensityrequirednumber≥ 0 · ≤ 10000
rotationrequirednumber≥ -6.283186 · ≤ 6.283186
maxResolutionrequiredinteger≥ 16 · ≤ 512
exposurerequirednumber≥ 0.01 · ≤ 100
toneMappingrequired"aces" | "reinhard" | "linear"
bloomrequiredobject
strengthrequirednumber≥ 0 · ≤ 2
thresholdrequirednumber≥ 0 · ≤ 100
radiusrequirednumber≥ 1 · ≤ 8
outlineobject
enabledrequiredboolean
colourrequirednumber[3]each ≥ 0 · each ≤ 1
widthPxrequirednumber≥ 1 · ≤ 4
depthThresholdrequirednumber≥ 0.0001 · ≤ 1
normalThresholdrequirednumber≥ 0.001 · ≤ 2
placementZonesplacementZone[]items ≤ 32
dataObjectsdataObject[]items ≤ 128
climbablesobject[]items ≤ 128
idrequiredslug
typerequired"ladder" | "rope" | "vines" | "chain-link"
bottomrequirednumber[3]each ≥ -10000 · each ≤ 10000
toprequirednumber[3]each ≥ -10000 · each ≤ 10000
facingrequirednumber[3]each ≥ -10000 · each ≤ 10000
widthrequirednumber≥ 0.6 · ≤ 32
depthrequirednumber≥ 0.1 · ≤ 2
speednumber≥ 0.1 · ≤ 8
exitsrequiredobject
toprequirednumber[3]each ≥ -10000 · each ≤ 10000
bottomrequirednumber[3]each ≥ -10000 · each ≤ 10000
visibilityobject
areasrequiredobject[]items ≤ 256
idrequiredstringlength 1–128
boundsrequiredobject
minrequirednumber[3]each ≥ -100000 · each ≤ 100000
maxrequirednumber[3]each ≥ -100000 · each ≤ 100000
nodesrequiredinteger[]items ≤ 10000 · unique items · each ≥ 0 · each ≤ 9999
visibleFromrequiredstring[]items ≤ 256 · unique items · each length 1–128
playableobjectrequires at least one of volumes, maxFlyHeight
volumesany of 2[]items 1–8
when type = "box"object
typerequired"box"
minrequirednumber[3]each ≥ -100000 · each ≤ 100000
maxrequirednumber[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
maxFlyHeightnumber≥ -100000 · ≤ 100000
backdropobject
farCardsrequiredinteger[]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.

objectsobject[]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.

idrequiredslug
assetrequiredslug
posepose
scalenumber≥ 0.01 · ≤ 100
speednumber≥ 0 · ≤ 10
phasenumber≥ 0 · < 1
ambientnumber[3]each ≥ 0 · each ≤ 16
pathslug

A paths[] slug with use route (characters only); pose is omitted.

reverseboolean

Only with path: start walking towards decreasing arc length.

seatseatRef

Characters without path: sits there permanently.

accentnumber[3]each ≥ 0 · each ≤ 1

Characters only: linear RGB for the accent material.

interactionsinstanceInteraction[]items 1–8

Characters only; replaces the asset's list. Ids unique per list.

lockedboolean

Movable assets only.

pathspath[]items ≤ 64

Authored paths (RFC-0011 Paths): at most 64, 1,024 points in total.

seatsworldSeat[]items ≤ 64

World seat anchors (RFC-0011 Seats and sitting).

keepClearkeepClearBox[]items ≤ 64

Boxes that objects may not block and route stops avoid.

Definitions

animation#

A world 0.8 declarative node animation (spin, orbit or bob).

object

FieldTypeConstraints
noderequiredstringlength 1–128
typerequired"spin" | "orbit" | "bob"
axisrequirednumber[3]each ≥ -1.001 · each ≤ 1.001
pivotnumber[3]each ≥ -10000 · each ≤ 10000
amplitudenumber> 0 · ≤ 10
periodrequirednumber≥ 0.5 · ≤ 3600
phasenumber≥ 0 · < 1

slotPose#

pose

interaction#

Asset-level character interaction: only say and panel, which reference nothing in a world.

object

FieldTypeConstraints
idrequiredslug
labelrequiredstringlength 1–32 · pattern ^[^\u0000-\u001f\u007f]+$
promptstringlength 1–64 · pattern ^[^\u0000-\u001f\u007f]+$
actionrequiredone of 2
when type = "say"object
typerequired"say"
linesrequiredstring[]items 1–8 · each length 1–160 · each pattern ^[^\u0000-\u001f\u007f]+$
when type = "panel"object
typerequired"panel"
panelrequiredslug

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

FieldTypeConstraints
idrequiredslug
positionrequiredvec3
yawrequirednumber≥ -360 · ≤ 360
heightrequirednumber≥ 0.2 · ≤ 1
use"sit"[1]unique items
approachnumber≥ 0.3 · ≤ 2

objectTraits#

Inline object asset traits (object.json 0.9 shapes). Unknown or reserved names reject the world.

object

FieldTypeConstraints
decorativeobject
animationsrequiredanimation[]items 1–16
collidableobject

The 0.8 static collision proxy: a mesh node, not animated, not in an animated subtree.

noderequiredstringlength 1–128
movableobject

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
uprightboolean
scalenumber[2]each ≥ 0.25 · each ≤ 4
characterobject

RFC-0010 character: clips with measured values (walk and idle required), height and radius in metres.

clipsrequiredobjectentries ≤ 64 · keys: length 1–64, pattern ^[a-z][a-z0-9_]*$ · extra keys allowed
walkrequiredobject

Values the import step measured; speed must match the clip's extras.speed within 2%.

speednumber> 0.05 · ≤ 15
seatHeightnumber≥ 0.2 · ≤ 1
idlerequiredobject

Values the import step measured; speed must match the clip's extras.speed within 2%.

speednumber> 0.05 · ≤ 15
seatHeightnumber≥ 0.2 · ≤ 1
speednumber> 0.05 · ≤ 15
seatHeightnumber≥ 0.2 · ≤ 1
heightrequirednumber≥ 1.2 · ≤ 2.2
radiusnumber≥ 0.25 · ≤ 0.5
accentboolean
interactionsinteraction[]items 1–8
seatobject
anchorsrequiredseatAnchor[]items 1–8
capacityinteger≥ 1 · ≤ 8
mountany

Reserved (RFC-0011 P4): a prop that holds a window. Rejected in world format 0.9.

machineany

Reserved for RFC-0013 (live objects). Rejected in world format 0.9.

interactiveany

Reserved (RFC-0011 P4): use actions on ordinary objects. Rejected in world format 0.9.

moverany

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

FieldTypeConstraints
statesone of 2[]items 1–8
idrequiredslug
materialsstring[]items 1–16 · unique items · each length 1–128
nodesstring[]items 1–16 · unique items · each length 1–128
paletterequiredobject[]items 1–16
idrequiredslug
colourrequirednumber[3]each ≥ 0 · each ≤ 1

Linear RGB, 0-1.

emissionrequirednumber≥ 0 · ≤ 16
variant 1object
materialsrequiredany[]
variant 2object
nodesrequiredany[]
labelsobject[]items 1–8
idrequiredslug
poserequiredslotPose
sizerequirednumber[2]each > 0 · each ≤ 16
maxCharsrequiredinteger≥ 1 · ≤ 64
spawnsobject[]items 1–8
idrequiredslug
poserequiredslotPose
effectsobject[]items 1–8
idrequiredslug
poserequiredslotPose

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

FieldTypeConstraints
idrequiredslug
labelrequiredstringlength 1–32 · pattern ^[^\u0000-\u001f\u007f]+$
promptstringlength 1–64 · pattern ^[^\u0000-\u001f\u007f]+$
actionrequiredone of 4
when type = "say"object
typerequired"say"
linesrequiredstring[]items 1–8 · each length 1–160 · each pattern ^[^\u0000-\u001f\u007f]+$
when type = "waypoint"object
typerequired"waypoint"
targetrequiredone of 4
variant 1object
zoneIdrequiredslug
variant 2object
positionrequiredvec3
variant 3object
anchorrequiredslug
variant 4object
objectrequiredslug
when type = "guide"object

Walk the player along a route path (the slug of a paths[] entry with use route).

typerequired"guide"
pathrequiredslug
when type = "panel"object
typerequired"panel"
panelrequiredslug

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

FieldTypeConstraints
positionrequiredvec3
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

FieldTypeConstraints
pointrequiredinteger≥ 0 · ≤ 255
secondsnumber≥ 0.5 · ≤ 600
clip"look_around" | "wave" | "nod" | "idle_fidget"
faceone of 3
variant 1object
positionrequiredvec3
variant 2object
anchorrequiredslug
variant 3object
objectrequiredslug
seatseatRef

path#

An authored path (RFC-0011 Paths). use defaults to generic, closed to false.

any & any

FieldTypeConstraints
idrequiredslug
namestringlength 1–64 · pattern ^[^\u0000-\u001f\u007f]+$
use"route" | "track" | "generic"
closedboolean
pointsrequiredpathPoint[]items 2–256
speednumber≥ 0.1 · ≤ 30
stopspathStop[]items 0–32

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

FieldTypeConstraints
idrequiredslug
poserequiredpose
heightrequirednumber≥ 0.2 · ≤ 1
use"sit"[1]unique items
approachnumber≥ 0.3 · ≤ 2

keepClearBox#

An axis-aligned box objects may not block (doorways, stairs, passages); min below max on every axis.

object

FieldTypeConstraints
idrequiredslug
minrequiredvec3
maxrequiredvec3

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

FieldTypeConstraints
idrequiredslug
scenerequiredpath & string
animationsobject[]items ≤ 16
noderequiredstringlength 1–128
typerequired"spin" | "orbit" | "bob"
axisrequirednumber[3]each ≥ -1.001 · each ≤ 1.001
pivotnumber[3]each ≥ -10000 · each ≤ 10000
amplitudenumber> 0 · ≤ 10
periodrequirednumber≥ 0.5 · ≤ 3600
phasenumber≥ 0 · < 1
collisionobject
noderequiredstringlength 1–128
lightingobject
moderequired"probe" | "unlit"
traitsobjectTraits
slotsobjectSlots

dirObjectAsset#

A package object directory (no trailing slash) holding object.json (object format at most the world's) and its scene.

object

FieldTypeConstraints
idrequiredslug
dirrequiredpath

libraryObjectAsset#

An object of an installed library; a missing library fails activation.

object

FieldTypeConstraints
idrequiredslug
libraryrequiredstringlength 3–256 · pattern ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*@[0-9A-Za-z.+-]+$

An installed shared object library, <reverse-domain id>@<semver>, resolved exactly.

objectrequiredslug

Mirrored byte-for-byte from hyprune/schema at 34849da45183 (2026-10-15). SHA-256 268d6c7cf7ad2e9733b77d4867e012cc7abccfbbb732f8d62c224a5454f6f357.