Gargantis

Bounding Volume Hierarchy

Mon, 01 Jan 0001 00:00:00 +0000

A Bounding Volume Hierarchy (BVH) is a tree of nested bounding volumes over a set of geometry. Each leaf holds primitives; each interior node holds a volume enclosing all of its children. A query — “what does this ray hit?”, “what is inside this box?” — descends from the root and prunes any subtree whose volume already fails the test, so cost scales with the answer rather than with the size of the world.

Game Loop

Mon, 01 Jan 0001 00:00:00 +0000

A game loop is the simulation step of a realm — a realm is, by definition, the region served by a single one. Each iteration turns the realm’s input streams into its output streams:

Record the current position of every input stream, so the whole iteration reads a consistent snapshot of its inputs.
Run AI.
Move objects.
Generate sounds.
Compute output deltas and append them to the output streams.
Repeat.

Why the shape matters#

Reading inputs at a recorded stream position, and emitting deltas appended to a stream, is what makes the loop a state machine over the log: two nodes that begin in the same state and consume the same inputs in the same order end in the same state. That is the property the peer-to-peer network leans on in place of an authoritative server — convergence follows from determinism rather than from anyone being in charge.

Gargantis Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Gargantis is a protocol, realised as a pure peer-to-peer network of homogeneous browser nodes. There is no central server: every node runs essentially the same software and is ephemeral — any node may leave at any time, and the architecture assumes this. A node that happens to stay online continuously can improve availability and discovery for others, but it is not privileged and must not be depended on — the architecture must hold with none. Data is kept across the ephemeral swarm by redundancy (erasure coding) and continuous repair; durability is probabilistic, and some loss is accepted by design (see Peer-to-Peer Network).

Gargantis Scout

Mon, 01 Jan 0001 00:00:00 +0000

Gargantis Scout is the browser-based explorer for the Gargantisphere: the JavaScript application that lets a person enter the network, render realms with WebGL, and travel between them through portals. It runs in any modern web browser — the browser is the platform, so there is no separate console or desktop client (the legacy “Steam”/native-client clients are not part of the protocol vision).

Scout is itself an ordinary node: it joins the peer-to-peer network via Helia / IPFS, subscribes to the visible parts of a realm via the Scene Composition Protocol, and represents the visitor with a persona. “Exploring with Scout” and “being a peer” are the same act.

Gargantisphere

Mon, 01 Jan 0001 00:00:00 +0000

The Gargantisphere is the universe of all Gargantis realms and the portals that connect them — the whole interconnected space the peer-to-peer network of nodes renders and maintains.

It is analogous to the World Wide Web: just as the Web is the universe of hyperlinked pages, the Gargantisphere is the universe of portal-linked realms. A visitor can travel seamlessly between realms — potentially with different physics, avatars, and authoring — exploring and discovering as they go, without ever contacting a central server.

Gargontology

Mon, 01 Jan 0001 00:00:00 +0000

The Gargontology is the ontology, or abstract schema, underlying the Scene Composition Protocol of the Gargantisphere. It names the classes and properties a scene is built from, so that independently-authored realms and independently-written nodes mean the same thing by “mesh” or “rotation”.

List of classes#

Vertex
Line
Curve
Polygon
Mesh
Image
Affine Transform
Rotation

Why an ontology rather than a fixed schema#

JSON-3D extends JSON-LD, and the Gargontology is the vocabulary its @context points at. That buys two things a fixed struct definition does not, both of which matter here specifically.

Helia and IPFS

Mon, 01 Jan 0001 00:00:00 +0000

Helia is the modern JavaScript implementation of IPFS (the InterPlanetary File System). It is a core building block of Gargantis: it provides content-addressed storage and the libp2p networking stack that the peer-to-peer network is built on, entirely inside the browser node.

Role in Gargantis#

Content addressing. Scene assets and JSON-3D documents are identified by cryptographic hash (CID). Any peer holding a CID can serve it, so there is no origin server (this replaces the legacy AWS S3/CloudFront origin entirely).
Transport & discovery. libp2p (bundled with Helia) handles peer discovery, connection, NAT traversal, and pubsub — the substrate for per-realm and per-stream topics.
Data plane for streams. The Web Stream Message Protocol and its log semantics ride on libp2p pubsub plus content-addressed blocks for replay.

Deployment#

The Hugo documentation site is deployable to IPFS as well as Cloudflare Workers, so the docs themselves can be served by the same content-addressed fabric as the protocol.

JSON-3D

Mon, 01 Jan 0001 00:00:00 +0000

JSON-3D is the JSON format for exchanging virtual-reality scenes and events between nodes. It is an extension of JSON-LD, so a document carries its own vocabulary context and can be read as linked data; the classes and properties that vocabulary names are the Gargontology. It borrows concepts from, but is not compatible with, GeoJSON.

