Skip to content

RFC-0004 — World packages

Status: accepted · proposed 2026-10-07, accepted 2026-10-09. Implemented through world format 0.9: core loads formats 0.1–0.9. Lumen Reach 0.8.0 is the first release on format 0.7; format 0.8 adds placed world objects, and format 0.9 adds characters, paths, seats and keep-clear volumes (RFC-0011 P2).

A world is an immutable, data-only directory. Its entrypoint is world.json, validated by schema/v0/world.schema.json; geometry uses glTF 2.0, .gltf or .glb. No Lua, executable hooks or downloaded resources. User placement overrides live in core’s separate per-user state, keyed by world ID, package version and anchor ID; an update never edits the installed package.

com.hyprune.observatory/
world.json
scene.gltf # scene.glb is equally valid
geometry/ # external glTF buffers, when needed
textures/ # base color, normal and lightmap textures
audio/ # optional local ambience
LICENSE # declared content license
ATTRIBUTION.md # creators, sources and modifications
preview.png # optional original preview

Manifest fields: formatVersion: "0.1", reverse-domain id, SemVer version, name, license (SPDX expression), scene (relative path), defaultSpawn, nonempty spawns, and attribution (nonempty array of {path, author, license, source?}). Optional description, preview, zones, anchors, navigation, collision, audio, lightmaps, extensions and requiredExtensions. Every shipped asset must be covered by attribution; path: "." covers all package contents as a baseline, more specific paths override it. Sources are provenance URLs, never fetch instructions.

Paths MUST be plain package-relative POSIX paths, no leading slash, empty segments, dot segments, backslash, URI schemes, percent escapes, query or fragment. . is allowed only as the attribution baseline. Resolve each path beneath the package root; reject symlinks and glTF external URIs escaping the root. Reject embedded scripts and remote/data URIs in v0. GLB BIN chunks and image bufferViews are allowed. Distribute directories or .tar.zst archives with one root package; extraction rejects links, devices, absolute paths and traversal. Installer caps: 1 GiB expanded, 10,000 files, 128 MiB single file. Archive installation is later SDK work, not implemented by the schema CLI.

Use glTF’s right-handed coordinates: +Y up, meters, radians, quaternion [x,y,z,w]. Camera forward is -Z; surface front is +Z. pose contains position: [x,y,z] and normalized rotation: [x,y,z,w]. World scale is exactly one meter per unit. An anchor’s size: [width,height] is meters. IDs inside a package are stable lowercase slugs and unique within their collection. Do not use node names as identifiers: manifest node is a zero-based index in the entry glTF’s nodes array, resolved on each package load.

Spawn and anchor poses are world space; their optional node is an authoring association, never an additional transform. Geometry used for collision and navigation uses the referenced node’s complete glTF world transform. Reject multiple-parent nodes, cycles and nonfinite transforms. Spawn orientation and anchor orientation must be normalized within 0.001. Re-exporting node indices requires a package version increment; author tools rewrite references.

Field Data and behavior
spawns {id, pose, node?}. defaultSpawn must exist. Validate a 0.3 m radius, 1.8 m standing capsule at each spawn; author must provide an unobstructed default. Runtime rechecks against loaded collision; invalid spawn rejects activation.
zones {id, name, bounds: {min: vec3, max: vec3}}; world-space AABBs with min < max per axis. Overlap is allowed; all containing zones are active. Zone labels do not grant permissions.
anchors {id, pose, size: vec2, screenType, node?}. Rectangular front-facing interactive area; binds a screen type ID, never a window address. User chooses actual application binding.
navigation {kind: "mesh", node, agentRadius, agentHeight}. Triangular walkable navigation mesh; runtime checks it against collision. No automatic movement script.
collision {node, shape: "mesh" | "convex", layer: "static"} entries. v0 is static geometry only; dynamic objects require a later contract. Visual geometry is not automatically collision.
audio {id, path, position, radius, gain, loop}. Local Ogg Vorbis or WAV, positional attenuation to silence at radius; gain 0..1, user volume/mute always wins. Missing optional audio disables that emitter with a notice.
lightmaps {material, texture, texCoord: 1, encoding: "linear" | "srgb", intensity}. Material and texture are glTF indices; details below.

All optional arrays default to empty. Missing navigation disables assisted walking; missing collision allows only explicit free-flight, never implied safe walking. v0 requires at least one spawn. Unknown screen types show a labeled placeholder and do not execute or install anything.

Keep tiled material UV0 and separately packed, non-overlapping lightmap UV1 (TEXCOORD_1). A lightmap entry binds to a glTF texture index, not the occlusion slot. Every primitive using that material must contain TEXCOORD_1. Each material may have at most one lightmap entry. This is manifest-side Hyprune metadata; do not invent a registered Khronos extension name. Material normals, roughness and albedo retain their glTF meanings.

v0 lightmaps store normalized RGB diffuse irradiance, excluding albedo and emission. Decode base color from sRGB exactly once. Decode lightmap according to explicit encoding (linear means raw linear samples; srgb means decode once). Compute baseColorLinear × lightmapLinear × intensity + emissiveLinear for the baked diffuse path; do not add the same direct diffuse light again. Dynamic/specular terms are separate. Tone map once, encode for the output once. Clamp UV1 sampling at atlas edges with authored gutters and mip-safe padding. v0 supports PNG lightmaps; HDR encodings need a future version. Missing declared lightmaps or UV1 is a validation failure, not an unexplained lighting fallback.

A single baked color atlas is permitted for deliberately unlit art, but is not the recommended world pipeline: it throws away independent texture detail and lighting control. Use standard KHR_materials_unlit for that case. Core advertises its supported glTF extensions and rejects unsupported extensionsRequired. Optional visual glTF extensions may fall back according to glTF rules.

extensions maps reverse-domain names to JSON objects; requiredExtensions lists the keys a loader must understand. Unknown optional entries are ignored with a diagnostic; unknown required entries reject the world before activation. No extension may override path safety, execute code, or weaken provenance rules. The built-in metadata above is versioned directly by formatVersion, not repeated in extensions.

