nAIVE

The 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.

Sub-second hot-reload. Shaders in <200ms. Scenes in <100ms. Scripts in <50ms. 100x faster than Unity or Unreal.

No royalties. No restrictions. The engine is MIT licensed. Build anything. Ship it. Sell it. Keep everything.

brew install poro/tap/naive

git clone https://github.com/poro/nAIVE.git
cd nAIVE

# Download SLANG SDK (required for shader compilation)
# macOS ARM:
curl -L https://github.com/shader-slang/slang/releases/download/v2026.2.1/slang-2026.2.1-macos-aarch64.tar.gz | tar xz -C vendor/
# macOS Intel:
curl -L https://github.com/shader-slang/slang/releases/download/v2026.2.1/slang-2026.2.1-macos-x86_64.tar.gz | tar xz -C vendor/

export SLANG_DIR=$(pwd)/vendor
cargo build --release

The build produces three binaries in target/release/:

• naive — Main CLI for running games
• naive-runtime — Full engine runtime (same as naive)
• naive_mcp — MCP JSON-RPC server for AI agent integration

• Rust 1.75+ (for building from source)
• macOS 12+ (Metal), Windows 10+ (Vulkan/DX12), or Linux (Vulkan)
• 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 test

my-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
• Shadow mapping with PCF filtering
• 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_death callbacks
• 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 per-entity sandboxing
• 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

1. Copy the environment file and fill in your credentials:

cp .env.example .env

2. Configure at least one generation backend:

The gateway (self-hosted GPU) is tried first; HuggingFace Spaces is the fallback.

3. 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:

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)    WASM + WebGPU build for browser playground

Run any scene with naive run --scene scenes/<name>.yaml:

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)           --> bool

Scenes 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.lua

Development follows a tiered system, each tier validated by proof-of-concept games:

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.

See the full roadmap in docs/nAIVE_Engine_PRD_v5.0.md.

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 --workspace

Current version: 0.1.18