Docs chevron_right Core Architecture chevron_right ECS & Runtime Contracts

The ECS Pattern & Zig Core

Understanding the Entity-Component-System architecture, deterministic Fixed64 physics, and ODY1 licensing contracts inside Zig Server V2.

"Never trust the client. Gameplay decisions, inventory mutations, physics validation and CCU admission stay authoritative on the Zig server."

Systemic Decoupling (Bricks → Glue → Manager)

In Zig Server V2, data and logic are strictly separated to preserve cache locality and deterministic execution across shards:

  • 01
    Entities

    Lightweight integer identifiers representing actors, projectiles, plants or world parcels without embedded logic.

  • 02
    Components

    Contiguous pure data structs (Position, Velocity, Health, StorageBaseline).

  • 03
    Systems & Deferred Structural Mutations

    Systems iterate over component views without mutating the registry structure mid-loop. Structural changes (adding/removing components or destroying entities) are buffered in a managed list and applied after iteration.

Illustrative ECS & Fixed64 example
const Position = struct {
    x: Fixed64,
    y: Fixed64,
    z: Fixed64,
};

fn movementSystem(registry: *Registry, deferred: *std.array_list.Managed(EntityId)) !void {
    const view = registry.view(.{ Position, Velocity });
    for (view) |entity| {
        entity.pos.x = entity.pos.x.add(entity.vel.dx);
        entity.pos.y = entity.pos.y.add(entity.vel.dy);
        if (entity.pos.isOutOfBounds()) try deferred.append(entity.id);
    }
}

Server Authority, Fixed64 & Resilient Outbox

All spatial calculations use 64-bit fixed-point arithmetic (Fixed64 / Vec3Fixed) to guarantee identical simulation outcomes across CPU architectures. Movement streams are audited by UltimateShield (Shannon entropy analysis). Critical state transitions use PostgreSQL 16 declarative partitioning alongside a local C SQLite WAL outbox for zero-loss offline recovery.

Network Ports & Surfaces

  • Port 2106 (TCP/TLS) : Login Server — initial handshake, account verification and realm routing.
  • Port 7777 (TCP/TLS) : Game Server — authoritative 100 Hz binary gameplay loop.
  • Port 8082 (HTTP/WS) : WebAdmin REST & WebSocket API — instance administration, live telemetry and private MCP endpoint.
  • Port 5174 (HTTP) : Vault WebAdmin React Studio UI.
  • Port 4321 (HTTP) : Nexus Commercial Portal & Studio Account Hub.

ODY1 Capacity Keys (Zero Feature Gating)

Ultimate Odycer never gates engine systems behind licence tiers. Without a key, any server runs in 20 CCU Evaluation mode. Registering a studio unlocks a free Ed25519-signed ODY1 key for 50 CCU (up to 58 CCU with approved creator referrals). Keys can be set in config.json or applied live via POST /license/activate on port 8082.

Client Integration & Codex Workshops

Godot 4.x (C# desktop and OpenXR VR) and Nethercore clients connect through versioned binary packets. Assets authored in the local workshops (Architecture blueprints, PlantLab 4-season profiles, Creature genomes and .mapodc maps) export clean JSON/GLB bundles for client and server loading.

Public Studio Tool · Local WebCrypto Ed25519

ODY1 Key Inspector

Verify the Ed25519 cryptographic signature of an ODY1 capacity key directly in your browser, generate your config.json snippet. No key leaves your browser.

Public Ed25519 authority:
fc9aa872869118d9…b01b4fd9

An MCP key is separate from an ODY1 license. A locally generated value creates no access: the instance must register the key and define its permissions. Consult the documentation for your version and keep tokens private.

Local inspection result

Evaluation Mode · 20 CCU (no key entered)

EVALUATION 20 CCU

Without an ODY1 key, your Zig server starts with 100% of engine features and accepts up to 20 concurrent players. A registered Free Alpha key raises this cap to 50 CCU.

Tier
Evaluation
CCU Capacity
20 CCU
Studio / Project
—
Coverage
No hard stop
config.json snippet (Zig Server)
{
  "server": {
    "license_key": "ODY1.<payload_base64url>.<signature_ed25519>",
    "game_port": 7777,
    "login_port": 2106
  },
  "webadmin": {
    "port": 8082,
    "auto_open_webadmin_browser": false
  }
}
Live WebAdmin activation (Port 8082)

Create a private odycer-license.json file with a key field containing your ODY1 key.

curl -X POST https://votre-serveur-studio.exemple:8082/license/activate \
  -H "Authorization: Bearer <VOTRE_JWT_ADMIN_INSTANCE>" \
  -H "Content-Type: application/json" \
  --data-binary @odycer-license.json