formatVersion: "0.1" is exact. A new structural or semantic contract gets a new identifier; core rejects unsupported versions. version is the author’s SemVer package version. Content changes require a new version and package digest; installations are immutable. Experimental formats are not silently migrated. Tools must write migrations to a new directory and show a report.

  1. Parse bounded JSON and validate the manifest against the offline schema.
  2. Check IDs, references, paths, quaternion normalization, AABBs, and attribution coverage.
  3. Validate the scene with the Khronos glTF validator, then check node/material/texture references, UV1, audio codecs, image dimensions and supported required extensions. Budget GPU resources before upload (initial ceiling 512 MiB world textures/buffers per world; reject over-budget assets or offer an explicit lower-detail package).
  4. Build collision/navigation off-thread; check spawns and stage GPU uploads on the render owner thread within a bounded budget.
  5. Activate scene, anchors, movement origin and audio atomically at a frame boundary; publish one state revision. Keep the old scene until readiness; on failure release staged resources and leave the old scene active.

The small schema CLI covers steps 1 and manifest-local parts of 2. It is not an asset, archive, glTF or rights audit. SDK’s future hyprune world check will add the other stages and deterministic package digests. M0 can accept a minimal original room with spawn and no optional features; it must reject required features it cannot implement.

Official worlds must be original, CC0 or CC-BY-4.0 assets with traceable attribution. Prefer original content released as CC-BY-4.0; keep source assets and reproducible export instructions. Tools/scripts are MIT. Third-party files retain their original license and attribution. The schema accepts SPDX expressions for interoperability, but official-world review applies this narrower policy. Nothing may enter these repositories without the right to license it under these terms. Hypr3D is a lessons-only historical reference.

Amendment M1: material profile, format 0.2

Section titled “Amendment M1: material profile, format 0.2”

Format 0.2 uses hyprune/schema/v0.2/world.schema.json. Its manifest fields are unchanged from 0.1; the version identifies the stronger material rendering contract below. Core continues accepting 0.1 packages. IPC versions are independent. No runtime shader source, texture-generation service, or proprietary assets are implied by this profile.

  • Honor each glTF texture’s sampler: REPEAT, MIRRORED_REPEAT and CLAMP_TO_EDGE independently on S/T; all six minification filters and both magnification filters. If omitted, choose LINEAR_MIPMAP_LINEAR / LINEAR and REPEAT. Generate a full mip chain. Anisotropy is a runtime quality setting, capped at supported hardware limits; core M1 uses up to 8× with trilinear/linear samplers and preserves explicit nearest sampling.
  • Support KHR_texture_transform on baseColorTexture, normalTexture, metallicRoughnessTexture, occlusionTexture and emissiveTexture. Apply offset + rotation * (scale * uv) using radians, including the extension’s texCoord override. Core M1 accepts UV0 and UV1; reject a referenced missing/unsupported set rather than silently sampling UV0. Negative scale and mirrored repeats are legal. Required KHR_texture_transform is supported.
  • UV0 may tile outside [0,1]. Trim sheets use ordinary glTF UVs and transforms: repeat along the strip, clamp across it, and pad strip borders for mip filtering. Do not clamp all material coordinates or repack a material atlas at runtime. Put unique baked irradiance islands on UV1 with sufficient gutters; trim repetition must not repeat lightmaps.
  • Base color and emissive images are sRGB; factors are linear. Normal, metallic-roughness and occlusion images are linear data. Generate color mipmaps in linear light (sRGB texture storage), including when one image has both color and data uses. Normal XY uses normalTexture.scale; normals follow glTF +Y. Metallic is B, roughness is G, occlusion is R, with their glTF factors/strength. Authors should specify metallicFactor explicitly: glTF’s default is 1, not dielectric. Supply roughness detail rather than putting lighting/highlights into base color.
  • Use a tangent frame or a derivative cotangent frame. M1 derives the frame from world-space position and the normal slot’s transformed UVs; this supports meshes without TANGENT and respects mirrored islands. Degenerate UV derivatives fall back to the geometric normal. Supplied TANGENT is not required by this implementation.
  • Manifest lightmaps remain the separate UV1 irradiance contract. They are not occlusionTexture. They use clamp/linear sampling, the manifest encoding and intensity, and no material texture transform. Baked diffuse remains base × irradiance. Metallic surfaces suppress diffuse; roughness controls a cheap view-dependent key-light and analytic sky specular approximation. Multiply both specular components by baked irradiance visibility so unlit corners do not acquire bright reflections. Normal detail may modulate baked diffuse locally; do not add a second full direct diffuse light to a bake. Emission remains additive. Apply tone mapping and display encoding once; preserve live application color separately.

Core M1’s fixed key direction is normalized (0.3,1,0.5), with a cool analytic sky. Roughness is clamped to 0.08 for stable low-cost highlights. This is a documented approximation, not a complete glTF reference PBR renderer: no environment cubemap, shadows, clearcoat, transmission, or material-extension promises. SSAO is deferred pending measured budget; occlusionTexture is supported. The original procedural material laboratory in core exercises tiling, trim strips, transforms, normal maps, channel swizzles and roughness/metalness variations.

Normative glTF behavior: glTF 2.0 and KHR_texture_transform. The irradiance/specular approximation and supported UV-set limit above are Hyprune profile choices.

M1 bounds exported zone metadata to 128 entries and 64 KiB serialized JSON so the revisioned IPC snapshot remains within its private bridge budget. Oversized metadata rejects loading before GPU activation. Material GPU accounting includes both color/data views and every mip level within the existing 512 MiB world budget.

World 0.1/0.2 remain unchanged. The optional extension com.hyprune.map version 0.1 contains {version,path,projection:"xz",north:[0,0,-1],bounds:[minX,minZ,maxX,maxZ],worldToMap:[a,b,c,d,e,f]}. The local safe SVG path and normalized affine map follow RFC-0008. No extension is required to load a world. The reference integration also recognizes the existing com.hyprune.switchyard.map 0.1 authoring proposal, translating its documented 900×1000 blueprint transform (u=(450+19x)/900, v=(200-18z)/1000) into the wire descriptor. This explicit compatibility adapter does not alter the package or infer an undocumented transform from bounds. Its route-node metadata supplies named navigable Map places; nodes are feet positions, converted to eye positions by core. It is static data and establishes no executable movement provider or pathfinding promise. Future packages should use the shared affine profile.

