feat: Implement deterministic runtime configuration & small visual fixes

README.md

@@ -92,13 +92,19 @@ other than `config/game.modal.local.json`.
 ## LLM Connector
 
 The default runtime config is `config/game.modal.local.json`, which uses the
-vLLM Modal endpoints for NPC decisions and God Console. To run without model
-calls, start the deterministic offline config explicitly:
+vLLM Modal endpoints for NPC decisions and God Console. For a temporary local
+run without model calls, force deterministic runtime
+resolvers:
 
 ```powershell
-uv run python -m god_simulator run --config config/game.local.json
+$env:GOD_SIMULATOR_FORCE_DETERMINISTIC="1"
+uv run python -m god_simulator run
 ```
 
+Unset `GOD_SIMULATOR_FORCE_DETERMINISTIC` to return to the configured model
+connectors. You can also start the deterministic offline config explicitly with
+`--config config/game.local.json`.
+
 The world is a 20 by 20 grid rendered as an 80 by 80 terrain, so one block is 4
 world units. NPCs start with 100 health and a deterministic base attack value
 between 5 and 15. The LLM connector uses the official `openai` Python client
@@ -157,14 +163,18 @@ by `connector.max_parallel_npc_calls`.
 
 The connector choice is binary: `connector.type: "deterministic"` makes every
 tick deterministic, while `connector.type: "openai_compatible"` asks the model
-on every tick.
+on every tick. `GOD_SIMULATOR_FORCE_DETERMINISTIC=1` overrides the active
+runtime to deterministic NPC ticks, disables model-backed God Console, and
+removes Modal warmup targets for that process.
 
 When the UI first loads, it fetches `/claw3d/state?warmup=1`. That tells the
 backend to start fire-and-forget health warmups for configured Modal model
-endpoints. Each resolved `.modal.run/health` URL is pinged in a daemon thread
-without a request timeout. Normal UI refreshes only read the latest model
-statuses. The UI shows each model as `checking`, `warmup` if no response has
-arrived after two seconds, or `ready` after HTTP 200.
+endpoints. With `GOD_SIMULATOR_FORCE_DETERMINISTIC=1` or
+`config/game.local.json`, there are no Modal targets to warm. Each resolved
+`.modal.run/health` URL is pinged in a daemon thread without a request timeout.
+Normal UI refreshes only read the latest model statuses. The UI shows each model
+as `checking`, `warmup` if no response has arrived after two seconds, or `ready`
+after HTTP 200.
 
 For Nemotron 3 Nano tool calling, the Modal configs use reasoning-off chat
 template kwargs and NVIDIA's recommended tool-call sampling values:

frontend/src/scene/BeastActor.tsx

@@ -6,9 +6,11 @@ import { MathUtils, Vector3 } from "three";
 
 import type { BeastSnapshot } from "../types";
 import { angularDistance, dampAngle, hashToUnit } from "./characterUtils";
