Zone Architecture

The Grid uses UE5 dedicated servers for zone multiplayer, backed by Cloudflare's edge infrastructure for authentication, zone discovery, and persistent storage. Each zone runs on a dedicated server instance that handles all replication, building, combat, and chat via native UE5 networking.

System Overview

┌──────────────────────────────────────────────────────────────┐
│  UE5 Client                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐   │
│  │ ZoneSubsystem│  │GridsCharacter│  │ ReplicatedBlock   │   │
│  │ (join flow)  │  │(Server RPCs) │  │ (UE5 replication) │   │
│  └──────┬───────┘  └──────┬───────┘  └───────────────────┘   │
│         │                  │                                  │
└─────────┼──────────────────┼──────────────────────────────────┘
          │ HTTP              │ UE5 NetDriver
          ▼                  ▼
┌─────────────────────────────────────────────────────────────┐
│  Infrastructure                                              │
│                                                              │
│  ┌──────────────────┐    ┌─────────────────────────────┐    │
│  │ Cloudflare Edge   │    │ UE5 Dedicated Server        │    │
│  │ (api.a-new-world) │    │ ┌─────────────────────┐     │    │
│  │                   │    │ │ GridGameMode          │     │    │
│  │ Hono Router       │    │ │ - Player validation   │     │    │
│  │ Auth middleware    │    │ │ - Block replication   │     │    │
│  │ Zone join + visit │    │ │ - Combat (server auth)│     │    │
│  │ Server registry   │    │ │ - Chat broadcast      │     │    │
│  └────────┬──────────┘    │ └─────────────────────┘     │    │
│           │               │                              │    │
│           ▼               │  Heartbeat → zone_servers ──┐│    │
│  ┌────────────────┐       │  Visit token validation  ───┘│    │
│  │ D1 (SQLite)    │◄──────│                              │    │
│  │ zone_blocks    │       └─────────────────────────────┘    │
│  │ zone_members   │                                          │
│  │ zone_roles     │       ┌─────────────────────────────┐    │
│  │ zone_servers   │       │ R2 (Asset Storage)           │    │
│  │ sub_zones      │       │ grids-assets bucket          │    │
│  │ credit_*       │       └─────────────────────────────┘    │
│  └────────────────┘                                          │
└─────────────────────────────────────────────────────────────┘

Dedicated Server Model

Each zone is served by one or more UE5 dedicated server instances. Servers register themselves in the zone_servers table and send heartbeats every 30 seconds. The edge API routes players to the least-loaded server with a recent heartbeat.

Why Dedicated Servers?

• Server-authoritative — All gameplay logic (building, combat, movement validation) runs on the server
• Native UE5 replication — Standard property replication, RPCs, and relevancy checking
• Full physics — Server-side physics and collision, not just position relay
• Anti-cheat — Server validates all player actions before replicating to other clients

Connection Flow

1. Client calls GET /api/zones/:id/join → edge API validates access, finds an online server
2. Edge API issues a visit token (signed JWT with player ID, permissions, zone ID)
3. Client receives server_host, server_port, visit_token
4. Client calls ClientTravel(host:port?VisitToken=token) to connect via UE5 networking
5. Dedicated server validates the visit token on Login, sets up PlayerState with permissions
6. UE5 handles all replication from this point

Server Registration

Dedicated servers register with the edge API on startup and maintain their registration via heartbeats:

POST /api/zones/servers/register   → { zone_id, host, port, max_players }
POST /api/zones/servers/heartbeat  → { server_id, player_count }
POST /api/zones/servers/deregister → { server_id }

Servers that miss two heartbeats (>2 minutes) are considered offline and excluded from routing.

Permissions Enforcement

Permissions are enforced at the dedicated server level — the authoritative game server. The visit token carries the player's initial permissions, and the server's PlayerState tracks them throughout the session.

Permission Sources

1. Visit token — Contains is_owner, can_build, can_moderate flags set by the edge API at join time
2. PlayerState — AGridsPlayerState stores permissions for the duration of the session
3. Server RPCs — ServerRequestBlockPlace, ServerRequestBlockRemove, ServerMeleeAttack all validate permissions before executing

Build Permission Flow

ServerRequestBlockPlace RPC received
  │
  ├─ PlayerState.bCanBuild? ──► NO → reject
  │
  ├─ Distance check (<2000cm) ──► TOO FAR → reject
  │
  ├─ Block limit check ──► EXCEEDED → reject
  │
  └─ Spawn AReplicatedBlock ──► Replicates to all clients

Block Streaming

Zones can contain up to 2 million blocks (realm tier). Blocks are loaded in chunks via the REST API and managed in real-time through server replication.

Chunk Requests

The client requests block chunks via the REST API:

GET /api/zones/:id/blocks?chunk_x=0&chunk_y=0&chunk_z=0

Each chunk is a 32×32×32 region. The client requests chunks in a sphere around the player as they move.

Real-Time Updates

Block placement and removal use UE5 server RPCs:

• ServerRequestBlockPlace → spawns AReplicatedBlock (replicated to all clients)
• ServerRequestBlockRemove → validates permissions, destroys the block (replicates destruction)

Block Limits

Scalability Considerations

Current Limits

Zone Instancing

For popular zones, multiple dedicated server instances can serve the same zone:

• Each server registers for the same zone_id
• The edge API routes new players to the server with the fewest players
• Cross-server chat and events can be coordinated via the edge API

Cron Jobs

A daily cron trigger (0 6 * * * UTC) processes:

• Rent collection — Auto-renew sub-zone leases, apply 48-hour grace period for insufficient funds, auto-evict after grace
• Revenue split — 95% to zone owner, 5% platform commission on sub-zone rent