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 Engine PRD v5.0

๐Ÿ”ง Product RequirementsLicense: MITVersion 5.0Author: Mark Ollila

Version: 5.0

Date: February 14, 2026

Author: Mark Ollila

License: MIT

Status: Draft

Classification: Public

Companion Document: nAIVE Platform PRD v5.0 (BSL 1.1)


1. Executive Summary

nAIVE is an open-source, AI-native game engine written in Rust. Worlds are created by AI, rendering happens on the client's GPU, and everything โ€” scenes, materials, shaders, game logic โ€” is a human-readable file that AI can generate, inspect, and modify.

v4.0 unified three layers (core engine, intelligence, networking) into a single platform specification. This document separates the engine from the platform, because they serve different audiences and carry different licenses:

  • This document (Engine PRD) specifies everything a game developer needs to build and ship games with nAIVE. It covers rendering, physics, audio, scripting, GPU compute simulation, skeletal animation, character controllers, weapons, vehicles, and inventory. All MIT licensed. No restrictions.
  • The companion Platform PRD specifies the server infrastructure: multiplayer hosting, world registry, matchmaking, AI Director, Telegram bridge, and the four-word addressing system. BSL 1.1 licensed.

You do not need the platform to ship a game. naive-core + naive-client + naive-runtime produce a complete single-player game binary. The platform adds multiplayer, hosting, and network services on top.

What v5.0 Adds to the Engine

v4.0's engine was a renderer with scripting and physics. v5.0 adds the systems needed to build action games โ€” shooters, brawlers, horde survival, racing โ€” not just Snake Sweeper:

  • Gameplay primitives (DONE v0.1.2) โ€” health/damage, hitscan, projectiles, collision damage, third-person camera. Tier 1 complete.
  • Production foundations โ€” dynamic GPU instance buffer (no more 256-entity ceiling), entity pooling, particle system, runtime entity queries, event subscription. Informed by HAVOC dev log feedback.
  • GPU compute entity simulation โ€” 50,000+ physics-driven entities on the GPU. nAIVE's answer to Unreal's Niagara, but for gameplay entities, not just particles.
  • Vertex Animation Textures (VAT) โ€” baked skeletal animation sampled on the GPU for massive instanced rendering
  • Skeletal animation system โ€” glTF skinned meshes, animation state machines, blend trees
  • Character controller โ€” capsule-based movement with gravity, jumping, sprinting, crouching, third-person and first-person camera
  • Weapon system โ€” hitscan, projectile, and continuous weapons with YAML-defined stats
  • Vehicle system โ€” physics-driven vehicles with mounted weapons, mount/dismount
  • Inventory and loadout โ€” weapon slots, pickups, ammo, health/shield
  • Client-side prediction engine โ€” local player movement feels instant; reconciles with server when connected
  • Entity interpolation โ€” other entities rendered smoothly between network updates when connected

Proof-of-Concept: HAVOC

HAVOC is a 3D Vampire Survivors-style horde survival game with vehicle combat. It can run as a single-player game using only MIT-licensed engine crates, or as 1-4 player co-op when combined with the platform.

A HAVOC prototype was already built in a single session during Tier 1 development. It validated the full gameplay loop (driving, killing, leveling, upgrading) but exposed hard engine limits: 256-entity ceiling, deferred destroy crashes, no VFX. The Tier 2 production foundations directly address every wall the prototype hit.

  • Health, hitscan, projectiles, collision damage (Tier 1 โ€” DONE)
  • Dynamic entity buffer + pooling + particles (Tier 2 โ€” removes the hard walls)
  • 50,000+ GPU-simulated enemies on screen simultaneously (Tier 3)
  • GPU neighbor-grid collisions between horde entities (Tier 3)
  • Vertex Animation Textures for GPU-instanced horde animation (Tier 4)
  • Third-person character controller with skeletal animation (Tier 4)
  • Driveable vehicles with collision damage (Tier 5)

If nAIVE can render 50,000 physics-driven goblins while you drive a truck through them โ€” it can handle anything.


2. Vision

2.1 What Makes This Different

Traditional EnginenAIVE v5.0
Games are compiled binariesWorlds are YAML + Lua, generated by AI
Authoring requires programmingDescribe what you want in natural language
Shaders are HLSL/GLSL platform-lockedSLANG shaders cross-compile to any GPU backend
3D assets from art pipelines onlyGaussian splats generated from text prompts (Gen-3DGS)
Render pipeline hardcoded in C++YAML-defined render pipeline DAG โ€” add passes without recompiling
Fixed visual style per gameNeural render passes swap visual styles at runtime
Entity counts limited by CPUGPU compute simulation drives 50,000+ entities at 60 FPS
Particle systems are cosmeticGPU entity systems are gameplay โ€” they collide, damage, path-find
Animation requires full CPU skinningVAT animation scales to 50,000+ animated entities on GPU

2.2 The Promise

For creators: Describe what you imagine. AI builds it. Test it locally. Ship it. The engine is MIT โ€” do anything you want with it. Sell your game. Never pay a royalty. Never give anything back. Or publish it with four words on the nAIVE platform and let anyone play it in a browser.

2.3 Design Philosophy

Six founding principles:

The AI agent IS the editor. nAIVE has no visual editor. The AI agent โ€” Claude Code, or any MCP-capable LLM โ€” is the editor. This thesis was validated at a Supercell AI Hackathon where a complete game was built using Claude Code as the sole development interface.

Everything is a file. Scenes, entities, materials, render pipelines, input bindings, event schemas โ€” all human-readable YAML. No proprietary binary formats.

Unix pipes connect everything. AI services via standardized CLI pipes: Meshy for 3D geometry, ElevenLabs for voice, Flux for textures, Claude API for scene generation.

SLANG shaders from day one. NVIDIA's SLANG compiles to Metal, SPIR-V, WGSL, and CUDA. Supports auto-differentiation for neural rendering.

Gaussian Splatting as first-class primitive. Native renderable type alongside meshes, with hybrid depth compositing in the deferred pipeline.

AI observability built in. Frame streaming for AI vision, game state via command socket, structured event logging, simulated input for automated playtesting.

2.4 The Future of Rendering

1990s  Fixed-function pipeline     Hardwired vertex/pixel ops, no shaders

2000s Programmable shaders HLSL/GLSL โ€” artists write lighting math

2010s Physically-based rendering Cook-Torrance, metallic/roughness, HDR

2020s Neural rendering begins NeRF, Gaussian splatting, differentiable rendering

2025+ AI-native rendering Learned shaders, generated assets, prompted style

Leap 1: Gaussian Splats Replace Polygons for AI-Generated Content. Text prompt โ†’ Gen-3DGS โ†’ .ply file โ†’ scene entity. Seconds instead of days.

Leap 2: Neural Shaders Replace Handcoded Shaders. Visual style becomes data, not code โ€” a weight file, downloadable, swappable, sharable.

yaml
passes:

- name: style_transfer

type: neural

weights: assets/neural/ghibli.weights

inputs: [bloomed_color, depth]

output: styled_color

Leap 3: Prompt-to-Render. A single sentence generates geometry (Gen-3DGS), lighting, particles, atmosphere, style (neural pass), and audio.