Window capture uses eligible com.hyprune.window anchors in manifest order for the developer default docking layout, with anchor pose/size authoritative. It preserves aspect ratio within the anchor. No anchor launches an application; the trusted developer harness supplies live apps. User-managed persistent bindings remain future work.

Amendment M2: workspace homes and rendering, world format 0.3

Section titled “Amendment M2: workspace homes and rendering, world format 0.3”

World 0.3 uses schema/v0.3/world.schema.json; 0.1/0.2 remain accepted. An area is one workspace’s home. areas declares up to 32 {id,workspaceSlot,primaryAnchor,toolAnchors,dataAnchors,theme,spawnId?,freePlacementZones?}. workspaceSlot is a two-to-four-digit authoring string (e.g. "01"), never a compositor workspace ID. Primary and tool/data IDs have exactly one area owner. The primary anchor has role mounted-workspace. Tools belong to this same home; additional workspace homes repeat a thematic kit under new stable IDs. spawnId selects a feet-position arrival; absent it, core derives a collision-checked standback point facing the primary wall. Actual workspace IDs are user bindings, not instructions in immutable world data.

Anchors gain mount:{type,role,interaction,frameNode?,limits?}. Types are facade-wall, hanging-wall, wall-inset-console, banner, lectern, operator-desk, field-rig, kiosk-pillar, globe, crate, blast-door-screen, terminal-bench, radar-dish. Roles are mounted-workspace|tool-mount|data-object; interaction is respectively focus-in|in-place|none. frameNode identifies the physical frame/bezel in the scene, never an input plane transform. The anchor’s exact quaternion and size remain authoritative, including tilted lecterns. Optional limits contains minAspect,maxAspect,minSize,maxSize: reject incompatible sources rather than stretching pixels. World-space surface front remains local +Z.

Non-planar dataObjects declare {id,areaId,pose,mount,node?}. Their mount role is data-object, interaction none; area dataAnchors owns each ID. Core publishes identity and pose, plus a publisher source binding; the shell or extension provides its presentation.

placementZones declares {id,bounds:{min,max},windowSizes,clearance}; area freePlacementZones lists the string IDs of its reserved volumes. Bounds are metre AABBs; clearance is 0.04–1 m. These are validated opportunities for placement, not a permission to intersect collision. Lumen Reach reserves 4 m tool approaches, 16 m primary-wall standback, 1.6×0.9 and 3.2×1.8 m rectangles, and 0.15 m clearance. World authoring must audit visible geometry as well as collision.

The explicit compatibility adapter for optional com.hyprune.lumen-reach.mounts version 1 accepts areas, mounts, objects. Areas retain the fields above; authoring name and approach annotations are ignored. Mounts contain {anchorId,areaId,workspaceSlot,mountType,role,frameNode?,limits?}; roles tool and data normalize to tool-mount and data-object. Objects {id,pose,mountType,areaId,workspaceSlot,node?} remain separate from planar windows. com.hyprune.lumen-reach.placement version 1 supplies zones. Unknown optional namespaces retain the old ignore behavior. Base Lumen Reach packages can stay format 0.2 with com.hyprune.window screen anchors; adapters validate normalized 0.3 metadata, ownership, slot matching, poses and references. Installed packages are never rewritten.

Optional atmosphere contains fog:{color,density,heightFalloff,baseHeight,excludeUnlit}, sky:{zenith,horizon,ground,sun:{direction,color,intensity,angularRadius}}, exposure, toneMapping:aces|reinhard|linear, and bloom:{strength,threshold,radius}. Colors and radiance are linear RGB; exposure is a positive linear multiplier; FOV is a runtime control in degrees. Fog is camera-relative with integrated exponential height density along the view ray; excludeUnlit protects authored unlit sky art. Sun direction is world-space, angular radius in radians. Bloom extracts HDR world radiance above threshold, downsamples and applies a normalized separable Gaussian kernel. Live app pixels bypass world exposure, fog, tone mapping and bloom.

Optional atmosphere.environment contains six local PNG/JPEG square faces in OpenGL +X,-X,+Y,-Y,+Z,-Z order, encoding:srgb|linear, linear intensity, Y-axis rotation radians and maxResolution 16–512. Each face must be ≤2048²; core resamples and GGX-prefilters a complete linear HDR mip pyramid on a CPU worker, then uploads RGBA16F. A procedural gradient/sun cubemap is the default. Reflection roughness selects a filtered mip; baked diffuse irradiance remains separate. This is static environment IBL, with no SSR or geometry reflection claims. Capture original environment faces near wet floors/practicals to retain architecture and warm light details. Core’s high tier currently uses 128² faces; Intel uses 64² probes, 2× MSAA, at most 2× anisotropy, half-resolution bloom and no SSR. Texture/mip storage counts against the world budget. Reflection probes may follow under a versioned contract.

Honor glTF OPAQUE, MASK (factor × texture alpha versus cutoff) and BLEND. Opaque/masked geometry writes depth; blend geometry sorts back-to-front per primitive and does not write depth. Interpenetrating transparent geometry may need author splitting; exact order-independent transparency is not promised. Honor doubleSided with reversed back-face lighting normals, and KHR_materials_emissive_strength as an HDR multiplier before bloom and exposure. The M1 irradiance/color-space contract remains unchanged. M2 fixtures make alpha sorting/masking, fog camera translation, sky exclusion, roughness reflections, HDR bloom and app-color preservation independently observable.

The optional com.hyprune.lumen-reach.routes version 1 adapter accepts at most 64 nodes:{id,position} and 256 edges:{from,to,width}. Node positions are capsule feet in metres; runtime places and path points add the 1.7 m eye offset. Edges are bidirectional, reference distinct declared nodes, and have width 0.6–100 m. Repeated undirected edges are invalid. Core does not infer stairs; authored ramp vertices and landings must remain explicit in the graph. A one-destination route.set pointing at a declared node expands through the shortest graph path from the nearest node to the current camera. Multi-point routes retain caller-specified paths. The connector to the first node and every path segment still use the capsule solver: an obstruction stops autodrive. Disconnected declared destinations are rejected. Arbitrary off-graph targets retain explicit direct-route behavior while that leg is clear (see off-graph routes round obstructions). The legacy route namespace keeps its existing place-only behavior.