JSON-3D is what the Scene Composition Protocol puts on the wire: the scene hierarchy with its transforms and meshes as structure, plus the events and value updates that flow over structural and parameter streams.

Mesh

Mon, 01 Jan 0001 00:00:00 +0000

A mesh is a graphical object that represents a surface as a two-dimensional web-like network of interconnected vertices, lines, and triangles. It is how a realm’s geometry reaches the GPU: triangles are what WebGL rasterises, so any richer surface is reduced to them before it is drawn.

A mesh sits in the scene hierarchy beneath a transform that places it. Its geometry is bulk data — large, immutable, and typically reused across many placements — which makes it the part of a scene that content addressing suits best: a mesh is fetched once by hash from any peer holding it via Helia / IPFS and instanced wherever it is needed, rather than travelling in the parameter stream alongside values that change every frame. Structure and bulk move on different terms; see Structural Stream.

Node

Mon, 01 Jan 0001 00:00:00 +0000

A node is a single participant in the Gargantis peer-to-peer network. Nodes are homogeneous: every node runs essentially the same software, in the browser, using JavaScript for logic and WebGL for rendering and GPU computation.

There is no client/server split. A node that renders a scene for a user and a node run headless as an always-on peer are the same software in different configurations. Every node is ephemeral — including the always-on one, which may still vanish at any time; the protocol assumes this and must never depend on any node persisting. An always-on configuration is not privileged: it merely improves availability and discovery for others at the margin, while the network stays correct with none.

Open Problems

Mon, 01 Jan 0001 00:00:00 +0000

This page is the register of known conceptual conflicts, gaps, and inconsistencies in this wiki — the places where entries contradict each other, contradict the protocol premise in README, or assert as settled something no entry actually specifies.

It exists because the wiki deliberately records open questions in place (not yet specified) rather than papering over them. Those in-place markers say that a question is open; this page says what breaks if it stays open, and collects the conflicts that span more than one entry and so have no single page to live on.

Parameter Stream

Mon, 01 Jan 0001 00:00:00 +0000

A parameter stream specifies numerical, Boolean, and other parameters that typically vary quickly over time — the positions, rotations, and states that change as a realm’s game loop runs. It is the fast-moving counterpart to the structural stream, and together the two carry the Scene Composition Protocol.

Higher-order derivatives#

A parameter may carry derivatives alongside its value: a point’s position can also specify velocity and acceleration. This is what lets a node extrapolate between updates instead of waiting for them — it renders the predicted value each frame and corrects when the next record arrives. Motion then stays smooth at frame rate while the stream runs at whatever rate the network and the loop sustain, and an update becomes a correction rather than a hard requirement.

Peer-to-Peer Network

Mon, 01 Jan 0001 00:00:00 +0000

Gargantis is a pure peer-to-peer network: there is no central server and no privileged tier. Participants are homogeneous nodes running essentially the same software, and every node is ephemeral — any node may disappear at any time, and the protocol treats this as the normal case, never the exception. A node that stays online continuously can improve discovery latency and data availability at the margin, but it is an ordinary peer the protocol grants no special authority and, crucially, must never depend on: correctness and liveness must hold even if no node is permanent.

Persona

Mon, 01 Jan 0001 00:00:00 +0000

A persona (a.k.a. character, toon, avatar) is the mechanism that allows a user/player to interact with a virtual world created as part of a shared social activity with friends. It represents a combination of values and mechanics — attributes, skills, and other things dependent on the experience — and the personality and other individual choices that a player makes to define their character.

A node represents its user through a persona, and a persona travels: crossing a portal hands it from one realm to the next, with no central server mediating the transition.

Portal

Mon, 01 Jan 0001 00:00:00 +0000

A portal connects one realm to another. Portals are what make the Gargantisphere a single navigable space rather than a set of isolated worlds — they are the Gargantisphere’s analogue of the hyperlink.

Kinds of portal#

Obvious portal — a visible boundary or gateway the visitor knowingly steps through (a door, a gate, a marked threshold).
Seamless portal — no visible boundary. If the two realms share physics and continuous geometry, a visitor may cross without being aware of it. A single virtual space can therefore be composed of multiple seamlessly-joined realms; this is also a scaling technique, since each joined realm runs its own game loop and can be served by different peers.

Mechanics#

A portal references the target realm by a content-addressed identifier resolved through Helia / IPFS. Crossing a portal means the node subscribes to the target realm’s streams (via the Scene Composition Protocol) and hands off the visitor’s persona — no central server mediates the transition.

Realm

Mon, 01 Jan 0001 00:00:00 +0000

