The HSD scene model
HSD (Hyper-Space Document) is the scene format of The Wired. An HSD document contains objects along with their geometry, materials, physics, and scripts.
Each document is stored as an iroh-docs namespace, which handles signing and sync between peers. HSD defines what the entries in it mean.
Prims and properties
A document is a tree of prims. A prim is only an id. Everything about it, including its place in the tree, is a property attached to it.
As in USD (Universal Scene Description), properties come in two kinds.
- An attribute stores data directly, such as a transform, a mesh, or a collider.
- A relationship points at another prim in the same document, such as a texture to sample.
The built-in properties are listed in wired:scene.
Prim ids
A prim keeps its id through every edit. Moving, renaming, or changing its mesh leaves anything pointing at it intact.
The compiler derives an authored prim's id from its source file's path and its place in the tree. Rebuilding the same source gives the same ids on every peer. A prim a script creates at runtime gets a fresh id instead.
Layers
A property's value is stacked from several layers. The strongest layer with a value wins.
| Layer | In wired:scene | Stores | Lasts |
|---|---|---|---|
| Session, one per peer | shared | What that peer in the space states | Until that peer leaves |
| Runtime | local | This peer's own writes | Until the document unloads |
| Override | Edits from a document that references this one | As long as that document does | |
| Document | The document's own entries | Durably |
Each person in the space has their own session layer on each document. The author's is the strongest, and the others sit below it, ordered by how far you trust each person. Your peer also decides what each of those layers may change. The author's can set anything, while anyone else's is limited to script state and portal pairing, as Trust and permissions explains. When someone leaves, their layers go with them. If you trust them at Guest or above, your peer first copies what they stated into your own session layer and shares it, so their changes outlive them for everyone you reach. The documents they brought stay loaded for the same reason, and a document from someone you don't trust that far unloads when they go.
A script's writes land in local and cost nothing, since only this peer sees them.
Calling commit makes a value durable in the document.
commit only takes effect on the peer that authored the script's document.
Every other peer runs the same script, and their commits do nothing, so the value is written once.
References
A prim can include another document with a reference attribute pointing at that document's id.
This is how a scene reuses an object, like a couch placed in a room.
The referencing document can change things inside the one it references without editing it, such as recoloring the couch. Those changes go into the referenced document's override layer.
Concurrent edits
Several peers can edit the same document at once. iroh-docs settles each key by taking the latest write, so every peer that has seen the same entries ends up with the same tree.
Entries can arrive out of order. A prim whose parent hasn't arrived yet waits for it, and a loop of parents is broken in the same place on every peer.