Amendment: climbable volumes, world format 0.4

Section titled “Amendment: climbable volumes, world format 0.4”

World formatVersion: "0.4" uses schema/v0.4/world.schema.json and adds optional climbables (at most 128). Earlier formats remain frozen and do not accept this field. The new format retains every 0.3 field and its semantics.

{
"id": "hatch-ladder", "type": "ladder",
"bottom": [0, 0, 0.55], "top": [0, 6, 0.55],
"facing": [0, 0, 1], "width": 1.4, "depth": 0.8,
"exits": {"bottom": [0, 0, 1.55], "top": [0, 6, -0.85]},
"speed": 2
}

bottom and top define the world-space capsule feet rail, in metres. Their normalized difference is the prism’s longitudinal axis. facing is the unit outward climb-face normal, perpendicular to that axis within 0.001; cross(axis, facing) is the lateral axis. width (0.6–32 m) and depth (0.1–2 m) are full dimensions, centered on the rail. The segment must ascend, be 0.5–100 m long and have normalized Y at least 0.25. This oriented segment representation covers ladders, inclined ladders and broad climbable walls; no quaternion or glTF node transform is applied again.

id is a stable unique slug. type is ladder, rope, vines or chain-link; all share the same controller. Optional speed is metres per second along the rail, 0.1–8, default 2. exits.top and exits.bottom are standing capsule feet positions, each within 3 m of its corresponding endpoint. All fields except speed are required. Unknown properties, duplicate IDs, nonfinite values, degenerate/descending segments, invalid normals and remote exits reject loading.

The rail must put the entire upright 0.3 m radius capsule clear of visible and collision ladder geometry; position rungs behind it (the fixture uses 0.52 m). Core checks standing capsules at both rail ends and exits during load. Runtime sweeps every connector, lateral movement and exit against static collision; an obstructed rail/exit holds the last safe position. Endpoints are not a permission to teleport through a hatch rim. Author unobstructed connectors and landings, and a catch prism spanning the intended drop-in opening. Visual meshes remain ordinary original/licensed glTF content and are never inferred to be climbable. Procedural fixture core/tests/fixtures/climbing.py is original CC0.

Amendment: world 0.6 playable bounds and backdrop validation

Section titled “Amendment: world 0.6 playable bounds and backdrop validation”

World format 0.6 adds optional gameplay bounds. Earlier versions remain valid and have unrestricted flight unless their collision geometry blocks it. Coordinates are world metres, +Y up. Bounds apply to the camera eye, not the player’s feet or the camera frustum.

{
"playable": {
"volumes": [
{"type": "box", "min": [-40, -2, -40], "max": [40, 30, 40]},
{"type": "convex", "points": [[40, 0, 0], [50, 0, 0], [40, 15, 0], [40, 0, 15]]}
],
"maxFlyHeight": 24
},
"backdrop": {"farCards": [12, 15]}
}

playable.volumes is a union. A box requires strictly increasing min/max on all axes; a convex hull takes 4–16 distinct points spanning nonzero volume. Coordinates and heights range from −100000 to +100000 m. Each declaration has at most eight volumes. maxFlyHeight is an absolute world-space eye Y and clips all volumes in that declaration. A world declaration can contain only a height cap; an area declaration must include volumes.

An existing areas[] entry can also contain playable with the same shape. All declared area regions form a union (at most 64 area volumes in total), intersected with the world envelope if present. This permits movement between adjacent/overlapping rooms without switching bounds based on a nearest-area heuristic. Undeclared areas add no constraints or implicit volumes. Authors must cover intended connecting passages and keep the world/area intersection nonempty. These volumes describe permitted flight, independently of visibility culling and window placement zones.

Core enforces bounds only during ordinary fly movement. The live Lua option player.fly_bounds_allowance expands every boundary plane, including height caps, by 0.5 m by default, range 0–20 m. In the final metre, outward movement slows smoothly; it cannot cross the expanded boundary or jump gaps between disconnected regions. Tangential movement remains possible. Enabling fly while already outside returns toward the nearest permitted region at up to 3 m/s without teleporting. Walking, climbing, collision, scripted travel and the capability-gated authoring camera retain their existing semantics.

Noclip ignores both bounds and fall respawn. On crossing outside the authored (unexpanded) bounds, core emits the existing runtime.notice event with level: "warning", code: "world.bounds.left", and message “Leaving world bounds · noclip is unbounded”. It emits once per outward crossing, including enabling noclip outside, and resets on world load. Shells show this through their existing notice UI. No IPC version bump or cursor transition is needed; authoring bounds are omitted from IPC area records.

backdrop.farCards explicitly identifies up to 256 glTF node indices, including rendered descendants, used as distant sky/backdrop cards. The authoritative hyprune-world-check PACKAGE validates indices and warns if a texture sampled by those meshes uses CLAMP_TO_EDGE (33071) on S or T. Warnings name the node, texture index and axes, appear on stderr and in the JSON warnings array, and do not fail validation. REPEAT/MIRRORED_REPEAT and undeclared meshes are silent. This is a diagnostic, not an instruction to change wrapping automatically; clamping can be intentional. Cubemap/environment faces are not far cards.

Amendment: world 0.7 compressed and optimised assets

Section titled “Amendment: world 0.7 compressed and optimised assets”

World format 0.7 lets packages ship GPU-ready textures and compressed geometry in scene.gltf, using standard Khronos/vendor glTF extensions. The world.json shape is unchanged from 0.6 except formatVersion: "0.7". Every valid 0.6 document is valid as 0.7 (the inheritance rule); older formats remain frozen and must not use these extensions.

glTF extension Allowed in 0.7 Rules
KHR_texture_basisu Material textures KTX2 images (image/ktx2), 2D, one layer and face, LDR, Basis ETC1S or UASTC 4×4, optional Zstandard supercompression. Ship the full mip chain in the file: block-compressed textures cannot be mip-mapped at load. Colour slots (base colour, emissive) are sRGB-encoded; data slots (normal, metallic-roughness, occlusion) are linear. A PNG source fallback is optional.
EXT_meshopt_compression All geometry Any mode and filter. The uncompressed fallback buffer may be omitted (fallback: true, no URI).
KHR_mesh_quantization All geometry Quantised attributes are dequantised through the node transform, as glTF specifies. Use at least 14-bit positions (16 recommended) so collision and walking keep their tolerances, and 16-bit TEXCOORD_1: it addresses lightmap texels.

