README.md

metadata

title: World Simulator
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.17.3
python_version: 3.11
app_file: app.py
header: mini
fullWidth: true
startup_duration_timeout: 1h
pinned: true
tags:
  - thousand-token-wood
  - judges-wildcard
  - best-demo
  - best-agent

World Simulator

An AI civilization sandbox: LLM-driven NPCs live, move, talk, and fight on a 80×20 grid, rendered in a Three.js/R3F 3D client. The Python simulation owns all meaning; the renderer only displays it — so planners, memory, factions, and world events can be added without touching the UI.

Build Small Hackathon — Track: Thousand Token Wood · Badges: Judges' Wildcard, Best Demo, Best Agent

• 📹 Demo video: https://youtu.be/cAIkA-WHoFM
• 📣 Social post: TODO: add link

Models (all < 32B): NPC decisions run on Nemotron-3-Nano-30B-A3B-FP8 (30B), the God Console on Qwen3.6-27B-FP8 (27B) — small models combined under the cap.

Quick Start

# Backend (deterministic, no model calls)
$env:WORLD_SIMULATOR_FORCE_DETERMINISTIC="1"
uv run python -m world_simulator run     # serves /health, /state, /scene/state, POST /tick

# 3D UI
npm install
npm run dev                              # http://127.0.0.1:5173

Controls: drag to orbit, scroll to zoom, WASD/arrows to pan.

Autoplay is on by default: the manual tick controls are hidden and the world advances ticks automatically. Set VITE_WORLD_SIMULATOR_AUTOPLAY=0 (build/dev env) to show the manual step / play-pause controls instead.

Hugging Face Space

app.py wraps the same game runtime in gradio.Server and serves the built React/Three UI from dist/frontend. Build it first, then run:

npm install
npm run gradio

requirements.txt installs the local project from pyproject.toml. Set WORLD_SIMULATOR_CONFIG to override the default config/game.modal.local.json.

How NPCs Think

Each tick, every living NPC gets its own model request containing its health, attack, personality, god directive, recent memories, and visible NPCs within 5 blocks. The model picks exactly one action — walk, talk, or attack — and all decisions are collected then applied together, so turn order grants no advantage. The server records outcome memories afterward and compacts older ones into a rolling summary.

A God Console (when an OpenAI-compatible connector is active) takes freeform commands like "Ada wants to kill everyone" and applies the model's tool calls to world state (health, attack, personality, directive, memory, position).

Connector is binary: connector.type is deterministic (every tick deterministic) or openai_compatible (model every tick). WORLD_SIMULATOR_FORCE_DETERMINISTIC=1 forces deterministic ticks and disables model-backed features.

Model Configs

• config/game.modal.local.json (default) — NPCs on a Modal vLLM Nemotron Nano H100 endpoint, God Console on a Modal vLLM Qwen3.6 H100 endpoint. Override with OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL.
• config/game.local.json — fully offline/deterministic.

Deploy the Modal endpoints with modal deploy deployments/modal_nemotron_nano.py and deployments/modal_qwen36_27b_h100.py; smoke-test with deployments/smoke_modal_endpoint.py.

Development

npm run gradio

Runtime deps live in pyproject.toml; dev tools are in the dev group.