Archived plan from February 2026, kept for reference. Some of it shipped differently and some has not been built; see the repository for what exists today.

nAIVE Platform PRD v5.0

๐ŸŒ Product RequirementsLicense: BSL 1.1Version 5.0Author: Mark Ollila

Version: 5.0

Date: February 14, 2026

Author: Mark Ollila

License: BSL 1.1 (converts to MIT after 3 years)

Status: Draft

Classification: Confidential

Companion Document: nAIVE Engine PRD v5.0 (MIT)


1. Executive Summary

The nAIVE Platform is the server infrastructure that turns nAIVE engine games into multiplayer, shareable, AI-directed experiences. While the engine (MIT) handles rendering, physics, and gameplay on the client, the platform (BSL 1.1) handles everything that lives on a server:

  • Multiplayer โ€” server-authoritative game state, dual WebSocket/WebRTC transport, client-side prediction reconciliation
  • World Registry โ€” four-word addresses (black.squirrel.white.deer) as the sharing mechanism
  • AI Director โ€” server-side system that monitors players and evolves worlds in real-time
  • LLM NPC Runtime โ€” persistent-memory NPCs with tiered inference for cost control
  • Telegram Bridge โ€” control live worlds from a chat app
  • Matchmaking โ€” queue-based skill matching and instance management
  • Interest Management โ€” server-side spatial partitioning for bandwidth scaling
  • Horde Authority โ€” simplified server-side simulation for GPU compute entity games

The platform adds multiplayer and network services to any game built with the engine. A game developer can ship a single-player game using only MIT-licensed engine crates. The platform is optional โ€” but it's where the network effects, community, and long-term value live.

Three Proof Games