A 0.7 package must list each extension it relies on in extensionsRequired, so an older core rejects it before activation instead of rendering it wrong. Core rejects these extensions for formatVersion below 0.7.

Runtime behaviour (normative for core): KTX2 images are transcoded on the loader thread to a block format the GPU advertises and can sample as sRGB, in the order BC7, BC1/BC3, ASTC 4×4, else RGBA8. ETC2 is skipped because desktop drivers often emulate it. Meshopt buffer views are decoded on the loader. World GPU budgets count the transcoded size. hyprune-world-check has no GPU, so it reports the RGBA worst case.

Lightmaps stay PNG in 0.7. A lightmap texture referenced from lightmaps[] must not use KHR_texture_basisu. Reasons:

  • v0 lightmaps are 8-bit irradiance multiplied by an authored intensity (up to ~30 in shipped worlds), so block-compression error is amplified into visible banding and blocking on large flat surfaces.
  • A KTX2 file carries its own mip chain, which bypasses the gutter-safe mip cap the bake pipeline relies on (two levels for 4 px gutters; some groups, such as dense foliage, allow none).
  • HDR irradiance (UASTC HDR, BC6H) needs its own encoding contract, which v0 already defers to a future version.

A later amendment can allow KTX2 lightmaps with a declared safe mip count and an HDR encoding. Lightmaps are now the largest remaining GPU cost (Lumen Reach: about 149 MiB in total after converting its material textures).

Two pitfalls when adding standard optimisers to a world build:

  1. Keep lightmap textures. world.json’s lightmaps[].texture is the only reference to lightmap textures; no glTF material uses them. glTF-Transform (meshopt, prune, most commands) drops textures that no material references and rebuilds the texture array. Re-append the lightmap textures at their original indices afterwards, or put them last and verify the indices, or encode material textures with basisu/ktx and add KHR_texture_basisu in place without rewriting the array.
  2. Keep node and material indices. world.json refers to glTF node indices (spawns[].node, anchors[].node, navigation.node, collision[].node, visibility area nodes, backdrop.farCards) and material indices (lightmaps[].material). gltfpack merges and renumbers nodes, meshes and materials (even with -kn -km), so it is unsuitable for world packages unless the build remaps every reference. glTF-Transform meshopt preserved node and material order in the core test conversion, but reordered material textures. That is harmless because materials are rewritten consistently. Builds should assert node/material names and order before and after, and run hyprune-world-check.

Measured on a converted copy of Lumen Reach 0.7.0 (core docs/PERF-2026-10.md): package 72 → 42 MiB, GPU memory 270 → 149 MiB, upload 209 → 127 MiB, visually indistinguishable (PSNR 37–39 dB).

The schema is 0.7. The shared validator also checks scene.gltf’s extensionsRequired and lightmap textures against the world’s formatVersion (validate('scene', gltf, undefined, worldVersion, {world})).

Amendment: blueprint map levels, com.hyprune.blueprint 0.1 (IPC 0.20)

Section titled “Amendment: blueprint map levels, com.hyprune.blueprint 0.1 (IPC 0.20)”

The map should read as a plan of the place, not just its paths. A package that carries com.hyprune.map 0.1 may also carry the optional extension com.hyprune.blueprint version 0.1:

"com.hyprune.blueprint": {"version": "0.1", "levels": [
{"id": "ground", "name": "Ground", "minY": -2, "maxY": 4.5, "path": "blueprint/ground.svg"},
{"id": "upper", "name": "Upper decks", "minY": 4.5, "maxY": 40, "path": "blueprint/upper.svg"}]}
  • levels holds 1–6 entries sorted by minY. Each id is a slug ([a-z][a-z0-9-]{0,31}, unique) and each name has 1–64 characters. A level shows the band of feet heights minY ≤ y < maxY, so minY < maxY and bands do not overlap.
  • Each path is a package-relative safe path to an SVG drawn in the map’s frame: the same viewBox, with worldToMap mapping world XZ onto it.
  • Each SVG is at most 64 KiB, and all levels together at most 256 KiB.
  • The SVGs use the map SVG subset (RFC-0008), plus a class attribute naming a drawing role: grid floor wall stair opening screen mount area label route waypoint void outline. Elements with a role and no fill/stroke take the consumer’s theme colours for that role. Other elements keep their own colours.
  • The drawing is a top-down technical plan of the level with north at −Z:
    • walkable floor;
    • wall outlines from collision;
    • stairs and ramps with treads, doors and openings;
    • mounted-workspace screens with their facing side, tool and data mounts;
    • area outlines and names;
    • the walking routes and waypoints;
    • a drawing grid and title block.
  • A blueprint without com.hyprune.map is an error. Cores that predate IPC 0.20 ignore the extension, so packages that carry it load everywhere.
  • Core validates the levels and publishes them to IPC 0.20 clients as spatial.map.levels ({id, name, minY, maxY, svg, sha256}). The reference shell draws them in the Director’s Map with level switching, pan and zoom.
  • Worlds generate them at build time from collision, the navmesh, areas, anchors and routes: worlds/tools/derive-blueprint.py.

The value’s shape is extensions/blueprint.schema.json. Ordering, byte budgets and the role vocabulary are enforced by core and the worlds checker.

World format 0.8 lets a world place objects: reusable glTF assets (an armillary, a lantern, a buoy) put into the world by reference with a transform, optionally with simple declarative animation. The world stays static otherwise. Two optional top-level fields are added; everything else is unchanged from 0.7 except formatVersion: "0.8". Every valid 0.7 document is valid as 0.8 (the inheritance rule); older formats remain frozen and reject both fields. glTF animations in any glTF of the package remain ignored.