3. Core Technical Differentiators

3.1 SLANG as Shader Language

FeatureSLANGRaw WGSL/HLSL/GLSL
Cross-compilationSingle source โ†’ WGSL, SPIR-V, HLSL, Metal, GLSLWrite per-platform
Module systemimport with namespaces, interfaces, genericsCopy-paste or #include
DifferentiableBuilt-in auto-differentiation for neural shader trainingNot possible
Type safetyGenerics, interfaces, associated typesWeak typing

All render passes are SLANG source files that cross-compile to WGSL at load time for wgpu.

3.2 Gaussian Splatting as First-Class Rendering Primitive

Splats flow through the same deferred pipeline as meshes. .ply files load with the same API as .gltf files.

yaml
entities:

- id: castle

components:

mesh_renderer:

mesh: assets/meshes/castle.gltf

material: assets/materials/stone.yaml

- id: dragon

components:

splat_renderer:

splat: assets/splats/crystal_dragon.ply

scale: 2.0

3.3 Data-Driven YAML Render Pipeline

The render pipeline is a YAML-defined DAG of passes. Add, remove, or reorder render stages without recompiling. Neural passes slot alongside traditional passes.

yaml
passes:

- name: shadow_pass

type: raster

shader: passes/shadow.slang

output: shadow_map

- name: geometry_pass

type: raster

shader: passes/geometry.slang

outputs: [albedo, normal, depth, metallic_roughness]

- name: splat_pass

type: compute

shader: passes/splat_render.slang

inputs: [depth]

outputs: [albedo, normal]

- name: lighting_pass

type: raster

shader: passes/deferred_light.slang

inputs: [albedo, normal, depth, metallic_roughness, shadow_map]

output: hdr_color

- name: bloom_pass

type: raster

shader: passes/bloom.slang

inputs: [hdr_color]

output: bloomed_color

- name: tonemap_pass

type: raster

shader: passes/tonemap.slang

inputs: [bloomed_color]

output: ldr_color

- name: fxaa_pass

type: raster

shader: passes/fxaa.slang

inputs: [ldr_color]

output: final_color

3.4 AI as Runtime Primitive

AI is a runtime component, not external tooling:

TraditionalnAIVE v5.0
AI writes code at dev timeAI runs inside the game at play time
NPCs follow pre-authored scriptsNPCs are LLM agents that reason, remember, adapt
3D assets created by artists3D assets generated from text on demand
Visual style fixed at compile timeNeural render passes swap styles at runtime
Level design is manualNL Compiler generates levels from natural language

3.5 Self-Modifying Engine (Plugin Architecture)

Hot-loadable .dylib/.so modules with a versioned ABI boundary:

rust
pub trait NaivePlugin: Send + Sync {

fn name(&self) -> &str;

fn version(&self) -> (u32, u32, u32);

fn on_load(&mut self, ctx: &mut PluginContext);

fn on_update(&mut self, ctx: &mut PluginContext, dt: f32);

fn on_unload(&mut self, ctx: &mut PluginContext);

}

3.6 Extended MCP Server

14+ MCP tools covering scene management, NL compilation, agent interaction, asset generation, plugin management, and render pipeline modification. Makes Claude Code (or any MCP client) a first-class citizen.

MCP ToolPurpose
naive/scene/loadLoad a scene YAML
naive/scene/queryQuery entities, components, transforms
naive/scene/modifyAdd/remove/update entities
naive/nl/compileNatural language โ†’ YAML + Lua
naive/generate/splatText description โ†’ Gaussian splat (Gen-3DGS)
naive/plugin/listList loaded plugins
naive/plugin/swapHot-swap a plugin at runtime
naive/render/pipelineQuery or modify the render pipeline YAML

3.7 GPU Compute Entity Simulation (NEW in v5.0)

The most ambitious new system. nAIVE's answer to Unreal's Niagara.

Traditional game engines simulate entities on the CPU. At 10,000+ entities, the CPU becomes the bottleneck. nAIVE's GPU compute entity system simulates tens of thousands of physics-driven entities entirely on the GPU โ€” flocking, collision, pathfinding, damage โ€” all in compute shaders.

CapabilityCPU ECSGPU Compute Entities (v5.0)
Max active entities~5,00050,000+
Collision detectionRapier broadphaseNeighbor-grid on GPU
PathfindingA* on CPUFlow field on GPU
AnimationSkeletal (CPU-skinned)VAT (GPU-sampled)
RenderingIndividual draw callsGPU instancing from compute buffer
Use casePlayers, bosses, key NPCsHordes, swarms, crowds, bullet hell

The two systems coexist. Players and bosses remain CPU ECS entities. Hordes and swarms use GPU compute entities. Full specification in Section 8.


4. Architecture

4.1 Crate Structure

nAIVE is split into three MIT-licensed crates:

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

โ”‚ naive-core (MIT) โ”‚

โ”‚ Shared types, ECS components, scene format, โ”‚

โ”‚ serialization โ”‚

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

โ”‚

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

โ”‚ naive-client (MIT) [library crate] โ”‚

โ”‚ Re-exports naive-core. Renderer, audio, input, โ”‚

โ”‚ physics, scripting, UI, GPU horde sim, skeletal โ”‚

โ”‚ animation, prediction engine, interpolation โ€” โ”‚

โ”‚ all engine modules (25 total) โ”‚

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

โ”‚

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

โ”‚ naive-runtime (MIT) [binary crate] โ”‚

โ”‚ Thin CLI entry point. Produces naive, โ”‚

โ”‚ naive-runtime, and naive_mcp binaries. โ”‚

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

naive-core: Shared types library. Contains ECS component definitions, scene format parsing, transform types, tween interpolation, event definitions, and all serialization logic. Re-exported by naive-client so downstream consumers get everything.

naive-client: Library crate containing the full engine. Re-exports naive-core. Contains the wgpu renderer, Kira audio, input capture, UI overlay, Rapier 3D physics, Lua scripting, GPU horde simulation shaders, skeletal animation, character controller, prediction engine, interpolation buffer, PBR materials, mesh loading, Gaussian splatting, CLI argument parsing, and command socket server. 25 modules total.

naive-runtime: Binary crate. A thin CLI entry point that depends on naive-client. Produces three binaries: naive-runtime (the main engine binary), naive (convenience alias), and naive_mcp (MCP JSON-RPC server for AI agent integration).

toml
# crates/naive-runtime/Cargo.toml

[dependencies]

naive-client = { workspace = true }

[[bin]]

name = "naive-runtime"

path = "src/main.rs"

[[bin]]

name = "naive"

path = "src/main.rs"

The server binary (naive-server) is specified in the companion Platform PRD.

4.2 Rendering Philosophy: Client-Side Rendering

The engine renders locally on the client's GPU. If connected to a server, the server never touches a pixel โ€” it sends state deltas, the client renders them.

Server-side rendering: 100 worlds ร— 10 players ร— $0.25/hr GPU = $180,000/month

Client-side rendering: 100 worlds on 2-core VPS = $25/month

Ratio: 9,000:1 cost advantage

