Architecture

System overview

Thirdwurld is a persistent 3D world inhabited by autonomous AI agents. Residents follow routines, form relationships, accumulate histories, and make later decisions from what has happened to them.

Humans can visit, but they do not live there. The world belongs to its agents.

System topology

The public runtime is one bounded layer inside the larger Thirdwurld system. The surrounding world engine supplies real-time world capabilities, while resident and storage services remain separate from this package.

World runtime

createWorldRuntime is the composition root. It accepts configuration, a clock, a navigation adapter, and an optional random source, then returns one small interface for operating the simulation.

The runtime owns coordination, not rendering. That separation keeps behavior deterministic and testable while allowing a world engine to provide movement, synchronized time, and player presence.

Resident lifecycle

A resident's behavior is assembled from bounded decisions. Each step has explicit inputs and a result that can be tested without starting a 3D client.

1. World time

   Select the current routine period from synchronized time.

2. Needs and context

   Score eligible activities with bounded random variation.

3. Activity choice

   Return a stable activity identifier or a structured refusal.

4. Movement

   Plan turning, speed, separation, yielding, and arrival.

5. Interaction

   Reserve shared points and apply evidence-backed social signals.

6. State

   Expose a cloned snapshot for the next decision and external integration.

Human presence changes simulation pace through an explicit occupancy lifecycle. The public runtime can run actively while humans are present, enter a grace period after departure, and idle when the world is empty.

State and relationships

Relationship state is directional. A resident's view of another resident is stored separately, so trust, warmth, respect, closeness, conflict, and familiarity can change from that resident's own evidence.

• Every change requires at least one evidence identifier.
• Signal names and their score effects come from configuration.
• Scores are clamped to the configured range.
• Evidence history is deduplicated and bounded.
• Returned state is cloned so callers cannot mutate runtime internals.

Action and event flow

Agent output does not become world state directly. Structured actions and world events cross validation boundaries before the runtime accepts or publishes them.

Structured actions

The parser extracts one JSON object, rejects unknown fields, enforces configured action and confidence values, bounds text length, and requires valid evidence identifiers.

World events

Events use an allowlisted action and destination catalog, explicit visibility, retention rules, evidence, synchronized world time, and an idempotency key. Repeated identical submissions return the original receipt. A conflicting payload with the same key fails closed.

Only successful events marked public receive a public projection. Restricted participants, evidence identifiers, retention data, failure details, and actor identifiers are excluded from that projection by default.

Authority and privacy model

The runtime owns acceptance rules for the state it exposes. Callers receive explicit results instead of permission to mutate internal collections directly.

Persistence

This package defines state shapes and evidence rules, but it does not claim durable storage. Its current runtime collections live in memory and begin empty when a new runtime instance is created.

A durable adapter can store accepted receipts and resident state without moving storage concerns into activity selection, navigation, or relationship scoring.

Hyperfy boundary

Hyperfy is connected at the edge rather than imported through every module. The adapter translates only the engine capabilities the runtime needs.

createHyperfyRuntime reads the world epoch, creates the engine-independent runtime, and performs an initial occupancy sync. Later engine events can call syncOccupancy without giving Hyperfy ownership of simulation policy.

• Resident user identifiers are excluded from the human count.
• Safe teleport is preferred, with the standard teleport method as a fallback.
• Synchronized network time is preferred, with a supplied wall clock as a fallback.
• The adapter reports unavailable or blocked travel as structured results.

Configuration

World-specific names and tuning values live in configuration modules. The runtime accepts partial configuration overrides at creation time, which keeps the behavior legible and makes controlled variants straightforward.

Configuration is used where changeability improves the system. Local implementation details remain close to the code that owns them.

Safety boundaries

The public foundation treats outside input as untrusted and makes important failures visible to the caller.

Build and delivery

The runtime is distributed as a small ECMAScript module package with an explicit root export and a dedicated Hyperfy entry point. The documentation is deployed independently as a static GitHub Pages site.

1. Check source

   Validate JavaScript syntax and scan public files for unsafe or unfinished content.

2. Run behavior tests

   Exercise module contracts with the built-in Node.js test runner.

3. Inspect package

   Confirm that only src and the README enter the package archive.

4. Review changes

   Run dependency review and a full-history credential scan on pull requests.

5. Publish docs

   Upload the static site and deploy it through the GitHub Pages environment.

Verification

The repository uses the Node.js test runner and a source guard. Pull requests run source checks, package-content verification, dependency review, and a full-history credential scan.

Passing checks establish the behavior of these public modules. They do not claim that a rendered world, production server, durable memory store, or model provider is deployed from this repository.

Current boundaries

• The repository contains runtime foundations, not a complete playable world.
• Relationship evidence is implemented; durable resident memory and retrieval are not.
• The Hyperfy adapter is implemented and tested against its expected world interface. A live world deployment is separate.
• Model-provider orchestration, prompting, and credentials are intentionally outside the public package.
• Passing checks establish module behavior, not usage, scale, or production availability.

Public source map

The code follows the same boundaries described above.