"objectAssets": [
{"id": "armillary", "scene": "objects/armillary.gltf",
"animations": [
{"node": "ring-equator", "type": "spin", "axis": [1, 0, 0], "pivot": [0, 0, 0], "period": 20},
{"node": "ring-tilted", "type": "spin", "axis": [-0.955, 0, 0.295], "pivot": [0, 0, 0], "period": 27, "phase": 0.3},
{"node": "moon", "type": "orbit", "axis": [0, 1, 0], "pivot": [0, 0, 0], "period": 60},
{"node": "buoy", "type": "bob", "axis": [0, 1, 0], "amplitude": 0.05, "period": 4}
],
"collision": {"node": "proxy"},
"lighting": {"mode": "probe"}}
],
"objects": [
{"id": "sun-court-armillary", "asset": "armillary",
"pose": {"position": [4, 0, -6], "rotation": [0, 0.383, 0, 0.924]}, "scale": 1,
"speed": 1, "phase": 0, "ambient": [0.3, 0.28, 0.25]}
]
Field Rules
id Required slug, unique among assets.
scene Package-relative .gltf/.glb path, validated like scene.gltf with the same glTF extension rules for the world’s format (0.7’s KTX2/meshopt/quantisation included).
library Reserved for a later shared object library ("id@version"). Validators and core reject it in 0.8, so a later format can add libraries without breaking 0.8 packages.
animations Optional, at most 16, see below.
collision Optional {"node": name}: a static collision proxy.
lighting Optional {"mode": "probe" | "unlit"}, default probe.

At most 32 assets. An asset’s asset space is its glTF scene’s root space (metres, +Y up); node transforms are applied as in scene.gltf. Only nodes in the asset’s scene graph are drawn. Nodes are referenced by glTF node name; a referenced name must belong to exactly one node of the asset.

Assets are never lightmapped: lightmaps[] binds scene.gltf materials only, and an asset’s TEXCOORD_1 is unused. Materials are ordinary metallic-roughness PBR or KHR_materials_unlit; an occlusionTexture is treated as baked object-space ambient occlusion.

Each animation moves a node and its whole subtree rigidly in asset space. At most one animation per node, and no animated node may lie inside another animated subtree (no target is an ancestor of another).

Field Rules
node Required node name.
type spin: rotate the subtree about the line through pivot along axis; its orientation turns with it. orbit: carry the subtree around that line keeping its orientation (translation only; the node’s origin travels on the circle), so an armillary ring can turn on its own axis while a moon circles the centre. bob: translate along axis by amplitude·sin(angle).
axis Required unit vector in asset space (length within 0.001 of 1; core normalises it). Right-hand rule: a positive angle is counter-clockwise looking down the axis toward the pivot.
pivot Point on the axis line, asset space, metres. Required for spin and orbit; not allowed for bob.
amplitude Metres, 0 < amplitude ≤ 10. Required for bob; not allowed otherwise.
period Required seconds per cycle, 0.5–3600.
phase Optional fraction of a cycle, 0 ≤ phase < 1, default 0.

The angle at time t is 2π·(t·speed/period + phase + instance phase). t is a monotonic world-animation clock that starts when the world loads and follows wall-clock time: an object is always at its natural periodic position and never jumps when frames resume. Poses are computed from the authored (rest) pose, which is the pose at t = 0 when both phases are 0.

Field Rules
id Required slug, unique among objects.
asset Required, an objectAssets[].id.
pose Required world position and unit-quaternion rotation (normalised within 0.002).
scale Uniform, 0.01–100, default 1.
speed Animation rate multiplier, 0–10, default 1 (0 holds the t = 0 pose).
phase Added to every animation’s phase, 0 ≤ phase < 1, default 0: repeated objects need not move in step.
ambient Optional linear RGB (0–16 each) replacing the probe’s ambient term (below).

At most 256 objects. An object’s model is translation · rotation · scale; the animation model applies in asset space before it.

Objects are render-only: they never collide, are never walkable, are never a pick or aim target, and no gesture, tool or editor transform can select or move them. The only exception is the asset’s optional collision proxy: the named node’s own mesh (not its children) becomes static collision at each instance’s pose. The proxy never moves; it must have a mesh and must not lie in an animated subtree. It is drawn only if it is part of the asset’s scene graph (keep a hidden proxy outside the scene’s node list). Proxy triangles of every instance count toward the world’s static collision budget (20000 triangles), and spawns and climbable endpoints are validated against them.

unlit assets are drawn as authored (base colour and emission, no lighting). probe assets (the default) are lit by the runtime sun plus a per-instance ambient probe that core derives at load from the world’s static lighting:

  1. From the centre of the instance’s swept bounds, 64 rays (an even Fibonacci sphere) are cast up to 100 m against the world’s rendered static geometry.
  2. A ray that hits a lightmapped surface takes that surface’s albedo (base colour factor times the average of its base colour texture) times the baked irradiance at the hit (lightmap texel, encoding and intensity applied); an unbaked surface gives albedo × (0.24 + 0.76·max(n·sun, 0)), the world shader’s unbaked lighting; an unlit surface its albedo; emission is added. A ray that misses takes the sky gradient (horizon to zenith above, horizon to ground below).
  3. Cosine-weighted averages over the upper and lower hemispheres give ambient up and ambient down; a fragment uses their mix by its normal’s Y.
  4. Direct sun = sun colour (normalised to luminance 1) × strength × visibility × max(N·L, 0). Visibility is the fraction of five shadow rays toward the sun (the centre, and ±min(radius/2, 1 m) along X and Z) that reach the sky. Strength is calibrated from the baked surfaces the probe saw: with at least four sunlit and four shaded hits whose mean baked luminance differs by more than 5%, (sunlit − shaded) ÷ mean cosine; else, with four sunlit hits, 0.76 × sunlit ÷ mean cosine; else 0.76 (the unbaked convention); clamped to 0–16. Specular highlights are scaled by the visibility.
  5. The asset’s occlusion texture multiplies the result. An instance’s ambient replaces both hemisphere terms; the sun term stays.