+import { useCompletePreviousTickPosition } from "./useCompletePreviousTickPosition";
 
 type BeastActorProps = {
   beast: BeastSnapshot;
+  tick: number;
   focusTarget: readonly [number, number, number] | null;
   isSelected: boolean;
   onSelect: () => void;
@@ -41,7 +43,7 @@ const DEAD_PALETTE: BeastPalette = {
   eyes: "#1f1b19",
 };
 
-export function BeastActor({ beast, focusTarget, isSelected, onSelect }: BeastActorProps) {
+export function BeastActor({ beast, tick, focusTarget, isSelected, onSelect }: BeastActorProps) {
   const groupRef = useRef<Group>(null);
   const pulseRef = useRef<Mesh>(null);
   const bodyRef = useRef<Group>(null);
@@ -59,10 +61,16 @@ export function BeastActor({ beast, focusTarget, isSelected, onSelect }: BeastAc
     beast.position.y,
     beast.position.z,
   ]);
+  const target = useMemo(
+    () => [beast.position.x, beast.position.y, beast.position.z] as const,
+    [beast.position.x, beast.position.y, beast.position.z],
+  );
 
   const isDead = beast.state === "dead";
   const palette = isDead ? DEAD_PALETTE : LIVING_PALETTE;
 
+  useCompletePreviousTickPosition({ groupRef, tick, target });
+
   useFrame((state, delta) => {
     const group = groupRef.current;
     if (!group) {
@@ -70,7 +78,9 @@ export function BeastActor({ beast, focusTarget, isSelected, onSelect }: BeastAc
     }
 
     const time = state.clock.elapsedTime + animationPhase;
-    const walkTarget = isDead ? 0 : updatePosition(group, beast, focusTarget, moveDirection, delta);
+    const walkTarget = isDead
+      ? 0
+      : updatePosition(group, target, focusTarget, moveDirection, delta);
     walkBlendRef.current = MathUtils.damp(walkBlendRef.current, walkTarget, 7, delta);
 
     if (pulseRef.current) {
@@ -165,19 +175,19 @@ export function BeastActor({ beast, focusTarget, isSelected, onSelect }: BeastAc
 
 function updatePosition(
   group: Group,
-  beast: BeastSnapshot,
+  target: readonly [number, number, number],
   focusTarget: readonly [number, number, number] | null,
   moveDirection: Vector3,
   delta: number,
 ): number {
-  group.position.y = MathUtils.damp(group.position.y, beast.position.y, 8, delta);
+  group.position.y = MathUtils.damp(group.position.y, target[1], 8, delta);
 
-  const deltaX = beast.position.x - group.position.x;
-  const deltaZ = beast.position.z - group.position.z;
+  const deltaX = target[0] - group.position.x;
+  const deltaZ = target[2] - group.position.z;
   const distanceToTarget = Math.hypot(deltaX, deltaZ);
   if (distanceToTarget <= 0.025) {
-    group.position.x = beast.position.x;
-    group.position.z = beast.position.z;
+    group.position.x = target[0];
+    group.position.z = target[2];
     if (focusTarget) {
       const focusDeltaX = focusTarget[0] - group.position.x;
       const focusDeltaZ = focusTarget[2] - group.position.z;

frontend/src/scene/NpcActor.tsx

@@ -7,16 +7,18 @@ import type { EntitySnapshot } from "../types";
 import { faceVariant, hashToUnit, rolePalette } from "./characterUtils";
 import { NpcBody } from "./NpcBody";
 import { NpcLabelButton } from "./NpcLabelButton";
+import { useCompletePreviousTickPosition } from "./useCompletePreviousTickPosition";
 import { useNpcActorAnimation } from "./useNpcActorAnimation";
 
 type NpcActorProps = {
   entity: EntitySnapshot;
+  tick: number;
   focusTarget: readonly [number, number, number] | null;
   isSelected: boolean;
   onSelect: () => void;
 };
 
-export function NpcActor({ entity, focusTarget, isSelected, onSelect }: NpcActorProps) {
+export function NpcActor({ entity, tick, focusTarget, isSelected, onSelect }: NpcActorProps) {
   const groupRef = useRef<Group>(null);
   const pulseRef = useRef<Mesh>(null);
   const characterRef = useRef<Group>(null);
@@ -52,6 +54,8 @@ export function NpcActor({ entity, focusTarget, isSelected, onSelect }: NpcActor
     rightLegRef,
   };
 
+  useCompletePreviousTickPosition({ groupRef, tick, target });
+
   useNpcActorAnimation({
     entity,
     isSelected,

frontend/src/scene/WorldView.tsx

@@ -42,6 +42,7 @@ export function WorldView({ snapshot, selectedId, onSelectEntity }: WorldViewPro
         <NpcActor
           key={entity.id}
           entity={entity}
+          tick={snapshot.tick}
           focusTarget={
             entity.state.focus_target_id
               ? (positionsById.get(entity.state.focus_target_id) ?? null)
@@ -71,6 +72,7 @@ export function WorldView({ snapshot, selectedId, onSelectEntity }: WorldViewPro
         <BeastActor
           key={beast.id}
           beast={beast}
+          tick={snapshot.tick}
           focusTarget={
             beast.state === "attacking"
               ? (positionsById.get(beast.target_npc_id ?? beast.target_house_id ?? "") ?? null)
@@ -115,7 +117,10 @@ function HouseBuilding({ house, isSelected, onSelect }: HouseBuildingProps) {
   return (
     <group position={[house.position.x, house.position.y, house.position.z]} onClick={handleSelect}>
       {isComplete ? (
-        <>
+        // Keyed so a house transitioning building -> completed remounts these
+        // meshes instead of reusing the frame's material (which would leak its
+        // transparent/opacity/color onto the wall and make it render wrong).
+        <group key="completed">
           <mesh castShadow receiveShadow position={[0, 1.0, 0]}>
             <boxGeometry args={[3.2, 2.0, 3.2]} />
             <meshStandardMaterial map={textures.wall} roughness={0.85} />
@@ -136,9 +141,9 @@ function HouseBuilding({ house, isSelected, onSelect }: HouseBuildingProps) {
               <meshStandardMaterial map={textures.window} roughness={0.4} />
             </mesh>
           ))}
-        </>
+        </group>
       ) : isDestroyed ? (
-        <>
+        <group key="destroyed">
           {/* Charred wall stumps where the house stood. */}
           <mesh castShadow receiveShadow position={[-0.95, 0.34, -1.05]} rotation={[0, 0.12, 0]}>
             <boxGeometry args={[1.3, 0.68, 1.1]} />
@@ -180,9 +185,9 @@ function HouseBuilding({ house, isSelected, onSelect }: HouseBuildingProps) {
               <meshStandardMaterial color="#6b5d51" roughness={0.95} />
             </mesh>
           ))}
-        </>
+        </group>
       ) : (
-        <>
+        <group key="building">
           {/* Frame rising with build progress. */}
           <mesh castShadow receiveShadow position={[0, Math.max(0.15, buildRatio), 0]}>
             <boxGeometry args={[3.2, Math.max(0.3, buildRatio * 2.0), 3.2]} />
@@ -202,7 +207,7 @@ function HouseBuilding({ house, isSelected, onSelect }: HouseBuildingProps) {
               </mesh>
             )),
           )}
-        </>
+        </group>
       )}
 
       <mesh rotation={[-Math.PI / 2, 0, 0]} position={[0, 0.035, 0]}>
@@ -270,12 +275,20 @@ type TerrainProps = {
 
 const VOXEL_SIZE = 1;
 const VOXEL_HEIGHT = 0.6;
+// Purely visual border (in tiles per side) so structures placed on the
+// playable edge still rest on ground instead of hanging into the void.
+// Gameplay bounds are unchanged — the backend never places anything here.
+const EDGE_MARGIN = 3;
 
 function Terrain({ width, depth, color }: TerrainProps) {
   const meshRef = useRef<InstancedMesh>(null);
-  const cols = Math.max(1, Math.round(width / VOXEL_SIZE));
-  const rows = Math.max(1, Math.round(depth / VOXEL_SIZE));
+  const cols = Math.max(1, Math.round(width / VOXEL_SIZE)) + EDGE_MARGIN * 2;
+  const rows = Math.max(1, Math.round(depth / VOXEL_SIZE)) + EDGE_MARGIN * 2;
   const count = cols * rows;
+  // Rendered span including the border; keeps the grid centered on the origin
+  // so playable coordinates from the backend still line up.
+  const renderWidth = cols * VOXEL_SIZE;
+  const renderDepth = rows * VOXEL_SIZE;
 
   useLayoutEffect(() => {
     const mesh = meshRef.current;
@@ -289,8 +302,8 @@ function Terrain({ width, depth, color }: TerrainProps) {
     let index = 0;
     for (let col = 0; col < cols; col += 1) {
       for (let row = 0; row < rows; row += 1) {
-        const x = (col + 0.5) * VOXEL_SIZE - width / 2;
-        const z = (row + 0.5) * VOXEL_SIZE - depth / 2;
+        const x = (col + 0.5) * VOXEL_SIZE - renderWidth / 2;
+        const z = (row + 0.5) * VOXEL_SIZE - renderDepth / 2;
         const heightRoll = tileNoise(col, row, 1);
         const tintRoll = tileNoise(col, row, 2);
         // Subtle steps only — keep the surface readable as flat ground.
@@ -310,7 +323,7 @@ function Terrain({ width, depth, color }: TerrainProps) {
     if (mesh.instanceColor) {
       mesh.instanceColor.needsUpdate = true;
     }
-  }, [cols, rows, width, depth, color]);
+  }, [cols, rows, renderWidth, renderDepth, color]);
 
   return (
     <group>
@@ -320,7 +333,7 @@ function Terrain({ width, depth, color }: TerrainProps) {
       </instancedMesh>
       {/* dirt slab so the world edge reads as a floating voxel block */}
       <mesh position={[0, -VOXEL_HEIGHT - 0.7, 0]}>
-        <boxGeometry args={[width, 1.6, depth]} />
+        <boxGeometry args={[renderWidth, 1.6, renderDepth]} />
         <meshStandardMaterial color="#6b4a2c" roughness={0.95} />
       </mesh>
     </group>

frontend/src/scene/useCompletePreviousTickPosition.ts

@@ -0,0 +1,40 @@
+import { useLayoutEffect, useRef } from "react";
+import type { RefObject } from "react";
+import type { Group } from "three";
+
+type ActorPosition = readonly [number, number, number];
+
+type CompletePreviousTickPositionOptions = {
+  groupRef: RefObject<Group | null>;
+  tick: number;
+  target: ActorPosition;
+};
+
+const SETTLED_DISTANCE = 0.025;
+
+export function useCompletePreviousTickPosition({
+  groupRef,
+  tick,
+  target,
+}: CompletePreviousTickPositionOptions) {
+  const previousTickRef = useRef(tick);
+  const previousTargetRef = useRef<ActorPosition>(target);
+
+  useLayoutEffect(() => {
+    const group = groupRef.current;
+    const previousTarget = previousTargetRef.current;
+    if (group && tick !== previousTickRef.current && !isAtPosition(group, previousTarget)) {
+      group.position.set(previousTarget[0], previousTarget[1], previousTarget[2]);
+    }
+
+    previousTickRef.current = tick;
+    previousTargetRef.current = target;
+  }, [groupRef, target, tick]);
+}
+
+function isAtPosition(group: Group, target: ActorPosition): boolean {
+  return (
+    Math.abs(group.position.y - target[1]) <= SETTLED_DISTANCE &&
+    Math.hypot(group.position.x - target[0], group.position.z - target[2]) <= SETTLED_DISTANCE
+  );
+}

scripts/playtest_agent.py

@@ -3,11 +3,11 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import sys
+import time
 from collections import Counter
 from dataclasses import dataclass, field
 from pathlib import Path
-import sys
-import time
 from typing import Any
 from urllib.error import URLError
 from urllib.parse import urlparse
@@ -26,6 +26,7 @@ from god_simulator.config import (  # noqa: E402
     ServerConfig,
     SimulationConfig,
     WorldConfig,
+    apply_runtime_env_overrides,
     load_game_config,
 )
 from god_simulator.domain import WorldLogEvent, WorldState  # noqa: E402
@@ -47,7 +48,6 @@ from god_simulator.simulation.roles import normalize_role  # noqa: E402
 from god_simulator.simulation.spawning import create_world  # noqa: E402
 from god_simulator.simulation.tick import advance_world  # noqa: E402
 
-
 CHAOS_SCHEDULE: dict[int, list[str]] = {
     50: ["spawn_beast"],
     120: ["famine"],
@@ -135,7 +135,7 @@ def main() -> None:
     args = _parse_args()
     started = time.perf_counter()
 
-    config = _load_or_default_config(args.config)
+    config = apply_runtime_env_overrides(_load_or_default_config(args.config))
     config = _with_playtest_overrides(config, seed=args.seed, npc_count=args.npcs)
     world = create_world(config)
     simulator, simulator_label = _build_simulator(config, args.use_llm)
@@ -197,7 +197,11 @@ def _parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         description="Run the scheduled-chaos playtest and write playtest_report.md."
     )
-    parser.add_argument("--config", type=Path, default=Path("config/game.modal.local.json"))
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=Path(os.getenv("GOD_SIMULATOR_CONFIG", "config/game.modal.local.json")),
+    )
     parser.add_argument("--report", type=Path, default=Path("playtest_report.md"))
     parser.add_argument("--ticks", type=int, default=400)
     parser.add_argument("--seed", type=int, default=None)

src/god_simulator/__main__.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
 import argparse
+import os
 from pathlib import Path
 
 from god_simulator.api.server import run_server
-from god_simulator.config import load_game_config
+from god_simulator.config import apply_runtime_env_overrides, load_game_config
 from god_simulator.simulation.spawning import create_world
 
-DEFAULT_CONFIG = Path("config/game.modal.local.json")
+DEFAULT_CONFIG = Path(os.getenv("GOD_SIMULATOR_CONFIG", "config/game.modal.local.json"))
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -37,7 +38,7 @@ def main() -> None:
     parser = build_parser()
     args = parser.parse_args()
 
-    config = load_game_config(args.config)
+    config = apply_runtime_env_overrides(load_game_config(args.config))
     world = create_world(config)
 
     if args.command == "inspect":

src/god_simulator/api/gradio_app.py

@@ -12,7 +12,7 @@ from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel
 
 from god_simulator.api.runtime import GameRuntime, create_game_runtime
-from god_simulator.config import load_game_config
+from god_simulator.config import apply_runtime_env_overrides, load_game_config
 from god_simulator.simulation.spawning import create_world
 
 
@@ -29,7 +29,7 @@ def create_gradio_app(
     config_path: Path,
     static_dir: Path = Path("dist/frontend"),
 ) -> gr.Server:
-    config = load_game_config(config_path)
+    config = apply_runtime_env_overrides(load_game_config(config_path))
     runtime = create_game_runtime(world=create_world(config), config=config)
     app = gr.Server(title="God Simulator")
 

src/god_simulator/config.py

@@ -9,6 +9,7 @@ from typing import Any, Literal, cast
 TerrainKind = Literal["plain_green"]
 ConnectorKind = Literal["deterministic", "openai_compatible"]
 OverseerMode = Literal["off", "advisor", "autopilot"]
+FORCE_DETERMINISTIC_ENV = "GOD_SIMULATOR_FORCE_DETERMINISTIC"
 
 
 @dataclass(frozen=True, slots=True)
@@ -83,6 +84,27 @@ def load_game_config(path: Path) -> GameConfig:
     return parse_game_config(raw)
 
 
+def apply_runtime_env_overrides(config: GameConfig) -> GameConfig:
+    if not _truthy_env(os.getenv(FORCE_DETERMINISTIC_ENV)):
+        return config
+
+    deterministic_connector = ConnectorConfig(type="deterministic")
+    return GameConfig(
+        world=config.world,
+        npcs=config.npcs,
+        simulation=config.simulation,
+        server=config.server,
+        connector=deterministic_connector,
+        god_console=None,
+        overseer=OverseerConfig(
+            mode=config.overseer.mode,
+            cycle_ticks=config.overseer.cycle_ticks,
+            max_directives=config.overseer.max_directives,
+            connector=deterministic_connector,
+        ),
+    )
+
+
 def parse_game_config(raw: dict[str, Any]) -> GameConfig:
     world = _required_mapping(raw, "world")
     npcs = _required_mapping(raw, "npcs")
@@ -345,3 +367,7 @@ def _dotenv_value(raw: str) -> str:
     if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
         return value[1:-1]
     return value
+
+
+def _truthy_env(value: str | None) -> bool:
+    return value is not None and value.strip().lower() in ("1", "true", "yes", "on")

tests/test_config.py

@@ -4,7 +4,7 @@ import json
 
 import pytest
 
-from god_simulator.config import load_game_config, parse_game_config
+from god_simulator.config import apply_runtime_env_overrides, load_game_config, parse_game_config
 
 
 def test_parse_game_config() -> None:
@@ -152,3 +152,42 @@ def test_load_game_config_does_not_override_existing_env(
     config = load_game_config(config_path)
 
     assert config.connector.base_url == "https://already-set.example/v1"
+
+
+def test_force_deterministic_env_overrides_runtime_connectors(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("GOD_SIMULATOR_FORCE_DETERMINISTIC", "1")
+    config = parse_game_config(
+        {
+            "world": {"width": 80, "depth": 60, "terrain": "plain_green", "seed": 7},
+            "npcs": {"count": 3},
+            "simulation": {"tick_ms": 500},
+            "server": {"host": "127.0.0.1", "port": 8000},
+            "connector": {
+                "type": "openai_compatible",
+                "base_url": "https://workspace--npc-serve.modal.run/v1",
+                "model": "npc-model",
+            },
+            "god_console": {
+                "type": "openai_compatible",
+                "base_url": "https://workspace--god-serve.modal.run/v1",
+                "model": "god-model",
+            },
+            "overseer": {
+                "mode": "autopilot",
+                "connector": {
+                    "type": "openai_compatible",
+                    "base_url": "https://workspace--overseer-serve.modal.run/v1",
+                    "model": "overseer-model",
+                },
+            },
+        }
+    )
+
+    config = apply_runtime_env_overrides(config)
+
+    assert config.connector.type == "deterministic"
+    assert config.god_console is None
+    assert config.overseer.mode == "autopilot"
+    assert config.overseer.connector.type == "deterministic"

tests/test_gradio_app.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
+import pytest
 from fastapi.testclient import TestClient
 
 from god_simulator.api.gradio_app import create_gradio_app
@@ -37,6 +38,28 @@ def test_gradio_app_serves_missing_frontend_page(tmp_path: Path) -> None:
     assert "frontend is not built" in response.text
 
 
+def test_gradio_app_force_deterministic_disables_modal_runtime(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("GOD_SIMULATOR_FORCE_DETERMINISTIC", "1")
+    config_path = _write_modal_config(tmp_path)
+    app = create_gradio_app(config_path=config_path, static_dir=tmp_path / "dist")
+    client = TestClient(app)
+
+    health = client.get("/health")
+    assert health.status_code == 200
+    assert health.json()["simulator"] == "deterministic"
+
+    snapshot = client.get("/claw3d/state?warmup=1")
+    assert snapshot.status_code == 200
+    assert snapshot.json()["simulation"]["models"] == []
+
+    god_command = client.post("/god-command", json={"command": "make Ada happy"})
+    assert god_command.status_code == 400
+    assert god_command.json()["error"] == "god_console_unavailable"
+
+
 def _write_config(tmp_path: Path) -> Path:
     config_path = tmp_path / "game.json"
     config_path.write_text(
@@ -56,3 +79,34 @@ def _write_config(tmp_path: Path) -> Path:
         encoding="utf-8",
     )
     return config_path
+
+
+def _write_modal_config(tmp_path: Path) -> Path:
+    config_path = tmp_path / "game.modal.json"
+    config_path.write_text(
+        json.dumps(
+            {
+                "world": {
+                    "width": 80,
+                    "depth": 80,
+                    "terrain": "plain_green",
+                    "seed": 42,
+                },
+                "npcs": {"count": 2},
+                "simulation": {"tick_ms": 500},
+                "server": {"host": "127.0.0.1", "port": 8000},
+                "connector": {
+                    "type": "openai_compatible",
+                    "base_url": "https://workspace--npc-serve.modal.run/v1",
+                    "model": "npc-model",
+                },
+                "god_console": {
+                    "type": "openai_compatible",
+                    "base_url": "https://workspace--god-serve.modal.run/v1",
+                    "model": "god-model",
+                },
+            }
+        ),
+        encoding="utf-8",
+    )
+    return config_path