Each proof game escalates what the platform must handle:

  • Snake Sweeper โ€” 4-player turn-based (WebSocket, 20 Hz, ~16 KB/s per client)
  • HAVOC โ€” 4-player co-op horde survival (WebRTC, 60 Hz, 50,000 GPU entities, ~360 KB/s per client)
  • DROPZONE โ€” 100-player battle royale (WebRTC, 30-60 Hz, 2kmยฒ map, ~300 KB/s per client)
  • If the platform can handle DROPZONE, it can handle any game.


    2. Platform Vision

    "make it rain in black.squirrel.white.deer"
    

    A message sent from Telegram. Within one second, every player connected to that world sees rain particles falling, hears rain audio, and watches the lighting shift. The AI parsed "make it rain" into a weather system call. The server executed it in the world's Lua environment. State deltas flowed to all connected clients. The world changed because someone asked it to โ€” from a chat app.

    The platform's three promises:

    For creators: Publish your game with a four-word name. Anyone in the world can play it instantly โ€” in a browser, no download. Multiplayer is free (you don't build it, the platform provides it).

    For players: Hear about a game. Type four words. You're in. No download, no account, no app store. Your friend is already there.

    For AI: You live inside the world. You remember. You adapt. You're not a tool โ€” you're a collaborator. The Telegram bridge, the AI Director, and the LLM NPCs all run on the server, always on.


    3. Architecture

    3.1 The Server Crate

    naive-server is the single BSL-licensed crate. It depends on naive-core (MIT) for shared types but has no dependency on naive-client.

    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
    

    โ”‚ naive-server (BSL 1.1) โ”‚

    โ”‚ โ”‚

    โ”‚ โ”œโ”€โ”€ World Manager (tokio, runs N worlds) โ”‚

    โ”‚ โ”œโ”€โ”€ Transport Layer (WebSocket + WebRTC) โ”‚

    โ”‚ โ”œโ”€โ”€ World Registry (four-word โ†’ world ID) โ”‚

    โ”‚ โ”œโ”€โ”€ Matchmaker (queue, ELO, instances) โ”‚

    โ”‚ โ”œโ”€โ”€ AI Director (per-world adaptive system) โ”‚

    โ”‚ โ”œโ”€โ”€ LLM NPC Runtime (tiered inference) โ”‚

    โ”‚ โ”œโ”€โ”€ Telegram Bridge (teloxide, AI-parsed NL) โ”‚

    โ”‚ โ”œโ”€โ”€ Interest Manager (spatial partitioning) โ”‚

    โ”‚ โ”œโ”€โ”€ Horde Grid Sim (simplified authority) โ”‚

    โ”‚ โ””โ”€โ”€ Per-World Instance: โ”‚

    โ”‚ โ”œโ”€โ”€ hecs World (canonical ECS state) โ”‚

    โ”‚ โ”œโ”€โ”€ Rapier Physics (headless, no rendering) โ”‚

    โ”‚ โ”œโ”€โ”€ mlua ScriptRuntime (Lua game logic) โ”‚

    โ”‚ โ”œโ”€โ”€ EventBus (typed pub/sub) โ”‚

    โ”‚ โ””โ”€โ”€ State Broadcaster (delta โ†’ transport fan-out) โ”‚

    โ”‚ โ”‚

    โ”‚ Depends on: naive-core (MIT) โ”‚

    โ”‚ Does NOT depend on: naive-client โ”‚

    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

    toml
    # Cargo.toml for naive-server
    

    [dependencies]

    naive-core = { path = "../naive-core" }

    tokio = { version = "1", features = ["full"] }

    tungstenite = "0.21" # WebSocket

    webrtc = "0.9" # WebRTC DataChannels

    teloxide = "0.12" # Telegram Bot API

    mlua = { version = "0.9", features = ["lua54"] }

    rapier3d = "0.18"

    hecs = "0.10"

    sqlx = { version = "0.7", features = ["sqlite"] }

    3.2 Three-Layer Stack (Server Perspective)

                        โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
    

    โ”‚ CREATOR LAYER โ”‚

    โ”‚ โ”‚

    โ”‚ Claude Code โ”€โ”€โ”€โ”€โ”€โ”€> YAML + Lua + Assets โ”‚

    โ”‚ NL Compiler โ”€โ”€โ”€โ”€โ”€โ”€> Scene Generation โ”‚

    โ”‚ Telegram โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€> Live World Commands โ”‚

    โ”‚ MCP Server โ”€โ”€โ”€โ”€โ”€โ”€> Agent Interaction โ”‚

    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

    โ”‚ publish / command

    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”

    โ”‚ SERVER LAYER (this PRD) โ”‚

    โ”‚ โ”‚

    โ”‚ World Registry (4-word names โ†” world IDs) โ”‚

    โ”‚ Per-World: โ”‚

    โ”‚ โ”œโ”€โ”€ hecs ECS (canonical state) โ”‚

    โ”‚ โ”œโ”€โ”€ Rapier (headless physics) โ”‚

    โ”‚ โ”œโ”€โ”€ mlua (game logic scripts) โ”‚

    โ”‚ โ”œโ”€โ”€ AI Agents (LLM NPC runtime) โ”‚

    โ”‚ โ”œโ”€โ”€ AI Director (adaptive evolution) โ”‚

    โ”‚ โ”œโ”€โ”€ Horde Sim (simplified grid) โ”‚

    โ”‚ โ”œโ”€โ”€ Matchmaker (queue + ELO) โ”‚

    โ”‚ โ””โ”€โ”€ Broadcaster (delta โ†’ WS/WebRTC) โ”‚

    โ”‚ Transport: WebSocket + WebRTC โ”‚

    โ”‚ Telegram Bridge (teloxide) โ”‚

    โ”‚ Asset CDN (scene + mesh + audio) โ”‚

    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

    โ”‚ state deltas

    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”

    โ”‚ CLIENT LAYER (see Engine PRD) โ”‚

    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜


    4. Server Authority Model

    The server is the single source of truth for all world state.

    • Anti-cheat by design. Clients send input events only. They cannot claim "my position is X" or "my score is Y." The server computes all state.
    • Consistent for all viewers. Every connected client sees the same world.
    • External control works naturally. Telegram commands, MCP tools, AI Director interventions all execute in the server's Lua environment.
    • Multiplayer is free. Adding a player = spawn entity + process input stream.

    Horde Authority Split

    For GPU compute entity games (HAVOC), the server is authoritative for aggregate horde state, not individual entity positions:

    WhatWhereWhy
    Total enemies aliveServerGameplay scoring
    Wave number, timingServerGame progression
    Damage dealt to playersServerAnti-cheat
    Flow fieldServer (computed) โ†’ Client (consumed)Pathfinding
    Individual goblin positionsClient (GPU compute)50K positions = 2.4 MB/tick. Impossible to replicate.
    Spawn commandsServer โ†’ ClientAuthority over spawning
    Death eventsServer (validated from grid counts)Scoring

    Sending 50,000 entity positions per tick at 60 Hz = 144 MB/s per client. Instead, the server sends flow fields (~64 KB, ~1/sec), spawn commands (~100 bytes each), death counts, and aggregate state. Each client runs the same GPU compute shaders with the same flow field. Small divergences between clients are invisible in a 50,000 entity swarm.


    5. Networking

    5.1 Dual Transport Architecture

    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
    

    โ”‚ Transport Layer โ”‚

    โ”‚ โ”‚

    โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚

    โ”‚ โ”‚ WebSocket โ”‚ โ”‚ WebRTC โ”‚ โ”‚

    โ”‚ โ”‚ (reliable)โ”‚ โ”‚ DataChannel โ”‚ โ”‚

    โ”‚ โ”‚ TCP-based โ”‚ โ”‚ (unreliable) โ”‚ โ”‚

    โ”‚ โ”‚ 20 Hz โ”‚ โ”‚ 60 Hz โ”‚ โ”‚

    โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚

    โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚

    โ”‚ โ”‚ โ”‚

    โ”‚ State Delta Protocol โ”‚

    โ”‚ (shared, transport-agnostic) โ”‚

    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

    โ”‚

    World Instance

    Per-world YAML configuration selects the transport:

    yaml
    network:
    

    transport: webrtc # or "websocket"

    tick_rate: 60 # Hz

    interpolation_delay: 2 # ticks

    prediction: true

    interest_radius: 100.0 # meters

    Both transports encode the same state delta protocol. A single server can host worlds with different transports simultaneously.

    WebRTC signaling: HTTPS for SDP exchange, then DataChannel for all game traffic. ICE/STUN for NAT traversal.

    5.2 State Delta Protocol

    json
    {
    

    "tick": 3042,

    "ack_input_tick": 3040,

    "updates": [

    {

    "entity": "player_1",

    "transform": {"position": [43.2, 0, 87.1], "rotation": [0, 45, 0]},

    "health": 85,

    "shield": 40

    },

    {

    "entity": "player_2",

    "transform": {"position": [51.0, 0, 82.3]},

    "animation_state": "run"

    },

    {"spawn": {"id": "pickup_12", "type": "health_pack", "position": [40, 0, 90]}},

    {"despawn": "pickup_7"}

    ],

    "horde": {

    "flow_field_update": "base64_encoded_128x128_grid",

    "spawns": [

    {"count": 200, "position": [80, 0, 50], "type": "goblin_melee"}

    ],

    "deaths": {"total_this_tick": 47},

    "alive_count": 23847,

    "wave": 5

    },

    "audio": [

    {"type": "play_sfx", "id": "explosion_3", "file": "assets/audio/boom.mp3", "position": [45, 0, 88]}

    ]

    }

    Bandwidth analysis:

    ScenarioDelta Size/TickAt Tick Rate
    Snake Sweeper (4 players, 20 Hz)~800 bytes~16 KB/s
    HAVOC solo (1 player, 60 Hz)~4 KB~240 KB/s
    HAVOC co-op (4 players, 60 Hz)~6 KB~360 KB/s
    DROPZONE (100 players, 30 Hz)~8 KB (per client)~240 KB/s
    Arena shooter (16 players, 60 Hz)~8 KB~480 KB/s

    5.3 Connection Lifecycle

    1. Client resolves four-word name โ†’ server address + transport type
    

    GET https://registry.naive.world/resolve/black.squirrel.white.deer

    โ†’ { "server": "us-east.naive.world", "world_id": "a1b2c3d4",

    "transport": "webrtc", "tick_rate": 60 }

    2a. (WebSocket) Standard handshake

    2b. (WebRTC) HTTPS signaling โ†’ DataChannel establishment

  • Server sends: full scene snapshot + horde config
  • Client downloads assets (CDN or server, cached locally)
  • Client builds local ECS + renderer from scene definition
  • Server streams state deltas every tick (interest-managed)
  • Client sends input events to server
  • On disconnect: client state discarded, server is truth
  • 5.4 Latency Budgets

    Snake Sweeper (v4.0 profile):

    Game tick: 280ms
    

    Input โ†’ server: 20-50ms (WebSocket)

    Server tick: 1-5ms

    Delta โ†’ client: 20-50ms

    Round-trip: ~60-120ms

    Budget remaining: 160-220ms โ† generous

    HAVOC (v5.0 profile):

    Game tick: 16.7ms (60 Hz)
    

    Input โ†’ server: 5-15ms (WebRTC)

    Server tick: 2-5ms

    Delta โ†’ client: 5-15ms

    Perceived latency: <16ms (prediction hides it)


    6. Server-Side Prediction Reconciliation

    Client-side prediction runs on the client (see Engine PRD Section 4.6). The server's role:

  • Receive input event from client with tick number
  • Process input authoritatively (character controller + Rapier physics)
  • Produce authoritative position
  • Include ack_input_tick in delta broadcast
  • Client compares prediction to server state and reconciles if needed
  • The server does NOT run prediction. It runs the authoritative simulation. The ack_input_tick tells the client "I've processed your inputs up to tick N" so the client can discard old prediction buffer entries.


    7. Server-Authoritative Hit Detection

    Weapons are defined in the Engine PRD. Hit detection runs on the server:

    7.1 Hitscan Weapons

    Client sends: {action: "fire", weapon: "assault_rifle", aim_direction: [0.7, 0.1, 0.7], tick: 3042}
    

    Server receives fire event

    Server rewinds entity positions to tick 3042 (lag compensation)

    Server raycasts from player position in aim_direction

    If hit: apply damage, broadcast hit event to all clients

    If miss: broadcast miss event (impact effect at ray endpoint)

    7.2 Lag Compensation

    The server maintains a history buffer of entity positions (last 200ms, ~12 ticks at 60 Hz). When processing a fire event from tick 3042, the server temporarily rewinds all entities to their positions at tick 3042, performs the raycast, then restores current positions.

    This ensures that what the client saw when they fired (their view of other players' positions at the time) is what the server validates against. Without lag compensation, players would need to "lead" their shots by their latency โ€” unacceptable for competitive games.

    7.3 Projectile Weapons

    Projectiles are ECS entities simulated on the server. Each tick: update position (physics). On collision: apply splash damage. Broadcast spawn, position updates, and explosion events to clients.


    8. Interest Management

    Server-side spatial partitioning determines per-client entity visibility:

    โ”Œโ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”
    

    โ”‚ โ”‚ โ”‚ โ”‚ โ”‚

    โ”‚ โ”‚ P1 โ”‚ โ”‚ โ”‚ P1's relevance radius

    โ”‚ โ”‚ โ—โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€ โ”‚ covers nearby cells

    โ”œโ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”ค

    โ”‚ โ”‚ โ”‚ โ”‚ P2 โ”‚ P2 is outside P1's radius

    โ”‚ โ”‚ โ”‚ โ”‚ โ— โ”‚ โ†’ P1 does NOT receive P2 updates

    โ”‚ โ”‚ โ”‚ โ”‚ โ”‚

    โ””โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”˜

    Grid-based partitioning with configurable cell size. Each client has a relevance set updated every N ticks (sticky to avoid flickering).

    Bandwidth scaling:

    PlayersWithout Interest MgmtWith Interest MgmtSavings
    416 entity streams~850%
    16256~8069%
    10010,000~80092%

    Interest management is critical for DROPZONE (100 players). Without it, each client receives 100 player updates per tick. With it, each client receives ~20-30 nearby players.

    For horde data: Flow field is global (small, ~64 KB). Spawn/death events filtered by interest radius. This means clients on opposite sides of the map see slightly different horde compositions โ€” which is fine.


    9. AI Director

    Server-side system that monitors player behavior telemetry and evolves the world:

    Player Telemetry โ†’ Analysis โ†’ Intervention Plan โ†’ Graduated Response
    
    

    Intervention levels:

    Subtle: Adjust spawn rates, lighting mood, music tempo

    Moderate: Introduce new NPCs, modify terrain, create events

    Significant: Restructure layout, change rules, add mechanics

    Transformative: Genre shifts (requires player opt-in)

    9.1 Snake Sweeper Director

    • 3+ mines in a row โ†’ reduce density 20%, add food
    • Clearing too easily โ†’ increase density, add obstacles
    • Player stuck โ†’ flash hint showing safe path
    • Mine circumnavigated โ†’ spawn bonus item

    9.2 HAVOC Director

    • Deaths > 3/minute โ†’ reduce wave size 30%, add health drops
    • No deaths, high kills โ†’ increase spawn rate, add ranged/elite enemies
    • Players cluster โ†’ spawn flanking waves from behind
    • Vehicle found โ†’ increase density to match power spike
    • Session > 20 min โ†’ boss wave

    9.3 DROPZONE Director

    • Storm pacing: shrink faster when many players alive, slower when few remain
    • Loot distribution: increase rare drops in low-traffic areas to encourage exploration
    • Bot difficulty: AI-controlled bots (to fill lobbies) scale to player skill
    • Supply drop placement: drops in contested areas to create engagement

    Fairness guardrail: In multiplayer, the Director never gives one player a mechanical advantage.


    10. LLM NPC Agent Runtime

    Entities with agent_brain components (defined in Engine PRD) run their inference on the server:

    yaml
    - id: merchant
    

    components:

    agent_brain:

    personality: "Gruff but fair dwarven blacksmith. Remembers repeat customers."

    memory_slots: 50

    inference_tier: 2

    10.1 Tiered Inference

    TierLatencyCost/CallUse CaseImplementation
    1500ms~$0.01Complex conversation, novel situationsClaude API (Haiku/Sonnet)
    250ms~$0.001Routine dialogueDistilled local model (Ollama)
    31ms~$0Greetings, combat barksPattern match + template cache

    10.2 Memory Architecture

    • Short-term: Last 10 interactions (full context)
    • Long-term: Vector-indexed memory store (embed interactions, retrieve relevant)
    • Personality: Immutable system prompt
    • Relationships: Per-player score (affects dialogue, trade prices)

    11. Telegram Integration

    11.1 Architecture

    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
    

    โ”‚ Telegram โ”‚โ”€โ”€โ”€โ”€>โ”‚ nAIVE Bot โ”‚โ”€โ”€โ”€โ”€>โ”‚ AI Parser โ”‚โ”€โ”€โ”€โ”€>โ”‚ World Server โ”‚

    โ”‚ User โ”‚<โ”€โ”€โ”€โ”€โ”‚ (teloxide) โ”‚<โ”€โ”€โ”€โ”€โ”‚ (Claude API) โ”‚<โ”€โ”€โ”€โ”€โ”‚ (Lua exec) โ”‚

    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

    11.2 Command Flow

    User on Telegram: "make it rain in black.squirrel.white.deer"
    
    
  • Bot extracts world reference
  • AI parser: "make it rain" โ†’ { "function": "weather.set", "args": ["rain"] }
  • Server executes in world's Lua environment: weather.set("rain")
  • State deltas broadcast to all clients
  • Bot replies: "It's raining in black.squirrel.white.deer"
  • 11.3 Bot Commands

    /connect snake.3d.nokia.mark       โ€” Subscribe to world events
    

    /disconnect โ€” Stop receiving updates

    /status โ€” World stats

    /players โ€” Connected players

    /worlds โ€” Your published worlds

    /command <anything> โ€” Natural language command

    11.4 World Notifications (Push)

    Push events to subscribed Telegram users: high scores, player joins, wave completions, boss kills.


    12. World Registry and Four-Word Naming

    12.1 Why Four Words

    URLs fail for games. Nobody remembers https://naive.world/a1b2c3d4-5678-...

    black.squirrel.white.deer โ€” you can tell someone this across the room.

    ~2,000 curated words โ†’ 16 trillion unique addresses. Pattern: {adjective}.{noun}.{adjective}.{noun}.

    12.2 Registry Architecture

    sql
    -- SQLite schema
    

    CREATE TABLE worlds (

    id TEXT PRIMARY KEY,

    name TEXT UNIQUE, -- four-word address

    owner TEXT,

    server TEXT, -- server hostname

    transport TEXT DEFAULT 'websocket',

    tick_rate INTEGER DEFAULT 20,

    created TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    status TEXT DEFAULT 'active', -- active, paused, archived

    config TEXT -- JSON

    );

    CREATE TABLE matches (

    id TEXT PRIMARY KEY,

    world_template TEXT, -- four-word name of template

    instance_id TEXT,

    players TEXT, -- JSON array

    started TIMESTAMP,

    status TEXT DEFAULT 'lobby'

    );

    CREATE TABLE dictionary (

    word TEXT PRIMARY KEY,

    category TEXT, -- noun, adjective

    syllables INTEGER

    );

    12.3 REST API

    GET  /resolve/{w1}.{w2}.{w3}.{w4}   โ†’ { server, world_id, transport, tick_rate }
    

    POST /register โ†’ { name, server, owner, transport }

    GET /browse โ†’ { category, sort, page }

    POST /publish โ†’ { name, assets[] }

    POST /matchmake โ†’ { game_type, player_id, region }

    GET /match/{match_id} โ†’ { status, players, instance }

    GET /health/{world_id} โ†’ { tick_rate, players, uptime }

    12.4 Player Identity

    • Anonymous: Random four-word player name
    • Telegram: Uses Telegram username
    • Persistent: Optional account for ELO, stats, achievements

    13. Matchmaking and Instance Management

    13.1 Queue-Based Matchmaking

    Player โ†’ selects game mode โ†’ enters queue
    

    โ†’ Matchmaker groups by ping region + skill (ELO ยฑ200)

    โ†’ Server spins up world instance

    โ†’ Players receive four-word address

    โ†’ On match end โ†’ results โ†’ back to queue or exit

    โ†’ Instance torn down after disconnect + 60s grace

    13.2 ELO/MMR

    • New players: 1000 ELO
    • Win: +25 ร— (1 - expected_win_probability)
    • Loss: -25 ร— expected_win_probability

    13.3 Instance Management

    • Each match = fresh world instance (~50-100 MB memory)
    • Instance pool with warm-start (pre-loaded scenes) for <3s match start
    • A single 4-vCPU server runs ~20 concurrent HAVOC matches or ~5 DROPZONE matches

    14. Proof Games (Platform Perspective)

    14.1 Snake Sweeper

    AttributeValue
    TransportWebSocket
    Tick rate20 Hz
    Players1-4
    Bandwidth/client~16 KB/s
    Server memory~50 MB
    Platform features exercisedWorld registry, WebSocket transport, Telegram bridge, AI Director

    14.2 HAVOC

    AttributeValue
    TransportWebRTC DataChannel
    Tick rate60 Hz
    Players1-4 co-op
    Bandwidth/client~360 KB/s
    Server memory~100 MB
    Platform featuresWebRTC, prediction reconciliation, horde authority, interest mgmt, AI Director, matchmaking

    14.3 DROPZONE (Battle Royale)

    AttributeValue
    TransportWebRTC DataChannel
    Tick rate30 Hz (100 players) โ†’ 60 Hz (<50 alive)
    Players100 (solos) / 25 squads of 4
    Map2km ร— 2km, 32ร—32 chunks
    Bandwidth/client~300 KB/s
    Server memory~500 MB

    What DROPZONE adds to the platform:

    SystemDescription
    Storm systemShrinking circle, server-authoritative position/radius/damage
    Loot spawnerYAML loot tables โ†’ spawn entities at predefined positions
    Bus/dropshipMoving entity, player detach, parachute physics
    Spectator modeCamera follows another player post-elimination
    100-player lobbyMatchmaker queues 100, countdown, hot-start instance
    Dynamic tick rate30 Hz with 100 players โ†’ 60 Hz when <50 alive
    Building (stretch)Grid-snapped placement, material harvesting, structure health

    Loot tables:

    yaml
    loot_table:
    

    floor_spawn:

    common: { prob: 0.40, items: [pistol, smg, bandages] }

    uncommon: { prob: 0.30, items: [assault_rifle, shotgun, shield_cells] }

    rare: { prob: 0.20, items: [sniper_rifle, rocket_launcher, med_kit] }

    epic: { prob: 0.08, items: [scar, heavy_shotgun, chug_jug] }

    legendary: { prob: 0.02, items: [gold_scar, mythic_item] }

    DROPZONE performance targets:

    MetricTarget
    Players100
    Map2km ร— 2km
    Server tick rate30-60 Hz
    Bandwidth/client<300 KB/s
    Server memory/match~500 MB
    Match duration~20 min
    Match start time<5s from lobby fill

    15. Licensing

    15.1 BSL 1.1 (Business Source License)

    naive-server is licensed under BSL 1.1.

    What you CAN do:

    • Self-host your own game servers using naive-server
    • Modify the server code for your games
    • Use it in commercial production
    • Run servers for your studio, tournaments, private communities
    • Read the source, learn from it, contribute to it

    What you CANNOT do:

    • Offer nAIVE world hosting as a commercial service that competes with the nAIVE platform
    • Specifically: "managed hosting where customers upload nAIVE worlds and you charge for hosting them"

    The Additional Use Grant: The specific restriction is: you may not use this software to provide a Managed nAIVE World Hosting Service (a service where third parties upload nAIVE world definitions and you host and serve them for a fee).

    3-year change date: BSL 1.1 converts to MIT automatically three years after each release. Code released in 2026 becomes MIT in 2029. This is baked into the license text โ€” it's not a promise, it's a legal obligation.

    15.2 Why BSL (Not MIT)

    The server contains the platform infrastructure โ€” the world registry, matchmaking, AI Director, and hosting orchestration. Without protection, a well-funded competitor could:

  • Fork the server
  • Build a competing "nAIVE Cloud" hosting service
  • Undercut the nAIVE platform on price (subsidized by their other business)
  • Capture the network effects that the nAIVE community built
  • BSL prevents this specific scenario while allowing every legitimate use:

    Use CaseAllowed?
    Self-host your game's serversYes
    Modify server code for your gameYes
    Run a tournament serverYes
    Use in commercial productionYes
    Start a "nAIVE World Hosting" businessNo

    The 3-year conversion ensures the code becomes fully open eventually.

    15.3 CLA Requirements

    Contributors to naive-server sign a Contributor License Agreement granting the project the right to relicense. This ensures the 3-year MIT conversion isn't blocked.

    15.4 Prior Art

    Other BSL projects: MariaDB, CockroachDB, HashiCorp (Terraform), Sentry. The model is well-understood by the open-source community.


    16. Infrastructure

    The platform starts on minimal hardware:

    Beelink EQ14 Mini PC
    

    CPU: Intel N150 (up to 3.6 GHz)

    RAM: 16 GB DDR4

    Storage: 500 GB NVMe + 2 TB M.2

    Network: 1 Gbps dual LAN

    Running: naive-server + cloudflared tunnel

    Capacity: ~50 concurrent worlds (Snake Sweeper class)

    ~10 concurrent HAVOC matches

    Cloudflare stack:

    • cloudflared tunnel: Already running. Routes traffic to Beelink without exposing IP.
    • Workers: Registry API, auth, rate limiting
    • D1: World registry database (SQLite-compatible)
    • R2: Asset CDN (scene files, meshes, audio, textures)
    • Pages: Web portal, WASM client hosting at play.naive.world

    Monthly cost: ~$15-40 (Cloudflare free tier + paid Workers for scale)

    16.2 Growth: VPS

    When the Beelink is saturated:

    • 4 vCPU, 8 GB RAM VPS: ~$40/month โ†’ ~100 worlds, ~20 HAVOC matches
    • 8 vCPU, 16 GB RAM: ~$80/month โ†’ ~200 worlds, ~5 DROPZONE matches

    16.3 Scale: Horizontal

    Multiple server instances behind load balancer. World migration between servers for balancing. Cloudflare Workers route clients to the correct regional server.


    17. Server Technical Specifications

    17.1 Server Requirements

    ResourcePer World (Snake Sweeper)Per World (HAVOC)Per Match (DROPZONE)
    CPU1 core2 cores4 cores
    Memory~50 MB~100 MB~500 MB
    Network/client~16 KB/s~360 KB/s~300 KB/s

    17.2 Capacity Planning

    HardwareSnake Sweeper WorldsHAVOC MatchesDROPZONE Matches
    Beelink EQ14 (N150, 16 GB)~50~10~2
    4-vCPU VPS (8 GB)~100~20~5
    8-vCPU VPS (32 GB)~200~40~10

    18. Implementation Roadmap (Server)

    Phase 1 (Weeks 1-4): Headless Server + WebSocket

    WeekDeliverable
    1-2Feature-flagged Cargo build: naive-server compiles without wgpu
    3WebSocket state streaming: server broadcasts deltas
    4World registry: SQLite, four-word name resolution, REST API

    Phase 2 (Weeks 5-8): Multiplayer + Telegram

    WeekDeliverable
    5-6Multiplayer Snake Sweeper: 2-4 players on shared minefield
    7Telegram bridge v2: AI-parsed NL commands
    8AI Director v1: adaptive difficulty for Snake Sweeper

    Phase 3 (Weeks 9-16): Fast Netcode

    WeeksDeliverable
    9-10WebRTC DataChannel transport layer
    11-12Server-side prediction acknowledgment + lag compensation
    13-14Interest management: grid-based spatial partitioning
    15-16Matchmaking: queue service, ELO, instance management

    Phase 4 (Weeks 17-24): HAVOC Server

    WeeksDeliverable
    17-18Horde grid simulator (simplified server-side horde authority)
    19-20Server-authoritative weapon hit detection + lag compensation
    21-22AI Director v2: HAVOC wave adaptation
    23-24LLM NPC runtime: tiered inference for boss encounters

    Phase 5 (Weeks 25-32): DROPZONE Server

    WeeksDeliverable
    25-26100-player instance management, dynamic tick rate
    27-28Storm system (server-authoritative shrinking circle)
    29-30Loot spawner, supply drops, spectator mode
    31-32Building system (stretch), 100-player load testing

    Phase 6 (Weeks 33-40): Platform

    WeeksDeliverable
    33-34Asset CDN via Cloudflare R2
    35-36Web portal: world browser at naive.world
    37-38World forking, permissions (public/private/invite)
    39-40Analytics dashboard, platform monitoring

    19. Risk Assessment

    RiskSeverityMitigationFallback
    WebRTC complexityMediumUse webrtc-rs crate, HTTPS signalingWebSocket with prediction for moderate-speed games
    100-player scaling (DROPZONE)HighInterest management, dynamic tick rateCap at 50 players initially
    Horde desync between clientsLowDeterministic compute shaders, periodic correction snapshotsInvisible at 50K โ€” 0.5m difference unnoticeable
    LLM API cost at scaleHighTiered inference: Tier 3 cache handles 60%+ at zero costBehavior trees with LLM-generated cache
    BSL license misunderstandingMediumClear docs, FAQ, examplesCommunity outreach
    Beelink hardware limitsLowVPS migration path at $40/monthCloudflare Workers for stateless components
    Four-word squattingLow16 trillion address spaceInactive worlds archived after 90 days
    Telegram bot rate limitsLowCommand queue, 1 cmd/sec/userDirect WebSocket API as alternative

    20. Success Metrics

    20.1 Technical Metrics

    MetricTarget
    Server tick rate (Snake Sweeper, 4 players)20 Hz sustained
    Server tick rate (HAVOC, 4 players)60 Hz sustained
    Server tick rate (DROPZONE, 100 players)30 Hz sustained
    State delta latency (WebRTC)<15ms
    Match start time (warm instance)<3s
    Concurrent worlds (Beelink)50+
    Concurrent HAVOC matches (4-vCPU VPS)20+
    Telegram command โ†’ visible change<1 second
    NPC response (Tier 1)<500ms
    NPC response (Tier 3)<5ms

    20.2 Experience Metrics

    • Snake Sweeper: 4 players with no perceptible desync
    • HAVOC: 4 players co-op with smooth gameplay
    • DROPZONE: 100 players competitive with fair hit registration
    • Telegram "/command" changes live world within 1 second
    • Sharing a four-word address is the only step to join
    • AI Director interventions rated "helpful" or "invisible" by >70%
    • NPC conversations feel meaningfully different across sessions

    Appendix A: Glossary

    TermDefinition
    Four-word addressHuman-memorable world ID: black.squirrel.white.deer
    State deltaCompact update with only changed entity components
    Server authorityServer computes all state; clients only render
    Tick rateServer updates per second (10-60 Hz)
    AI DirectorServer-side system that monitors and adapts worlds
    Interest managementSpatial culling to limit per-client bandwidth
    Lag compensationServer rewinds state to validate hits at client's view time
    Horde authorityServer tracks aggregate horde state, not individual positions
    BSL 1.1Business Source License โ€” all use except competing hosting service
    Change date3 years after release, BSL converts to MIT automatically
    WebRTC DataChannelBrowser-native UDP-like transport for low-latency networking
    ELO/MMRSkill rating for matchmaking
    InstanceA fresh world spun up for a single match
    Flow fieldServer-computed pathfinding grid sent to clients for horde sim
    naive-clientMIT crate: renderer, audio, input, physics, scripting, all engine modules
    naive-coreMIT crate: shared types, components, scene format, serialization
    naive-runtimeMIT crate: single-process game binary (thin CLI that uses naive-client)
    naive-serverBSL crate: world manager, transport, registry, Director, matchmaking