8000 GitHub - poro/nAIVE: nAIVE · GitHub
[go: up one dir, main page]

Skip to content
poroPublic

About

nAIVE

Resources

Stars

15 stars

Watchers

1 watching

Forks

Repository files navigation

nAIVE

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.


Why nAIVE

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.

Measured: an agent builds a game

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.

Implementation status

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.


Install

Homebrew (macOS)

brew install poro/tap/naive

From source

git 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-player

Git 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 games
  • naive-runtime — Full engine runtime (same as naive)
  • naive_mcp — MCP JSON-RPC server for AI agent integration
  • naive-player — naive without the Slang compiler; naive build ships it inside game bundles

Requirements

  • 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

Quick Start

# 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

Project structure

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

Features

Rendering

  • 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

Physics & Gameplay

  • 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

Scripting

  • 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()

Runtime Foundations (Tier 2, experimental)

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

AI Asset Generation

  • 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

Infrastructure

  • 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

AI Asset Generation

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

Setup

  1. Copy the environment file and fill in your credentials:
cp .env.example .env
  1. 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.

  1. If using a self-hosted server, open an SSH tunnel:
ssh -L 8000:localhost:8000 -p 2222 ubuntu@<your-server-ip>

Generate assets

source .env
node scripts/test_generate_asset.js "red sports car"

This saves generated_2d.png and generated_3d.glb into project/assets/meshes/.

MCP Servers

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

Architecture

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

Tech stack

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)

Demo Scenes

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

Lua API

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

Key API functions

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

Scene Format

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

Roadmap

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


Documentation

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

PRD version history (archived)

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

License

nAIVE uses a dual-license model:

Engine (MIT)

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.

Platform (BSL 1.1)

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.

Contributing

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

About

nAIVE

Resources

Stars

15 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

0