A realm is a region of the Gargantisphere served by a single game loop. It is the unit of world simulation and authoring: a realm has its own scene, its own physics, and its own avatars.

A realm is published into and replicated across the peer-to-peer network rather than hosted on a server. Its scene is expressed via the Scene Composition Protocol as a Scene Hierarchy, carried by structural and parameter streams. Nodes subscribe only to the partitions of a realm they can currently see, bounded by a Bounding Volume Hierarchy; a large or busy realm may be split into multiple seamlessly-joined sub-realms to spread load across peers.

Scene Composition Protocol

Mon, 01 Jan 0001 00:00:00 +0000

The Scene Composition Protocol (SCP) specifies how a 3D scene is transferred between nodes over the peer-to-peer network and assembled into the Scene Hierarchy a node renders.

Model#

A world is modeled as a hierarchy. Each level has its own coordinate system and a transform mapping a contained coordinate system into its container. Parameters may carry higher-order derivatives — e.g. a point’s position may also specify velocity and acceleration so motion can be extrapolated between updates.

Scene Hierarchy

Mon, 01 Jan 0001 00:00:00 +0000

The Scene Hierarchy is the hierarchical set of objects making up the scene a node renders. Each level has its own coordinate system, and a transform maps a contained object’s coordinates into its container’s — so moving a parent moves everything beneath it, and an object’s world placement is the composition of the transforms along its path to the root.

It is the structure the Scene Composition Protocol assembles from incoming streams: the structural stream adds, removes, and re-parents objects, while the parameter stream drives values on objects already present. A realm’s bounding volume hierarchy is indexed over this tree, which is what lets a node subscribe to a subtree it can see and ignore the rest.

Structural Stream

Mon, 01 Jan 0001 00:00:00 +0000

A structural stream specifies the structure of a realm’s objects — what exists, of what type, parented where — and typically varies slowly over time. It is one of the two stream kinds the Scene Composition Protocol uses; the other, the parameter stream, carries the values that change quickly.

Why the split#

The two kinds have opposite delivery needs. Structural records are comparatively rare, but nothing else can be interpreted without them, and a missed one cannot be papered over by extrapolation — a node that never learned an object exists cannot render it. Parameter records are the reverse: high rate, individually disposable, stale within a frame. Separating them lets a node fetch the structure of a newly-visible BVH partition once and then track only its parameters, and lets each kind be delivered on the terms it actually needs.

The Log

Mon, 01 Jan 0001 00:00:00 +0000

A log is an append-only sequence of records ordered by time — a very simple storage abstraction, and the one underneath every Gargantis stream. It acts as a kind of messaging system with durability guarantees and strong ordering semantics, and it solves the two problems every distributed data system has: ordering changes and distributing data.

The load-bearing property is the State Machine Replication Principle: if two identical, deterministic processes begin in the same state and get the same inputs in the same order, they will produce the same output and end in the same state. A game loop is exactly such a process, which is why a realm can converge across the network with no authoritative server deciding what is true.

Transform

Mon, 01 Jan 0001 00:00:00 +0000

A transform is composed of a position, a rotation, and a scale. The position is represented as a three-dimensional vector, and the scale is also a three-dimensional vector. Every level of the scene hierarchy carries one, mapping a contained coordinate system into its container, so an object’s world placement is the composition of the transforms along its path to the root.

The three components compose into a single 4×4 matrix — using homogeneous coordinates, so that translation, rotation, and scale all become multiplication and a chain of them collapses into one product. That matrix is the form the GPU consumes.

Vertex

Mon, 01 Jan 0001 00:00:00 +0000

A vertex is a point of a mesh — the atom of renderable geometry. It is a position, and usually more: a vertex commonly carries a normal for lighting, UV coordinates for texturing, and sometimes a colour or skinning weights. These are its attributes, and naming which attributes a vertex may carry is part of what the Gargontology has to do.

The vertices property of a mesh is an ordered list with elements of type vertex. The ordering is load-bearing rather than incidental: triangles are defined by indices into that list, so a vertex’s position in it is its identity, and sharing one vertex between adjacent triangles is what makes a mesh a connected surface rather than a pile of loose triangles.

Web Stream Message Protocol

Mon, 01 Jan 0001 00:00:00 +0000

The Web Stream Message Protocol (WSMP) defines how a web stream is carried between nodes. A web stream is a resource that provides data to many subscribers in the form of a replicated log of messages. The channel between publisher and subscriber is bidirectional and symmetric: what a publisher emits may depend on messages its subscribers send, so a stream is a conversation rather than a broadcast.

Web streams carry both stream kinds the Scene Composition Protocol uses — the structural stream and the parameter stream. The same abstraction composes into data pipelines, where a stage consumes web streams and publishes another, and it simplifies distributing updates to a replicated store.