An experimental AI-native game engine. Create worlds with YAML, Lua, and natural language.
Built from the ground up in Rust. Worlds are created by AI, rendering happens on your GPU, and everything — scenes, materials, shaders, game logic — is a human-readable file that AI can generate, inspect, and modify.
| Traditional Engine | nAIVE |
|---|---|
| Games are compiled binaries | Worlds are YAML + Lua, generated by AI |
| Authoring requires a visual editor | The AI agent is the editor |
| Shaders are HLSL/GLSL, platform-locked | SLANG shaders cross-compile to any GPU backend |
| 3D assets from art pipelines only | Gaussian splats from text prompts |
| Render pipeline hardcoded in C++ | YAML-defined render pipeline DAG |
| Entity counts limited by CPU | GPU compute swarms: 50,000 goblins in a fight at over 1,000 fps on an M4 Max |
Hot-reload for scenes, shaders, materials and scripts. Reload times depend on scene complexity, assets, hardware and the shader toolchain.
No engine royalties. The core, client, runtime and web crates are MIT licensed. The separate, currently stubbed server crate uses BSL 1.1 with a restriction on commercial managed hosting services; see License.
From a one-paragraph prompt, headless Claude Code (Opus 5.5) built a small original arcade game in nAIVE (scene, Lua gameplay, HUD, game over and six passing Lua tests) in 3.0 minutes for $1.26 at API prices. That's one run, with tests the agent wrote itself. Details, caveats and the script to reproduce it.
| Status | Capabilities |
|---|---|
| Implemented, experimental | Native renderer with forward fallback and optional deferred render DAG; physics, Lua scripting, hot reload, MCP scene control, GPU swarms, local game bundling |
| Prototype | Browser WebGPU clear-canvas demo; it does not yet run native engine scenes or Lua games |
| Stub / planned | Multiplayer hosting, matchmaking, AI Director and naive publish; animation/UI expansion and production hardening |
macOS is the primary development platform. Linux is checked in CI and exercised with software Vulkan by the release smoke test; Windows is not supported. Benchmark figures below describe individual demo runs, not a cross-engine comparison or a general performance guarantee.
brew install poro/tap/naivegit clone https://github.com/poro/nAIVE.git
cd nAIVE
git lfs install --local
git lfs pull
# Download SLANG SDK (required for runtime compilation of Slang shaders)
mkdir -p vendor
# macOS ARM:
curl -L https://github.com/shader-slang/slang/releases/download/v2026.2.2/slang-2026.2.2-macos-aarch64.tar.gz | tar xz -C vendor/
# macOS Intel:
curl -L https://github.com/shader-slang/slang/releases/download/v2026.2.2/slang-2026.2.2-macos-x86_64.tar.gz | tar xz -C vendor/
export SLANG_DIR=$(pwd)/vendor
cargo build --release
# The player that `naive build` ships in game bundles. Build it on its own so
# it stays free of the Slang libraries.
cargo build --release -p naive-playerGit LFS is required for the GLB and audio assets, including meshes embedded by include_bytes!. Install it before building from a clone. For core development without the Slang SDK, use cargo test --workspace --exclude naive-web --no-default-features --locked; native rendering uses built-in WGSL shaders, while Slang hot reload and Slang-defined pipeline passes require the SDK. See development and release checks and asset storage.
The builds produce four binaries in target/release/:
naive— Main CLI for running gamesnaive-runtime— Full engine runtime (same asnaive)naive_mcp— MCP JSON-RPC server for AI agent integrationnaive-player—naivewithout the Slang compiler;naive buildships it inside game bundles
- Rust 1.88+ (for building from source; CI uses Rust 1.100)
- macOS 12+ (Metal). Linux (Vulkan) compiles but is untested. Windows is not supported yet.
- GPU with WebGPU support
# Create a new project
naive init my-game
cd my-game
# Run the default scene
naive run
# Run a specific demo scene
naive run --scene scenes/genesis.yaml
# Run tests
naive testmy-game/
├── naive.yaml # Project config
├── CLAUDE.md # AI agent instructions (Lua API reference)
├── scenes/ # YAML scene definitions
├── logic/ # Lua game scripts
├── assets/
│ ├── meshes/ # .gltf, .glb, .ply (Gaussian splats)
│ ├── materials/ # YAML PBR material definitions
│ ├── textures/ # PNG, JPG, HDR
│ └── audio/ # OGG, WAV
├── shaders/passes/ # SLANG render pass shaders
├── pipelines/ # YAML render pipeline DAG
├── input/bindings.yaml # Input action mappings
├── events/schema.yaml # Event type definitions
└── tests/ # Automated Lua test scripts
- Deferred PBR pipeline (shadow, G-buffer, lighting, bloom, tonemap, FXAA)
- Native Gaussian splatting with depth compositing
- Cascaded shadow maps (four cascades fitted to the camera) with PCF filtering
- Sky backgrounds with image-based lighting (gradient or equirectangular image)
- Frustum culling of the camera passes
- HDR + bloom + ACES tonemapping
- SLANG shaders that cross-compile to WGSL for all GPU backends
- YAML-defined render pipeline DAG — add passes without recompiling
- Rapier 3D physics — rigid bodies, colliders, character controllers
- Health/damage system with
on_damage/on_deathcallbacks - Hitscan raycast API with entity hit detection
- Physics-driven projectiles with auto-damage
- Collision damage component
- Third-person camera with wall collision
- Lua 5.4 with a per-entity environment and no access to the filesystem, the shell or module loading
- CPU and memory limits — a script that runs away is stopped instead of hanging the engine
- 40+ API functions (transform, physics, audio, UI, events, input)
- Hot-reload with state migration via
on_reload() - Lifecycle hooks:
init(),update(dt),on_collision(),on_damage(),on_death()
- Dynamic GPU instance buffer — no more 256-entity ceiling
- Safe entity lifecycle — destroy-before-spawn ordering
- Runtime entity queries by tag —
scene.find_by_tag(),entity.has_tag() - Event subscription from Lua —
events.on("name", callback) - Built-in entity pooling —
entity.pool_acquire()/entity.pool_release() - CPU particle simulation (GPU billboard rendering TBD)
- Text-to-3D pipeline: prompt → 2D image (FLUX.1) → 3D mesh (Hunyuan3D) → engine
- Self-hosted GPU server support (H100/A100 via gateway API)
- HuggingFace Spaces fallback for cloud-based generation
- MCP server for AI agent-driven asset creation
- Automatic smooth normal generation for AI-generated meshes
- glTF/GLB import with vertex color support
- MCP command socket for AI agent control
- Headless test runner for automated playtesting
- Event bus with YAML schema validation
- Spatial audio (Kira)
- File watching with hot-reload for scenes, scripts, shaders, materials
nAIVE can generate 3D game assets from text prompts using AI. The pipeline is:
"red sports car" → FLUX.1 (2D image) → Hunyuan3D (3D GLB mesh) → nAIVE engine
- Copy the environment file and fill in your credentials:
cp .env.example .env- Configure at least one generation backend:
| Variable | Description | Required |
|---|---|---|
GATEWAY_URL |
Your GPU server URL (e.g. http://localhost:8000) |
For self-hosted |
GATEWAY_KEY |
API key for your GPU server | For self-hosted |
HF_TOKEN |
HuggingFace API token (get one) | For HF Spaces |
MODEL_SPACE |
HF Space for 3D generation (e.g. your-username/Hunyuan3D-2mini-Turbo) |
For HF Spaces |
The gateway (self-hosted GPU) is tried first; HuggingFace Spaces is the fallback.
- If using a self-hosted server, open an SSH tunnel:
ssh -L 8000:localhost:8000 -p 2222 ubuntu@<your-server-ip>source .env
node scripts/test_generate_asset.js "red sports car"This saves generated_2d.png and generated_3d.glb into project/assets/meshes/.
nAIVE uses MCP (Model Context Protocol) servers to let AI agents generate assets. Configure them in .mcp.json:
| Server | Purpose | Required env vars |
|---|---|---|
game-asset-generator |
Text-to-3D asset pipeline | HF_TOKEN, MODEL_SPACE, GATEWAY_URL, GATEWAY_KEY |
meshy-ai |
Meshy AI 3D generation | MESHY_API_KEY |
blender |
Blender scene manipulation | None |
naive-core (MIT) Shared types, ECS components, scene format, event bus
│
naive-client (MIT) Full engine: renderer, physics, audio, scripting
│
naive-runtime (MIT) Thin CLI binary (naive, naive-runtime, naive_mcp)
│
naive-server (BSL) Multiplayer hosting, matchmaking, AI Director (stub)
│
naive-web (MIT) Minimal WASM + WebGPU clear-canvas prototype
| Layer | Technology |
|---|---|
| Language | Rust |
| Rendering | wgpu 24 (Metal / Vulkan / DX12 / WebGPU) |
| Shaders | NVIDIA SLANG → WGSL cross-compilation |
| ECS | hecs |
| Physics | Rapier3D 0.22 |
| Scripting | Lua 5.4 (mlua, vendored) |
| Audio | Kira 0.9 |
| Asset formats | glTF, PLY (Gaussian splats), YAML (scenes, materials, pipelines) |
Run any scene with naive run --scene scenes/<name>.yaml:
| Scene | Description |
|---|---|
genesis.yaml |
Full showcase — 65 entities, 24 lights, 5K splats, cinematic camera |
pbr_gallery.yaml |
Metallic/roughness material grid |
neon_dreamscape.yaml |
Emissive materials with pulsing animations |
physics_test.yaml |
Rigid body physics, collisions, gravity |
combat_demo.yaml |
Health/damage, hitscan, projectiles |
third_person_demo.yaml |
Third-person camera orbit with wall collision |
splat_test.yaml |
Gaussian splatting rendering |
cosmic_splats.yaml |
Splats with cinematic camera orbit |
inferno.yaml |
Fire-themed PBR showcase |
void.yaml |
Dark ambient showcase |
titan.yaml |
Large-scale scene with dramatic camera |
ui_demo.yaml |
UI overlay system demo |
audio_test.yaml |
Spatial 3D audio |
tier2_stress_test.yaml |
300+ entities — dynamic GPU buffer growth |
tier2_lifecycle_demo.yaml |
Entity lifecycle, pooling, tag queries |
tier2_particle_demo.yaml |
Particle emitters with orbiting camera |
Every entity can have a Lua script attached. Scripts run in a per-entity sandbox with access to the full engine API.
function init()
self.speed = 5
self.health = 100
end
function update(dt)
-- Move forward
local x, y, z = entity.get_position(_entity_string_id)
entity.set_position(_entity_string_id, x, y, z - self.speed * dt)
-- Hitscan raycast
local hit, id, dist = physics.hitscan(x, y, z, 0, 0, -1, 50)
if hit then
entity.damage(id, 25)
end
-- HUD
ui.text(20, 20, "Health: " .. self.health, 18, 1, 1, 1, 1)
end
function on_damage(amount, source)
self.health = self.health - amount
ui.flash(1, 0, 0, 0.3, 0.2) -- red flash
end
function on_death()
audio.play_sfx(_entity_string_id, "assets/audio/explode.wav", 1.0)
events.emit("enemy.killed", { id = _entity_string_id })
end-- Transform
entity.get_position(id) --> x, y, z
entity.set_position(id, x, y, z)
entity.set_rotation(id, pitch, yaw, roll)
-- Combat
entity.get_health(id) --> current, max
entity.damage(id, amount)
entity.heal(id, amount)
physics.hitscan(ox,oy,oz, dx,dy,dz, range) --> hit, id, dist, px,py,pz, nx,ny,nz
entity.spawn_projectile(owner, mesh, mat, pos, dir, speed, dmg, lifetime, gravity)
-- Queries (Tier 2)
scene.find_by_tag(tag) --> { id1, id2, ... }
entity.has_tag(id, tag) --> bool
entity.add_tag(id, tag)
entity.remove_tag(id, tag)
-- Events (Tier 2)
events.emit("event.name", { data })
events.on("event.name", function(e) ... end)
-- Pooling (Tier 2)
entity.pool_acquire(name) --> id or nil
entity.pool_release(id)
-- Materials
entity.set_base_color(id, r, g, b)
entity.set_emission(id, r, g, b)
entity.set_roughness(id, value)
-- UI
ui.text(x, y, text, size, r, g, b, a)
ui.rect(x, y, w, h, r, g, b, a)
ui.flash(r, g, b, a, duration)
-- Audio
audio.play_sfx(id, path, volume)
audio.play_music(path, volume, fade_in)
-- Input
input.pressed(action) --> bool
input.just_pressed(action) --> boolScenes are YAML files that define entities with components:
name: "My Scene"
settings:
ambient_light: [0.2, 0.2, 0.3]
gravity: [0, -9.81, 0]
entities:
- id: player
tags: [player, team_a]
components:
transform:
position: [0, 1, 0]
mesh_renderer:
mesh: assets/meshes/character.gltf
material: assets/materials/hero.yaml
character_controller:
height: 1.8
radius: 0.3
health:
max: 100
script:
source: logic/player.lua
- id: enemy_goblin
tags: [enemy, goblin]
components:
transform:
position: [10, 1, 5]
mesh_renderer:
mesh: procedural:sphere
material: assets/materials/enemy_red.yaml
collider:
shape: sphere
radius: 0.5
health:
max: 30
collision_damage:
damage: 10
destroy_on_hit: true
script:
source: logic/goblin_ai.luaDevelopment follows a tiered system, each tier validated by proof-of-concept games:
| Tier | Systems | Status |
|---|---|---|
| 1 | Health, hitscan, projectiles, collision damage, third-person camera | Done (v0.1.2) |
| 2 | Dynamic GPU buffer, entity pooling, particles, tag queries, events | Done (v0.1.4) |
| 2.5 | Physics & Scene API — impulse/force, CCD, collider materials, scene loading, camera shake | Done (v0.1.7) |
| 2.7 | DX & Code Quality — physics hot-reload, pipeline modularization, debug wireframes, kinematic bodies, convex decomposition | Done (v0.1.15) |
| 3 | Visual & Interaction — texture mapping, procedural meshes, STL loading, screen_to_ray mouse picking |
In progress (v0.1.18) |
| 4 | GPU compute entity simulation (50,000+ entities at 60 FPS), neighbor-grid collisions, flow field, damage and spawn waves | Done (v0.1.21; plan and measurements) |
| 5 | Vertex animation textures, skeletal animation, state machines, UI widgets | Planned |
Proof game: HAVOC — A 3D Vampire Survivors-style horde survival game. If nAIVE can render 50,000 physics-driven goblins while you drive a truck through them, it can handle anything. Waves 1 to 3 are playable now: naive run --scene scenes/tier4_havoc.yaml in project/.
The original tier roadmap is in the archived engine PRD v5.0; much of what it plans beyond Tier 4 is not built.
| Document | Description |
|---|---|
| Game Development Guide | How to build games with nAIVE |
| Architecture | How the engine is put together |
| Development and release checks | Tests, CI, releases and shipping a macOS app |
| Snake Sweeper Dev Log | Building Snake Sweeper in nAIVE |
| HAVOC Dev Log | Building a Vampire Survivors prototype in nAIVE |
| Archive | Earlier PRDs, the GDC white paper, plans and engine comparisons: history, not a description of the current engine |
| Version | Date | Key additions |
|---|---|---|
| v1.0 | Dec 2025 | Initial spec — Rust + wgpu + SLANG vision |
| v2.0 | Jan 2026 | ECS, physics, scripting, Gaussian splatting |
| v3.0 | Jan 2026 | Deferred pipeline, PBR materials, audio |
| v4.0 | Feb 2026 | Unified platform (engine + server), four-word addressing |
| v5.0 | Feb 2026 | Tier system, gameplay primitives, HAVOC proof game |
nAIVE uses a dual-license model:
The engine crates — naive-core, naive-client, and naive-runtime — are MIT licensed. You can use them for any purpose: personal, commercial, educational. Modify them, sell games built with them, fork them, include them in proprietary software. No royalties, no revenue sharing, no restrictions.
These three crates produce a complete game engine. You do not need the platform to build and ship games.
The server crate — naive-server — is licensed under the Business Source License 1.1.
What's allowed:
- Building and selling games (no restrictions)
- Self-hosting game servers
- Using the platform for internal development
- Any non-competing use
What's restricted:
- Offering managed game-hosting or game-server orchestration as a commercial service to third parties
The BSL converts to MIT on February 14, 2029. After that date, the server code becomes fully open source under the same MIT license as the engine.
naive-core MIT Use for anything. No restrictions.
naive-client MIT Use for anything. No restrictions.
naive-runtime MIT Use for anything. No restrictions.
naive-web MIT Use for anything. No restrictions.
naive-server BSL 1.1 No competing hosting services. Converts to MIT in 2029.
nAIVE is built with Claude Code as the primary development interface. The CLAUDE.md file in the project root contains the full Lua API reference and engine conventions for AI-assisted development.
# Run tests
cargo test
# Run with a specific scene
cargo run --bin naive -- --scene scenes/genesis.yaml
# Check compilation
cargo check --workspaceCurrent version: 0.1.22