This is what Minecraft, Roblox, Fortnite, and every successful multiplayer game uses.

4.3 Scene YAML as World Format

A "world" is a directory of files: YAML scenes, Lua scripts, YAML materials, glTF meshes, audio files, SLANG shaders, and VAT textures.

project/

scenes/ โ€” YAML scene definitions

logic/ โ€” Lua game scripts

assets/

materials/ โ€” PBR material YAML files

meshes/ โ€” glTF 3D models (including skinned meshes)

splats/ โ€” Gaussian splatting .ply files

vat/ โ€” Vertex Animation Textures (.exr)

audio/ โ€” MP3/WAV/OGG audio files

shaders/

passes/ โ€” SLANG render pass shaders

compute/ โ€” SLANG compute shaders (horde sim, etc.)

modules/ โ€” Shared SLANG modules

4.4 Data Flow (Single-Player / naive-runtime)

Player presses "W"

โ†’ Input system captures key event

โ†’ Character controller processes input: move forward 0.2m

โ†’ Rapier physics: collision check, gravity, grounding

โ†’ Lua script: game logic (stamina drain, footstep sound trigger)

โ†’ GPU horde sim: compute shaders update 50,000 entities

โ†’ ECS updated: player position, horde positions, animation states

โ†’ Renderer: deferred pipeline draws frame

โ†’ Audio: spatial sound, footstep SFX

โ†’ Total frame time: <16ms at 60 FPS

4.5 Data Flow (Multiplayer / naive-client + Platform Server)

Player presses "W"

โ†’ Client prediction: character controller moves player locally (instant)

โ†’ Client sends input to server via WebRTC DataChannel

โ†’ Server processes authoritatively, broadcasts delta to all clients

โ†’ Client compares prediction to server state

โ†’ Match (95%): discard prediction buffer

โ†’ Mismatch (5%): rewind to server state, replay inputs

โ†’ Other players: interpolated between last two server states

โ†’ GPU horde sim: runs on client, parameterized by server-sent flow field

โ†’ Perceived input latency: <16ms (one frame)

4.6 Client-Side Prediction Engine

Included in naive-client for use when connected to a server. Also usable in naive-runtime for consistent behavior.

What is predicted:

  • Player position (character controller movement)
  • Player rotation (camera/aim direction)

What is NOT predicted:

  • Weapon fire (server-authoritative)
  • Damage taken/dealt
  • Inventory changes
  • Horde entity positions (client-simulated independently)
  • Other players (interpolated, not predicted)