This is deliberately simple: objects pick up the colour and level of the baked light around them, darken under cover and keep a moving sun highlight, without per-object bakes. Authors fix the rare bad probe with ambient.

  • Each asset is uploaded once and counts once toward the world GPU budget, however many objects place it. Repeated objects are drawn instanced: one draw per asset primitive for all its visible instances (blended materials per instance, depth-sorted with other transparent geometry).
  • Culling uses each instance’s swept bounds: a sphere about the asset’s rest-pose box centre that holds the asset at every animation pose, scaled and placed by the instance. An object shares the visibility of the static geometry around it: the visibility areas owning scene.gltf meshes whose bounds the sphere overlaps. It is region-visible while any of them is; with none it is culled by the frustum only. (Correction, 2026-10-11: the first text placed an object in the first area whose bounds contained its centre. Derived regions are camera cells that own no nodes and are visible from no other cell, so an object in one was drawn only with the camera in that cell.)
  • Render on demand. While an animated object (speed > 0) is visible and the world view is active, core keeps scheduling frames at the normal target frame rate. When none is visible, or the world view is inactive or idle (desktop, output off, still loading), objects force no frames and an unchanged frame is reused.
  • graphics.reduced_motion: true stops animation: every object rests at its t = 0 pose (asset and instance phases applied) and forces no frames.
  • The ink outline, depth and occlusion of native windows work on objects as on static geometry. Render-pass safety rules apply: nothing that makes the compositor render is called inside the render pass, and GL state is saved and restored.
  • The optional offload renderer (RFC-0009) draws world objects with the same results as the in-process renderer: the same animation clock, instanced path, lighting and culling, including catalog placements and editor changes (see the RFC-0009 world objects amendment). Until that amendment a world with objects used the in-process renderer, with the reason “world objects use local renderer”.

Schema, the shared validator, core and hyprune-world-check reject: objects or assets below 0.8; unknown properties; more than 32 assets, 256 objects or 16 animations per asset; duplicate asset or object ids; an unknown asset; a library reference; a non-unit axis; a spin/orbit without pivot or with amplitude, a bob the other way round; two animations on one node; a node name that is missing or not unique in the asset; an animated node inside another animated subtree; a collision node that is animated, inside an animated subtree or has no mesh; an asset glTF extension the format forbids; a proxy that obstructs a spawn (core and hyprune-world-check only: it needs collision). The scene-dependent asset rules are in validate('scene', assetGltf, undefined, '0.8', {world, asset: id}). hyprune-world-check lists each asset (swept radius, animation and triangle counts) and each object’s probe result.

No IPC change. The schema is 0.8.

Amendment: world 0.9 characters, paths, seats and keepClear

Section titled “Amendment: world 0.9 characters, paths, seats and keepClear”

World format 0.9 is the format half of RFC-0011’s P2: object assets gain sources and traits, an instance can be a character walking a route or standing on a spot, and the manifest gains paths, seats and keep-clear volumes. Every valid 0.8 document is valid as 0.9 apart from formatVersion: "0.9" (the inheritance rule); 0.8 and older formats remain frozen and reject every field below. What the fields mean (traits, segment geometry, walkability, sitting, interactions, protection) is normative in RFC-0011 and, for characters, RFC-0010; this amendment records the format delta and where each rule is checked. The IPC side is IPC 0.23 (RFC-0011 P2 amendment).

"objectAssets": [
{"id": "resident", "dir": "characters/resident-blue"},
{"id": "porter", "library": "com.hyprune.starter@0.1.0", "object": "porter"},
{"id": "court-bench", "scene": "objects/bench.glb", "collision": {"node": "proxy"},
"traits": {"movable": {}, "seat": {"capacity": 2, "anchors": [
{"id": "left", "position": [-0.4, 0, 0.55], "yaw": 0, "height": 0.45},
{"id": "right", "position": [0.4, 0, 0.55], "yaw": 0, "height": 0.45}]}}}
],
"objects": [
{"id": "bench-east", "asset": "court-bench", "locked": true,
"pose": {"position": [3.6, 0, -2], "rotation": [0, -0.7071068, 0, 0.7071068]}},
{"id": "porter-1", "asset": "porter", "path": "court-loop", "phase": 0.25, "accent": [0.9, 0.5, 0.1],
"interactions": [{"id": "where", "label": "Where is work?", "prompt": "Mark it",
"action": {"type": "waypoint", "target": {"zoneId": "work"}}}]},
{"id": "reader", "asset": "resident", "seat": "fountain-ledge",
"pose": {"position": [1.5, 0, 1.8], "rotation": [0, 1, 0, 0]}}
],
"paths": [
{"id": "court-loop", "use": "route", "closed": true, "speed": 1.1,
"points": [{"position": [-3.5, 0, 3], "type": "line"}, {"position": [-3.5, 0, -2], "type": "line"},
{"position": [3, 0, -2], "type": "curve"}, {"position": [3, 0, 3], "type": "arc"}],
"stops": [{"point": 1, "seconds": 3, "clip": "look_around"},
{"point": 2, "seconds": 20, "seat": "bench-east/left"},
{"point": 3, "seconds": 4, "face": {"anchor": "desk"}}]}
],
"seats": [{"id": "fountain-ledge", "height": 0.5,
"pose": {"position": [1.5, 0, 1.2], "rotation": [0, 1, 0, 0]}}],
"keepClear": [{"id": "north-door", "min": [-0.8, 0, -4.2], "max": [0.8, 2.4, -3.6]}]

The complete synthetic manifest is the schema repository’s examples/world-npcs.json.