Reconciliation: On receiving server state, compare predicted position to server position for the acknowledged tick. If diverged, rewind to server state and replay all unacknowledged inputs. This happens ~5% of frames (usually due to collisions with other players that the client couldn't predict).

4.7 Entity Interpolation

Other entities (players, NPCs, vehicles) are rendered by interpolating between the two most recent states received from the server:

Server sends position at tick 100: [43.0, 0, 87.0]

Server sends position at tick 101: [43.2, 0, 87.1]

Client renders at visual time = tick 100.5:

position = lerp([43.0, 0, 87.0], [43.2, 0, 87.1], 0.5)

= [43.1, 0, 87.05]

The client renders one tick behind the server (configurable). Extrapolation fallback if a packet is lost: linear extrapolation with exponential decay.


5. What Already Exists (v1.0 Foundation)

16 phases built and working:

SystemStatusImplementation
Window + InputDonewinit 0.30, keyboard/mouse events
Scene GraphDoneYAML scenes with entity/component definitions
ECSDonehecs with Transform, MeshRenderer, Camera, Light, Hidden, EntityId
Deferred RenderingDone8-stage pipeline: Shadow โ†’ G-Buffer โ†’ Splat โ†’ Lighting โ†’ Bloom โ†’ Tonemap โ†’ FXAA โ†’ UI
Gaussian SplattingDone.ply loader, integrated into deferred pipeline
PBR MaterialsDoneCook-Torrance GGX, metallic/roughness/emissive
Shadow MappingDoneDirectional shadow maps with PCF soft shadows
Post-ProcessingDoneBloom, tone mapping, FXAA
PhysicsDoneRapier 3D: rigid bodies, colliders, joints, gravity
ScriptingDonemlua (Lua 5.4): per-entity scripts, full API
AudioDoneKira 0.9: music, SFX, fade-in/out, MP3/WAV/OGG
UI OverlayDoneImmediate-mode 2D: text, rects, screen flash
Entity CommandsDoneRuntime spawn/destroy/scale/visibility from Lua
MCP ServerDoneJSON-RPC over stdio
Event BusDoneTyped publish/subscribe
Headless ModeDone--headless runs without window
Shader PipelineDoneSLANG โ†’ WGSL, YAML-defined render pipeline DAG
Procedural MeshesDoneSphere, cube, plane at runtime

16 demo scenes exercising all systems. 20 features DONE.

Tier 1 Gameplay Primitives (v0.1.2)

Implemented in v0.1.2. These are engine-level systems, not game-specific code:

SystemStatusImplementation
Health/DamageDoneHealth ECS component, entity.damage() / entity.heal() Lua API, on_damage / on_death callbacks
Hitscan APIDonephysics.hitscan() returns entity ID + hit point + normal, self-exclusion
Collision DamageDoneCollisionDamage component, automatic damage on physics contact, owner-skip for projectiles
Projectile SystemDoneentity.spawn_projectile() spawns physics-driven projectiles with velocity, gravity, lifetime, auto-damage via collision
Third-Person CameraDoneCameraMode::ThirdPerson with configurable distance/height/pitch, wall collision via raycast

6. Intelligence Layer (Engine-Side)

These AI capabilities run in the engine (client or runtime), not on the server.

6.1 Natural Language Compiler

Text descriptions โ†’ complete YAML + Lua files via MCP tool:

User:  "I want a 3D snake game on a neon grid with pulsing music"

NL Compiler:

โ†’ scenes/snake.yaml

โ†’ logic/snake_controller.lua

โ†’ logic/food_spawner.lua

โ†’ materials/neon_grid.yaml

โ†’ materials/snake_body.yaml

Target: >80% first-attempt correct scene generation.

6.2 Generative Gaussian Splatting (Gen-3DGS)

Text descriptions โ†’ 3D Gaussian splat assets:

TierGaussiansTimeQuality
Preview~10K2-5sDraft
Standard~100K15-30sGood
High~500K1-3minExcellent
Cinematic~2M5-15minPhotorealistic

6.3 Neural Render Passes

Portions of the render pipeline replaced with differentiable, trainable neural networks:

yaml
passes:

- name: style_transfer

type: neural

weights: ghibli_style.neural_shader

inputs: [color_buffer, depth_buffer]

output: styled_color

- name: super_resolution

type: neural

weights: 2x_upscale.neural_shader

inputs: [styled_color]

output: final_color

Use cases: style transfer, ambient occlusion estimation, denoising, super-resolution. Performance target: >30 FPS on M1 MacBook with one neural pass active.


7. Skeletal Animation System (NEW in v5.0)

glTF skinned mesh support with animation state machines.

7.1 Pipeline

glTF file โ†’ Skeleton extraction (joints, bones, inverse bind matrices)

โ†’ Animation clip loading (keyframes per joint per clip)

โ†’ Runtime: Animation state machine drives blend weights

โ†’ GPU skinning (vertex shader or compute shader)

7.2 Animation State Machine (YAML-Defined)

yaml
animation_state_machine:

states:

idle:

clip: animations/idle.gltf

loop: true

transitions:

- to: run

condition: speed > 0.5

- to: jump

condition: is_airborne

run:

clip: animations/run.gltf

loop: true

blend_parameter: speed

transitions:

- to: idle

condition: speed < 0.1

- to: jump

condition: is_airborne

- to: sprint

condition: speed > 5.0

jump:

clip: animations/jump.gltf

loop: false

transitions:

- to: fall

condition: velocity_y < 0

fall:

clip: animations/fall.gltf

loop: true

transitions:

- to: land

condition: is_grounded

land:

clip: animations/land.gltf

loop: false

duration: 0.3

transitions:

- to: idle

condition: animation_complete AND speed < 0.1

- to: run

condition: animation_complete AND speed > 0.5

Animation blending: Crossfade between states (configurable duration, default 0.15s). Upper body and lower body can play different animations simultaneously (layered animation).


8. GPU Compute Entity Simulation (NEW in v5.0)

The system that makes 50,000+ on-screen enemies possible. This runs entirely on the client GPU.

8.1 Architecture

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

โ”‚ GPU COMPUTE PIPELINE โ”‚

โ”‚ โ”‚

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

โ”‚ โ”‚ Spawn โ”‚โ”€โ”€>โ”‚ Simulation โ”‚โ”€โ”€>โ”‚ Animation โ”‚ โ”‚

โ”‚ โ”‚ Buffer โ”‚ โ”‚ Compute โ”‚ โ”‚ (VAT sample) โ”‚ โ”‚

โ”‚ โ”‚ โ”‚ โ”‚ Shader โ”‚ โ”‚ โ”‚ โ”‚

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

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

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

โ”‚ โ”‚ Neighbor โ”‚ โ”‚ Instance โ”‚ โ”‚

โ”‚ โ”‚ Grid โ”‚ โ”‚ Render Buffer โ”‚ โ”‚

โ”‚ โ”‚ (collision) โ”‚ โ”‚ (transforms) โ”‚ โ”‚

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

โ”‚ โ”‚

โ”‚ Inputs: โ”‚

โ”‚ - Flow field texture (128ร—128, for pathfinding) โ”‚

โ”‚ - Spawn commands (position, count, type) โ”‚

โ”‚ - Global parameters (max_speed, damage, etc.) โ”‚

โ”‚ โ”‚

โ”‚ Outputs: โ”‚

โ”‚ - Per-instance transform buffer โ†’ GPU instanced draw โ”‚

โ”‚ - Per-instance animation state (VAT time offset) โ”‚

โ”‚ - Per-instance health (for damage flash shader) โ”‚

โ”‚ - Player damage events (readback to CPU) โ”‚

โ”‚ โ”‚

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

8.2 Compute Shader Pipeline

Each frame, the GPU runs a sequence of compute dispatches:

  • Spawn โ€” New entities written into free slots. Atomic counter free-list tracks available slots.
  • Flow Field Sample โ€” Each entity samples the flow field texture for desired velocity.
  • Steering โ€” Separation, alignment, cohesion from neighbor grid. Combined with flow field.
  • Neighbor Grid Build โ€” Entities binned into spatial grid via atomic scatter.
  • Collision Resolution โ€” Iterate neighbors, apply separation forces, apply damage to player contact volumes.
  • Integration โ€” Apply velocity to position. Clamp to world bounds. Update animation state.
  • Death and Cleanup โ€” Health โ‰ค 0 โ†’ marked dead, slot returned to free list, death event buffered.
  • Instance Buffer Write โ€” Living entities write transform + anim state to render buffer. Compaction removes gaps.
  • 8.3 Vertex Animation Textures (VAT)

    Skeletal animation doesn't scale to 50,000 entities. VAT bakes animation into textures:

    Baking (offline):

    glTF with skeletal animation
    

    โ†’ Sample vertex positions at each frame of each clip

    โ†’ Pack into texture: X = vertex index, Y = frame, RGBA = position offset + normal

    โ†’ Output: animation_atlas.exr (e.g., 1024 vertices ร— 150 frames ร— RGBA16F)

    Runtime (GPU, per-entity):

    vertex_position = base_mesh_position + texture_sample(vat_texture, vertex_id, anim_time)
    

    LOD levels:

    DistanceMeshAnimationDraw
    < 30mFull mesh (LOD0)VAT samplingGPU instanced
    30-80mSimplified mesh (LOD1, 50% triangles)VAT samplingGPU instanced
    80m+Billboard spriteSprite sheetBillboard batch

    8.4 YAML Configuration

    yaml
    gpu_entity_system:
    

    name: goblin_horde

    max_entities: 65536

    mesh: assets/meshes/goblin_lod0.gltf

    mesh_lod1: assets/meshes/goblin_lod1.gltf

    mesh_lod2: billboard

    lod_distances: [30.0, 80.0]

    animation:

    type: vat

    texture: assets/vat/goblin_walk_run_die.exr

    clips:

    idle: { start: 0, end: 30 }

    walk: { start: 31, end: 60 }

    run: { start: 61, end: 90 }

    attack: { start: 91, end: 120 }

    die: { start: 121, end: 150 }

    simulation:

    compute_shader: shaders/horde_sim.slang

    collision: neighbor_grid

    grid_cell_size: 2.0

    pathfinding: flow_field

    flow_field_resolution: 128

    separation_radius: 1.0

    cohesion_radius: 5.0

    max_speed: 8.0

    health: 100

    damage_on_contact: 10

    spawning:

    wave_system: true

    initial_count: 1000

    spawn_rate: 200

    spawn_radius: 80.0

    max_alive: 50000

    8.5 SLANG Compute Shader

    slang
    struct HordeEntity {
    

    float3 position;

    float3 velocity;

    float health;

    float anim_time;

    uint type; // 0 = melee, 1 = ranged, 2 = elite

    uint state; // 0 = alive, 1 = dying, 2 = dead

    };

    RWStructuredBuffer<HordeEntity> entities;

    Texture2D<float2> flow_field;

    RWTexture2D<uint> neighbor_grid_counts;

    [numthreads(256, 1, 1)]

    void cs_simulate(uint3 tid : SV_DispatchThreadID) {

    uint idx = tid.x;

    if (idx >= alive_count) return;

    HordeEntity e = entities[idx];

    if (e.state != 0) return;

    // Sample flow field for pathfinding

    float2 grid_uv = e.position.xz / world_size;

    float2 desired_velocity = flow_field.SampleLevel(linear_sampler, grid_uv, 0);

    // Neighbor query for separation

    int2 cell = int2(e.position.xz / grid_cell_size);

    float3 separation = float3(0);

    // ... iterate neighbors, compute separation force

    // Combine steering forces

    float3 steering = float3(desired_velocity.x, 0, desired_velocity.y) * max_speed

    + separation * separation_weight;

    // Integrate

    e.velocity = lerp(e.velocity, steering, dt * 5.0);

    e.position += e.velocity * dt;

    // Update animation based on speed

    float speed = length(e.velocity);

    e.anim_time += dt speed anim_speed_scale;

    entities[idx] = e;

    }


    9. Character Controller (NEW in v5.0)

    Capsule collider-based movement using Rapier:

    yaml
    character_controller:
    

    capsule:

    height: 1.8

    radius: 0.3

    movement:

    walk_speed: 5.0

    sprint_speed: 9.0

    crouch_speed: 2.5

    jump_force: 8.0

    gravity: -20.0

    air_control: 0.3

    ground_friction: 8.0

    air_friction: 0.5

    camera:

    mode: third_person # or first_person

    distance: 4.0

    height_offset: 1.5

    collision: true

    spring_arm: true

    sensitivity: 2.0

    pitch_limits: [-60, 75]

    Touch input mapping (mobile):

    • Left virtual joystick: movement
    • Right virtual joystick: camera/aim
    • Jump button, fire button, weapon switch swipe

    10. Weapon System (NEW in v5.0)

    Weapons defined in YAML. In single-player (naive-runtime), hit detection runs locally. In multiplayer, hit detection is server-authoritative (see Platform PRD).

    10.1 Weapon Types

    yaml
    weapons:
    

    assault_rifle:

    type: hitscan

    fire_rate: 10.0

    damage: 22

    range: 100.0

    spread: 2.5

    recoil:

    vertical: 1.5

    horizontal: 0.3

    recovery: 5.0

    magazine: 30

    reload_time: 2.0

    headshot_multiplier: 2.0

    rocket_launcher:

    type: projectile

    fire_rate: 1.0

    damage: 120

    splash_radius: 5.0

    splash_falloff: linear

    projectile:

    speed: 40.0

    gravity: true

    lifetime: 5.0

    mesh: assets/meshes/rocket.gltf

    trail_effect: assets/effects/rocket_trail.yaml

    magazine: 1

    reload_time: 3.0

    flamethrower:

    type: continuous

    damage_per_second: 80

    range: 15.0

    cone_angle: 30.0

    fuel: 100

    fuel_drain: 20

    ignite_chance: 0.3

    10.2 Hit Detection (Single-Player)

    Player fires weapon
    

    โ†’ Raycast from player position in aim direction

    โ†’ Check intersection with ECS entities (Rapier colliders)

    โ†’ Apply damage to hit entity

    โ†’ Play hit effect at impact point

    In multiplayer, the server performs the raycast and applies damage. The client plays cosmetic effects locally. See Platform PRD Section 7 for lag compensation and server-authoritative hit registration.


    11. Vehicle System (NEW in v5.0)

    Vehicles are Rapier rigid bodies:

    yaml
    vehicles:
    

    war_buggy:

    type: wheeled

    physics:

    mass: 1500

    wheels: 4

    suspension_stiffness: 30.0

    max_speed: 25.0

    acceleration: 12.0

    brake_force: 20.0

    turn_rate: 2.5

    health: 500

    seats:

    driver:

    position: [0, 0.8, 0.3]

    controls: driving

    gunner:

    position: [0, 1.5, -0.5]

    controls: turret

    weapon: mounted_machine_gun

    mounted_machine_gun:

    type: hitscan

    fire_rate: 15.0

    damage: 15

    range: 80.0

    overheat: 5.0

    cooldown: 2.0

    mesh: assets/meshes/war_buggy.gltf

    enter_radius: 3.0

    truck:

    type: wheeled

    physics:

    mass: 5000

    wheels: 6

    max_speed: 18.0

    acceleration: 6.0

    health: 1200

    damage_on_collision: 80

    seats:

    driver:

    position: [0, 1.5, 1.0]

    controls: driving

    mesh: assets/meshes/truck.gltf

    Press E near vehicle โ†’ mount. Press E while mounted โ†’ dismount. Vehicles damage horde enemies on collision.


    12. Inventory and Loadout (NEW in v5.0)

    yaml
    inventory:
    

    weapon_slots:

    primary: 1

    secondary: 1

    heavy: 1

    melee: 1 # always available

    consumable_slots: 4

    pickups:

    health_pack:

    heal: 50

    mesh: assets/meshes/health_pack.gltf

    respawn_time: 30.0

    shield_cell:

    shield: 25

    mesh: assets/meshes/shield_cell.gltf

    respawn_time: 20.0

    ammo_box:

    ammo: 60

    mesh: assets/meshes/ammo_box.gltf

    respawn_time: 15.0


    13. Large World Support (NEW in v5.0)

    13.1 Chunk-Based World Streaming

    yaml
    world_streaming:
    

    chunk_size: 64.0

    load_radius: 3

    unload_radius: 5

    Chunks are individual YAML scene files loaded/unloaded based on player position.

    13.2 LOD System

    • Mesh LOD: glTF meshes with multiple LOD levels, selected by screen-space size
    • Gaussian Splat LOD: Progressive pruning โ€” drop small/transparent Gaussians at distance
    • Horde LOD: Full mesh โ†’ simplified mesh โ†’ billboard (Section 8.3)

    13.3 Occlusion Culling

    Frustum culling + optional Hi-Z occlusion culling for complex scenes.


    14. Proof Game: HAVOC

    HAVOC is a 3D Vampire Survivors-style horde survival game with vehicle combat. It runs as single-player on naive-runtime or as 1-4 player co-op when connected to the platform.

    14.1 Why HAVOC

    The game "There Are Millions of Goblins" (Unreal Engine 5, Niagara GPU simulation) demonstrated 50,000 physics-driven enemies with Vampire Survivors-style gameplay fused with vehicle combat. HAVOC proves nAIVE can match this:

    SystemHow HAVOC Proves ItEngine Tier
    Health/damage/hitscanWeapon damage, enemy death, collision damageTier 1 (DONE)
    ProjectilesPhysics-driven weapon projectilesTier 1 (DONE)
    Dynamic buffer + pooling200+ CPU entities without crashes, horde poolingTier 2
    Particle systemKill effects, weapon VFX, boost trailsTier 2
    Event subscriptionCross-script game events (kills, waves, pickups)Tier 2
    GPU compute entities50,000+ goblins on GPUTier 3
    Neighbor-grid collisionsGoblins collide with each other and playersTier 3
    VAT animation50,000 goblins animated via vertex texturesTier 4
    Skeletal animationPlayer character with full state machineTier 4
    VehiclesWar buggy, truck with collision damageTier 5

    14.2 Game Design

    Concept: Survive increasingly intense waves of goblin hordes. On foot or in vehicles.

    Setting: Arena-scale map (~500m ร— 500m) with ruins, open fields, vehicle spawn points, elevation changes. Gothic-industrial aesthetic.

    Core Loop:

    Explore โ†’ Find weapons/vehicles โ†’ Survive wave โ†’ Brief respite โ†’ Harder wave โ†’ Repeat
    

    โ†’ Die โ†’ Score screen โ†’ Play again

    Wave progression:

    WaveCountTypesSpecial
    1-31K โ†’ 5KMelee onlyTutorial, plentiful health drops
    4-65K โ†’ 15KMelee + rangedRanged goblins, first vehicle
    7-915K โ†’ 30K+ elite3x health elites, rarer pickups
    1030K โ†’ 50K+ bossGoblin King (CPU ECS, full AI)
    EndlessScalesDynamicAI Director controls everything

    Player abilities: Sprint (stamina), dodge roll (i-frames), weapon swap, vehicle mount/dismount, AoE ground slam (cooldown, unlocked wave 3).

    14.3 Performance Targets

    MetricTarget
    Horde entities on screen50,000+
    Frame rate (desktop, RTX 3060)60 FPS
    Frame rate (browser, WebGPU)30+ FPS
    Frame rate (M1 MacBook)45+ FPS

    15. Platform Targets

    PlatformGPU BackendStatus
    macOS (Intel + Apple Silicon)MetalDONE (primary dev)
    Windows (x64)Vulkan / DX12Supported
    Linux (x64)VulkanSupported
    Browser (WebGPU + WASM)WebGPUPlanned
    Android (ARM64)VulkanPlanned
    iOS (ARM64)MetalPlanned

    16. Licensing

    MIT License

    nAIVE engine (naive-core, naive-client, naive-runtime) is licensed under the MIT License.

    MIT License
    
    

    Copyright (c) 2026 Mark Ollila

    Permission is hereby granted, free of charge, to any person obtaining a copy

    of this software and associated documentation files (the "Software"), to deal

    in the Software without restriction, including without limitation the rights

    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

    copies of the Software, and to permit persons to whom the Software is

    furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all

    copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

    SOFTWARE.

    What this means:

    • Use nAIVE for any purpose โ€” personal, commercial, educational
    • Modify the source code however you want
    • Sell games built with nAIVE โ€” owe nothing, no royalties, no revenue share
    • Fork nAIVE and build a competing engine โ€” that's fine
    • Include nAIVE in proprietary software โ€” that's fine
    • No CLA required for contributions

    The server (naive-server) is licensed separately under BSL 1.1. See the companion Platform PRD for details. You do not need the server to build and ship games.

    Dependency Compatibility

    DependencyLicenseCompatible
    wgpuMIT/Apache-2.0Yes
    hecsMIT/Apache-2.0Yes
    RapierApache-2.0Yes
    KiraMIT/Apache-2.0Yes
    mluaMITYes
    serdeMIT/Apache-2.0Yes
    shader-slangMITYes

    No GPL dependencies. All dependencies are MIT or Apache-2.0 compatible.


    17. New ECS Components (v5.0)

    All v4.0 components remain. v5.0 adds:

    Tier 1 โ€” Implemented (v0.1.2)

    ComponentPurpose
    healthHealth points with current/max, dead flag. Engine fires on_damage/on_death callbacks.
    collision_damageAuto-applies damage on physics contact. Configurable damage amount and destroy_on_hit.
    projectileRuntime-spawned physics projectile with damage, lifetime, owner tracking.
    camera_modeFirstPerson or ThirdPerson { distance, height_offset, pitch_min, pitch_max }. Wall collision via raycast.
    character_controllerCapsule movement: walk, sprint, jump, step height

    Tier 2 โ€” Production Foundations (planned)

    ComponentPurpose
    particle_emitterBillboard particle source with rate, lifetime, velocity, color, size curves
    pool_memberMarks entity as belonging to a named pool for acquire/release lifecycle

    Tier 3+ โ€” Future

    ComponentPurpose
    skeletal_meshglTF skinned mesh with bone hierarchy
    animation_stateCurrent clip, blend weight, state machine ref
    weapon_holderEquipped weapons, current weapon, ammo counts
    vehicle_seatAssociates entity with a vehicle seat
    vehicle_physicsWheeled vehicle rigid body configuration
    horde_configGPU compute horde parameters for this world
    prediction_stateUnacknowledged input buffer for reconciliation
    interpolation_bufferLast N server states for smooth rendering
    agent_brainLLM NPC personality, memory slots, inference tier (server runs inference; see Platform PRD Section 10)

    18. Implementation Roadmap

    Phase 1 (Weeks 1-4): Snake Sweeper + Headless Mode

    WeekDeliverable
    1Snake Sweeper core gameplay
    2Snake Sweeper polish: particles, heartbeat, HUD
    3Headless mode improvements for testing
    4State delta encoding/decoding in naive-core

    Phase 1.5 (Informed by Snake Sweeper Devlog): Lua API Polish

    Snake Sweeper was built by Claude Code (Opus 4.6) in a single session using only naive init + CLAUDE.md as documentation. The devlog identified concrete API gaps that blocked or complicated the build. These are small, focused additions that improve the game development experience without architectural changes.

    APIPriorityRationale
    entity.get_rotation(id) -> pitch, yaw, rollHighComplete the transform API. set_rotation exists but get_rotation doesn't. Any game with dynamic rotation needs manual tracking without this.
    entity.exists(id) -> boolHighNo way to check if an entity is alive. entity.destroy() is deferred to end-of-frame, creating a race condition with entity.spawn() in the same frame. exists() enables defensive programming.
    entity.set_base_color(id, r, g, b)HighOnly emission/roughness/metallic can be overridden at runtime. Base color requires pre-authored materials, limiting dynamic visual state changes. The devlog used emission-only tinting as a workaround, producing a glow-heavy aesthetic.
    camera.world_to_screen(x, y, z) -> sx, sy, visibleHighEssential for any game that overlays UI on 3D entities (damage numbers, name tags, Minesweeper numbers). The devlog manually calculated screen projection from camera FOV โ€” 5 lines of fragile math that breaks with camera movement.
    input.any_just_pressed() -> boolMediumNo "any key" query. Splash screens require checking every mapped action individually.
    ui.text_width(text, font_size) -> pixelsMediumNo text measurement. Centering text requires magic numbers tuned by eye.
    entity.destroy_by_prefix(prefix)MediumBulk entity cleanup. Procedural games (grids, particles) track hundreds of entity IDs in arrays for cleanup.
    math.lerp(a, b, t) -> numberLowUsed constantly for animations, fades, easing. Currently written inline everywhere.

    Key Discovery: Deferred entity.destroy() Behavior

    entity.destroy(id) is queued and executed at end-of-frame. If entity.spawn(id) is called in the same frame after entity.destroy(id), the spawn is a no-op (entity still exists), and the deferred destroy then removes it. This caused invisible entities and immediate deaths on level transitions. The safe pattern is: never destroy entities you might re-use; hide them with set_visible(false) and reposition. This must be documented in CLAUDE.md, the Game Development Guide, and engine docstrings.

    Phase 2 (Weeks 5-12): Intelligence Layer

    WeeksDeliverable
    5-6NL Compiler v1 via Claude API MCP tool
    7-8Gen-3DGS preview tier: text โ†’ Gaussian splat
    9-10Neural shader prototype: style transfer pass
    11-12WebGPU/WASM browser build

    Phase 3: Engine Systems โ€” Tiered by Game Capability

    The engine provides generic systems and Lua/YAML APIs. Game developers (human or AI) build content, logic, and game rules on top. HAVOC is a proof game built by a developer using these engine systems โ€” it is not built into the engine.

    Tier 1 โ€” Gameplay Primitives (unblocks any action game) DONE v0.1.2

    These systems let a game developer build a playable shooter/brawler/survival game at CPU entity scale. Implemented in engine version 0.1.2.

    SystemEngine ProvidesGame Dev Uses Via
    Health/Damage componentsGeneric Health ECS component. Engine applies damage, tracks death state, fires on_damage/on_death callbacks.Lua: entity.get_health(id), entity.damage(id, amount), entity.heal(id, amount). YAML: health: { max: 100 } on entities.
    Projectile systemEngine spawns physics-driven projectile entities with velocity, gravity, lifetime, auto-damage via CollisionDamage.Lua: entity.spawn_projectile(owner, mesh, material, pos, dir, speed, damage, lifetime, gravity)
    Third-person cameraCamera mode with configurable offset, collision-aware pullback via Rapier raycast.YAML: camera: { mode: third_person, distance: 4.0, height_offset: 1.5, pitch_limits: [-60, 75] }
    Hitscan APIRaycast from origin in direction, returns hit entity + point + normal. Self-exclusion built in.Lua: physics.hitscan(ox, oy, oz, dx, dy, dz, range) returning hit, entity_id, distance, hx, hy, hz, nx, ny, nz
    Collision damageCollisionDamage component auto-applies damage on physics contact. Projectile owner-skip prevents self-damage.YAML: collision_damage: { damage: 25, destroy_on_hit: false }. Engine handles detection automatically.

    Tier 2 โ€” Production Foundations (makes nAIVE a shippable engine)

    Informed by the HAVOC dev log. A complete Vampire Survivors prototype was built in nAIVE in a single session, validating Tier 1 systems. But the developer hit hard walls โ€” engine crashes from entity overflow, mandatory workarounds for deferred destroy, no VFX, no runtime queries. These aren't missing features; they're the difference between "prototyping engine" and "real engine." The HAVOC developer's verdict: "If I were pitching to a publisher, this nAIVE prototype would be the vertical slice demo. Then we'd rebuild it in a real engine." Tier 2 ensures they don't have to.

    SystemEngine ProvidesGame Dev Uses Via
    Dynamic GPU instance bufferInstance buffer grows automatically when entity count exceeds current capacity. No hard 256-entity ceiling. Graceful warning at configurable thresholds.Transparent โ€” game dev spawns entities freely. Engine handles buffer resizing. Target: 4K+ CPU entities before GPU becomes the bottleneck, not an arbitrary buffer.
    Safe entity lifecycleDeferred destroy processes before spawns within the same frame. Spawn+destroy in one frame no longer doubles buffer usage. Optional entity.destroy_immediate() for cases where the dev needs guaranteed slot reclamation.Lua: existing entity.destroy() becomes safe by default. entity.destroy_immediate(id) for explicit control.
    Built-in entity poolingEngine-managed object pools. Pre-allocate N entities of a type, acquire/release without spawn/destroy overhead. Zero GPU buffer churn.Lua: entity.pool_create(name, count, mesh, material), entity.pool_acquire(name) returns id, entity.pool_release(id). YAML: pool: { name: "goblins", count: 200, mesh: ..., material: ... }
    Particle systemLightweight 2D billboard particles with lifetime, velocity, gravity, color fade, size curve. GPU-instanced rendering from a dedicated particle buffer (separate from entity buffer).Lua: particles.emit(x, y, z, { count: 20, lifetime: 0.5, speed: 3.0, color: {1,1,0}, gravity: -5 }). YAML: particle_emitter: { rate: 50, lifetime: 1.0, ... } on entities.
    Runtime entity queriesQuery entities by tag at runtime. Returns array of entity IDs matching a tag.Lua: scene.find_by_tag(tag) returns {id1, id2, ...}. Eliminates hardcoded ID arrays in game scripts.
    Event subscriptionLua scripts can subscribe to named events and receive callbacks. Completes the event bus (currently write-only from Lua).Lua: events.on("enemy_killed", function(data) ... end), events.emit("enemy_killed", { id = eid, killer = pid }). Cross-script communication without polling the game table.

    Tier 3 โ€” GPU Scale (unblocks 50K entities)

    These systems move entity simulation from CPU to GPU. Game developers configure behavior via YAML and SLANG compute shaders.

    SystemEngine ProvidesGame Dev Uses Via
    GPU compute entity systemGeneric compute pipeline: storage buffers for entity data, configurable dispatch, spawn/death slot management with atomic free-list.YAML: gpu_entity_system: { max_entities: 65536, compute_shader: shaders/compute/horde.slang }. Game dev writes SLANG shader for entity behavior.
    GPU neighbor gridSpatial hash built on GPU each frame. Entities binned into cells. Query API for compute shaders.Engine auto-builds grid from entity positions. Game dev's compute shader calls query_neighbors(cell) in SLANG.
    GPU instanced renderingRender 50K+ entities from compute-output transform buffer in one draw call per mesh type.Automatic โ€” engine reads instance buffer written by compute shader. Game dev configures mesh/material in YAML.
    Flow field pathfindingGPU wavefront propagation from target position. 2D grid of direction vectors. Entities sample field for steering.YAML: flow_field: { resolution: 128, cell_size: 4.0 }. Engine recomputes when target moves. Game dev's compute shader samples flow_field_texture.

    Tier 4 โ€” Animation (unblocks animated characters)

    SystemEngine ProvidesGame Dev Uses Via
    Skeletal animationglTF skinned mesh loading (joints, weights, inverse bind matrices). Animation clip parsing. State machine with crossfade blending. GPU skinning.YAML: animation state machine definition (states, transitions, conditions). Lua: entity.set_anim_state(id, "run"), entity.set_anim_param(id, "speed", 5.0)
    VAT loader + rendererLoad baked vertex animation textures (.exr). Vertex shader samples position/normal per frame. Works with GPU instanced rendering.YAML: animation: { type: vat, texture: assets/vat/goblin.exr, clips: { walk: { start: 0, end: 30 } } }

    Tier 5 โ€” Vehicles (unblocks vehicle combat)

    SystemEngine ProvidesGame Dev Uses Via
    Vehicle physicsRapier wheel joints, raycast suspension, engine torque, steering angle, brake force.YAML: vehicle: { wheels: 4, max_speed: 25.0, suspension_stiffness: 30.0 }
    Mount/dismountEngine re-parents player to vehicle seat, switches input context (movement โ†’ driving). Proximity trigger.Lua: vehicle.mount(player_id, vehicle_id, "driver"), vehicle.dismount(player_id). Automatic on interact key near vehicle.
    LOD systemDistance-based mesh switching. Billboard fallback at far distance. Engine selects LOD per frame.YAML: lod: { distances: [30, 80], meshes: [lod0.gltf, lod1.gltf], billboard: sprite.png }

    Implementation Schedule

    PhaseTierWeeksDeliverables
    3aTier 1: Gameplay Primitivesโ€”DONE (v0.1.2) Health/damage, projectiles, third-person camera, hitscan API, collision damage
    3bTier 2: Production Foundations13-18Dynamic instance buffer, safe entity lifecycle, entity pooling, particle system, runtime queries, event subscription
    3cTier 3: GPU Scale19-24GPU compute entity system, neighbor grid, instanced rendering, flow field
    3dTier 4: Animation25-28Skeletal animation + state machine, VAT loader + renderer
    3eTier 5: Vehicles29-32Vehicle physics, mount/dismount, LOD system

    Phase 4: HAVOC โ€” Proof Game (Built by Game Developer Using Engine)

    HAVOC is built entirely in YAML + Lua + SLANG using the engine systems from Phase 3. It validates that the engine APIs are sufficient for a AAA-scale horde survival game. No Rust code is written for HAVOC โ€” if Rust is needed, that's a missing engine system.

    A HAVOC prototype was already built during Tier 1 development using only CPU entities and Lua-side simulation. It validated the gameplay loop (driving, killing, leveling, upgrading) but hit hard limits: 256-entity ceiling, deferred destroy crashes, no VFX. Tier 2 removes these walls. The full HAVOC rebuild on Tier 2+ will prove nAIVE is a production engine, not just a prototyping tool.

    WeeksDeliverableEngine Systems Exercised
    33-34HAVOC core: arena scene, player controller, horde (pooled + particles)Tier 1 (health, hitscan, third-person camera) + Tier 2 (pooling, particles, dynamic buffer, events)
    35-36HAVOC GPU horde: 50K goblin swarm, wave progression, 5 weapon typesTier 3 (GPU entities, flow field) + Tier 4 (skeletal anim for player, VAT for horde)
    37-38HAVOC vehicles + polish: 2 vehicles, LOD, 10-wave campaignTier 5 (vehicles, mount/dismount, LOD)

    19. Technical Specifications

    19.1 Client Requirements

    ComponentMinimumRecommendedHAVOC (50K horde)
    GPUIntel UHD 620Any dedicated GPURTX 3060+
    VRAM512 MB2 GB4 GB+
    RAM512 MB2 GB4 GB
    BrowserChrome 113+Latest stableLatest + WebGPU

    19.2 Performance Targets

    MetricTarget
    Frame rate (Snake Sweeper, M1 MacBook)>60 FPS
    Frame rate (HAVOC, desktop RTX 3060)>60 FPS
    Frame rate (HAVOC, browser WebGPU)>30 FPS
    Horde entity count (desktop)50,000+
    Horde entity count (browser)20,000+
    NL Compiler accuracy>80% first-attempt correct
    Neural shader FPS>30 FPS on M1 with one pass
    WASM binary size<80 MB

    20. Risk Assessment

    RiskSeverityMitigationFallback
    GPU compute portabilityHighSLANG cross-compiles to WGSL, SPIR-V, MetalCPU fallback with 5,000 entities
    50K entities on WebGPUHighAggressive LOD, billboard at distanceCap browser at 20,000
    VAT texture memoryMediumBC6H compression, 3-5 clips per typeRotation-only animation
    WebGPU browser supportMediumWebGL2 fallback rendererNative-first distribution
    SLANG compilation speedLowShader cache (compile once, reuse)Pre-compiled WGSL fallback
    Rapier scaling for vehiclesLowRapier handles hundreds of rigid bodies easilySimplified vehicle physics

    21. Comparison to Existing Engines

    FeaturenAIVE v5.0UnityUnrealGodot
    LicenseMITSubscriptionRoyaltyMIT
    LanguageRustC#C++/BlueprintsGDScript/C#
    World formatYAML + LuaProprietaryProprietarytscn (text)
    AI-generatableNativeLimitedNoPartial
    Gaussian splattingNativePluginPluginNo
    GPU entity sim (50K+)NativeVFX GraphNiagaraNo
    Hot-reload<200ms5-60s10-30s1-3s
    MCP / AI controlNativeNoNoNo
    Neural shadersNative (SLANG)NoNoNo
    Browser targetWebGPU WASMLimitedPixel streamingPlanned

    Appendix A: Existing Codebase Map

    crates/
    

    naive-core/src/

    lib.rs, components.rs, scene.rs, transform.rs, tween.rs, events.rs

    naive-client/src/

    lib.rs โ€” Re-exports naive-core + declares all engine modules

    engine.rs โ€” Core engine loop

    pipeline.rs โ€” Deferred render pipeline

    shader.rs โ€” SLANG โ†’ WGSL compilation

    world.rs โ€” Scene loading, ECS setup

    scripting.rs โ€” Lua runtime

    physics.rs โ€” Rapier 3D

    audio.rs โ€” Kira 0.9

    ui.rs โ€” Immediate-mode 2D overlay

    font.rs โ€” Bitmap font atlas

    command.rs โ€” Command socket server

    cli.rs โ€” CLI arguments

    splat.rs โ€” Gaussian splatting renderer

    material.rs โ€” PBR materials from YAML

    mesh.rs โ€” glTF + procedural meshes

    ... (25 modules total)

    naive-runtime/src/

    main.rs โ€” Thin CLI entry point

    bin/naive_mcp.rs โ€” MCP JSON-RPC server

    naive-server/src/ โ€” (see Platform PRD)

    lib.rs, main.rs

    Appendix B: HAVOC Weapon Stats

    WeaponTypeDamageFire RateRangeMagazineReload
    Assault RifleHitscan2210/s100m302.0s
    ShotgunHitscan (8 pellets)12ร—81.5/s20m62.5s
    Rocket LauncherProjectile120 (splash)1/sโˆž13.0s
    FlamethrowerContinuous80/sโ€”15m100 fuelโ€”
    SwordMelee602/s2mโˆžโ€”
    Mounted MGHitscan1515/s80mโˆž (overheat)2.0s cool

    Appendix C: Glossary

    TermDefinition
    GPU compute entityEntity simulated on the GPU via compute shaders
    VATVertex Animation Texture โ€” baked skeletal animation sampled on GPU
    Neighbor gridGPU-side spatial hash for entity-entity collision queries
    Flow fieldPrecomputed pathfinding grid (each cell stores a direction vector)
    HordeLarge group of GPU compute entities acting as a swarm
    SLANGNVIDIA shader language that cross-compiles to WGSL/SPIR-V/Metal/CUDA
    Gen-3DGSGenerative Gaussian Splatting: text โ†’ 3D splat assets
    Neural passRender pipeline stage implemented as a trained neural network
    LODLevel of Detail โ€” reducing mesh complexity at distance
    Client-side predictionClient simulates local movement before server confirmation
    Entity interpolationSmoothly rendering entities between network state updates
    HAVOCnAIVE v5.0 proof game: horde survival with vehicle combat
    naive-coreMIT library crate: shared types, ECS components, scene format, serialization
    naive-clientMIT library crate: full engine โ€” renderer, audio, input, physics, scripting, UI, all engine modules. Re-exports naive-core
    naive-runtimeMIT binary crate: thin CLI entry point that uses naive-client. Produces naive, naive-runtime, and naive_mcp binaries