Field 0.9 delta
objectAssets[] Still at most 32, ids unique; each has exactly one source. Inline {id, scene, animations?, collision?, lighting?, traits?, slots?}: the 0.8 asset plus the object manifest’s 0.9 traits and slots (decorative, collidable, movable, character and seat allowed; mover, mount, machine and interactive rejected). animations is shorthand for traits.decorative.animations and collision for traits.collidable; giving both forms of one is invalid. Directory {id, dir}: a package-relative directory (the common path rules, no trailing slash) holding an object.json whose formatVersion is at most the world’s, and its scene. Library {id, library, object}: library is <reverse-domain id>@<semver> (the pattern 0.8 reserved), object an object id (slug). Directory and library assets take no other fields. Trait combinations follow RFC-0011 (a character combines with nothing).
objects[] Still at most 256, of which at most 16 character instances. Adds path (a route path id; replaces pose), reverse (only with path: start walking towards decreasing arc length), seat (a seats[] id, <objectId>/<anchorId> or <objectId> for any free anchor; only characters without a path, which sit there permanently), accent (linear RGB 0-1; characters), interactions (1-8, characters; replaces the asset’s list) and locked (movable assets). pose is required unless path is set and forbidden with it; for an unbound character it is the standing spot. On a character, speed (0-10, default 1) scales pace and clip rate, phase is the start fraction of the route’s length, and scale must be 1.
Interactions {id, label (1-32), prompt? (1-64), action}, ids unique per list. Actions: say {lines} (1-8 lines of 1-160 printable characters), waypoint {target} ({zoneId}, {position}, {anchor} or {object}), guide {path} (a route), panel {panel} (a shell panel id). travel and quest are reserved and rejected in 0.9. Asset-level interactions (in object.json) stay say and panel only.
paths[] New. At most 64 paths and 1,024 points in total: {id, name? (1-64), use? (route, track or generic; default generic), closed? (default false), points (2-256 {position, type: line, curve or arc}), speed? (0.1-30 m/s), stops? (at most 32)}. A stop is {point, seconds? (0.5-600, default 3), clip? (look_around, wave, nod, idle_fidget), face? ({position}, {anchor} or {object}), seat?} with at most one of clip, face and seat, one stop per point and point below the point count. Track stops take only point and seconds (source, sink and items wait for 0.10); generic paths have no stops. At most 8 characters per path.
seats[] New. At most 64 world-space seat anchors {id, pose, height (0.2-1 m), use? (["sit"]), approach? (0.3-2 m, default 0.6)}; pose is where the sitter’s root stands at the start of sit, facing the pose’s +Z.
keepClear[] New. At most 64 boxes {id, min, max}, min below max on every axis: volumes objects may not block (placement rule 6) and route stops and seat approaches avoid.

Segment geometry is RFC-0011’s: line straight; curve a cubic Hermite with start tangent (b − previous point) / 2 and end tangent b − a; arc the straight line plus a horizontal offset of 0.3·|b − a|·sin(πt) towards (b − a) × +Y. An arc whose horizontal chord is under 0.1 m is invalid. Core and tooling sample 24 steps per segment.

Where Checks
Schema (v0.9/world.schema.json) Shapes, ranges and closed objects; exactly one asset source; the list limits (32 assets, 256 objects, 64 paths of 2-256 points, 32 stops, 8 interactions, 64 seats, 64 keep-clear boxes); the interaction action vocabulary (travel, quest rejected); at most one of clip, face and seat per stop; track stops with point and seconds only; no stops on generic paths.
Shared validator (validate('world', manifest, undefined, '0.9', {assets})) Unique ids per list; asset references; one form of animations and collision; trait combinations, with reserved traits and actions named plainly; objects[].path and guide paths exist and are routes; seat references (a world seat id, else an object id; whether the object is a seat and has the named anchor is checked when its asset is inline or its object.json is supplied in options.assets[assetId]); stop seat and facing references; waypoint zone, anchor and object references; character-only fields (path, seat, accent, interactions) on assets known not to be characters; locked only on movable assets; pose/path exclusivity, reverse only with a path, no seat with a path; a character’s scale of 1; normalised seat rotations; arc chords; the 1,024-point total; one stop per point below the point count; keep-clear ordering; 16 character instances (when the assets are known) and 8 per path. validate('scene', gltf, undefined, '0.9', {world, asset}) reads an inline asset’s animations and proxy from either form and checks an inline character’s skin and clips.
Core and hyprune-world-check Directory and library resolution (a library is resolved exactly against the installed id@version; a missing one fails activation with runtime.notice world.library.missing naming it, and the previous scene stays); the object checks of every referenced object; the character spec (hyprune-npc-check’s rules) for every character asset; route walkability; seat reachability, including the approach legs; stops and seat approaches outside keepClear volumes.
hyprune-world-check only With navigation data, route samples on the default spawn’s navmesh island; the release gate’s 1.2 m door width along routes.

Walkability (core and hyprune-world-check): every 0.25 m along the curve there is an upward-facing collision surface (normal Y at least 0.65) under the sample within 0.35 m of the previous sample’s floor; the character’s capsule (its radius and height, default 0.35 m and 1.8 m) is clear of collision; the sample lies inside the playable union when the world declares one; and no segment passes through an approach zone. Seat approach legs (route point to approach point to anchor) are checked the same way. Problems are reported with the sample’s position.

  • 0.8 and older packages load unchanged; their assets carry no traits, so they stay render-only and unpickable. A 0.9 world declares movable (and locked) itself.
  • A core that does not support 0.9 rejects a 0.9 package (exact versions), so a world that references library objects never loads half-resolved.
  • RFC-0010’s draft fields (kind: "character", an inline route) never shipped and are replaced by the trait and path, not migrated.
  • Object and library manifests are unchanged (object.json 0.9, draft 0.10). An object used by a 0.9 world must have formatVersion 0.9.
  • v0.9/common.schema.json is the 0.8 common definitions under the 0.9 $id; the directory’s IPC 0.9, input, object and library schemas are untouched.
  • Loading a 0.9 world needs no IPC change. Characters, paths and interactions over IPC are IPC 0.23; older peers keep their frozen shapes.

The schema is 0.9.

Amendment: off-graph routes round obstructions (core 0.8.1)

Section titled “Amendment: off-graph routes round obstructions (core 0.8.1)”

No format or wire change. A one-destination route.set whose target is not a declared node (an arbitrary position, or a zone’s destination point) and whose straight leg from the camera is blocked by collision follows the walking graph instead: the shortest graph path from the node nearest the camera to the node nearest the target, then the target. The last route entry keeps the caller’s target. A clear straight leg keeps the direct route above, and worlds without a walking graph are unchanged. A target the graph can’t reach keeps the direct route. The drawn route line lies on the ground under each leg.

World format 0.5 (optional ink outline style and authored visibility regions) is specified in RFC-0005. World formats 0.8 and 0.9 are the amendments above. World format 0.11 (panorama skies and object format 0.11 directory assets; it follows 0.9, there is no world format 0.10) is specified in RFC-0014’s builder world amendment. The world manifest reference lists every format version with its diff and the amendment that introduced it.