feat: add reset world admin btn

src/world_simulator/api/gradio_app.py

@@ -43,7 +43,7 @@ class AdminModelRequest(BaseModel):
 
 def _load_or_create_world(
     config: GameConfig,
-) -> tuple[WorldState, PlayerManager, BackgroundSnapshotWriter | None]:
+) -> tuple[WorldState, PlayerManager, BackgroundSnapshotWriter | None, SnapshotStore | None]:
     """Resume the world from the snapshot bucket if configured, else create fresh.
 
     Set ``WORLD_STATE_DIR`` to a (writable, ideally bucket-mounted) directory to
@@ -53,7 +53,7 @@ def _load_or_create_world(
     """
     state_dir = os.getenv("WORLD_STATE_DIR", "").strip()
     if not state_dir:
-        return create_world(config), PlayerManager(), None
+        return create_world(config), PlayerManager(), None, None
 
     store = SnapshotStore(Path(state_dir))
     players = PlayerManager()
@@ -72,7 +72,7 @@ def _load_or_create_world(
 
     writer = BackgroundSnapshotWriter(store)
     atexit.register(writer.close)
-    return world, players, writer
+    return world, players, writer, store
 
 
 def create_gradio_app(
@@ -81,12 +81,13 @@ def create_gradio_app(
     static_dir: Path = Path("dist/frontend"),
 ) -> gr.Server:
     config = apply_runtime_env_overrides(load_game_config(config_path))
-    world, players, snapshot_writer = _load_or_create_world(config)
+    world, players, snapshot_writer, snapshot_store = _load_or_create_world(config)
     runtime = create_game_runtime(
         world=world,
         config=config,
         players=players,
         snapshot_writer=snapshot_writer,
+        snapshot_store=snapshot_store,
     )
     app = gr.Server(title="World Simulator")
 

src/world_simulator/api/persistence.py

@@ -121,6 +121,22 @@ class SnapshotStore:
                 best = (tick, data)
         return best[1] if best else None
 
+    def clear(self) -> None:
+        """Delete both slot files and forget their ticks.
+
+        Missing files are ignored so a clear on a never-persisted world is a
+        no-op. After this, :meth:`load` returns ``None`` and the next
+        :meth:`save` starts the ping-pong from slot 0 again.
+        """
+        for name in _SLOT_NAMES:
+            try:
+                (self._dir / name).unlink()
+            except FileNotFoundError:
+                pass
+            except OSError as exc:
+                print(f"world snapshot clear failed for {name}: {exc}", flush=True)
+        self._slot_ticks = [-1, -1]
+
     def save(self, snapshot: dict[str, Any]) -> None:
         target = 0 if self._slot_ticks[0] <= self._slot_ticks[1] else 1
         path = self._dir / _SLOT_NAMES[target]
@@ -168,6 +184,12 @@ class BackgroundSnapshotWriter:
             self._pending = snapshot
             self._cond.notify()
 
+    def drop_pending(self) -> None:
+        """Discard any not-yet-written snapshot so a reset can't be undone by a
+        stale snapshot submitted just before it."""
+        with self._cond:
+            self._pending = None
+
     def _run(self) -> None:
         while True:
             with self._cond:

src/world_simulator/api/public_ui.py

@@ -118,12 +118,12 @@ def build_public_ui(runtime: GameRuntime, *, world_path: str = "/world") -> gr.B
                             token_box = gr.Textbox(
                                 label="Your MCP token",
                                 interactive=False,
-                                show_copy_button=True,
+                                buttons=["copy"],
                             )
                             mcp_url_box = gr.Textbox(
                                 label="Your MCP server URL",
                                 interactive=False,
-                                show_copy_button=True,
+                                buttons=["copy"],
                             )
                             config_box = gr.Code(
                                 label="MCP client config (Streamable HTTP)",
@@ -159,10 +159,10 @@ def build_public_ui(runtime: GameRuntime, *, world_path: str = "/world") -> gr.B
                 """
                 <div class="gs-card-head sky">
                   <div class="gs-tile sky">📄</div>
-                  <h2>Admin Logs</h2>
+                  <h2>Admin panel</h2>
                 </div>
                 <div class="gs-card-body">
-                  <p class="gs-lede">Read model, validator and engine records from ledger.jsonl. Requires ADMIN_TOKEN.</p>
+                  <p class="gs-lede">Read model, validator and engine records from ledger.jsonl, and reset the world. Requires ADMIN_TOKEN.</p>
                 </div>
                 """
             )
@@ -189,6 +189,11 @@ def build_public_ui(runtime: GameRuntime, *, world_path: str = "/world") -> gr.B
                     admin_limit = gr.Number(label="limit", value=100, precision=0)
                 admin_btn = gr.Button("Load ledger records")
                 admin_out = gr.JSON(label="Ledger records")
+                with gr.Row(elem_classes="status-row"):
+                    admin_reset_btn = gr.Button(
+                        "⚠️ Clear state & restart world", variant="stop"
+                    )
+                admin_reset_out = gr.Markdown()
 
         gr.HTML(_GROUND_FOOTER_HTML)
 
@@ -233,6 +238,13 @@ def build_public_ui(runtime: GameRuntime, *, world_path: str = "/world") -> gr.B
             api_name="admin_logs",
         )
 
+        admin_reset_btn.click(
+            _make_admin_reset_handler(runtime),
+            inputs=[admin_token],
+            outputs=[admin_reset_out],
+            api_name="admin_reset",
+        )
+
     return blocks
 
 
@@ -315,6 +327,18 @@ def _make_admin_logs_handler(runtime: GameRuntime) -> Any:
     return load
 
 
+def _make_admin_reset_handler(runtime: GameRuntime) -> Any:
+    def reset(token: str) -> str:
+        if token != os.getenv("ADMIN_TOKEN", "dev-admin-token"):
+            return "❌ admin_token_required"
+        status, payload = runtime.reset_world()
+        if status != HTTPStatus.OK:
+            return f"❌ {payload.get('message', 'Could not reset the world.')}"
+        return f"✅ World cleared and restarted (tick {payload.get('tick', 0)})."
+
+    return reset
+
+
 def _format_status(payload: dict[str, Any]) -> str:
     icon = payload.get("icon", "")
     name = payload.get("name", "?")

src/world_simulator/api/runtime.py

@@ -13,7 +13,11 @@ from urllib.error import HTTPError, URLError
 from urllib.request import Request, urlopen
 
 from world_simulator.api.modal_auth import modal_proxy_auth_headers
-from world_simulator.api.persistence import BackgroundSnapshotWriter, build_snapshot
+from world_simulator.api.persistence import (
+    BackgroundSnapshotWriter,
+    SnapshotStore,
+    build_snapshot,
+)
 from world_simulator.api.players import (
     PlayerCharacter,
     PlayerError,
@@ -26,6 +30,7 @@ from world_simulator.rendering.scene_contract import to_scene_snapshot
 from world_simulator.simulation.connectors.base import TickPlan, WorldSimulator
 from world_simulator.simulation.connectors.factory import create_world_simulator
 from world_simulator.simulation.directives import expire_directives
+from world_simulator.simulation.spawning import create_world
 from world_simulator.simulation.tick import apply_tick_plan, plan_world_tick
 
 
@@ -40,6 +45,7 @@ class GameRuntime:
         ledger: RunLedger | None = None,
         config: GameConfig | None = None,
         snapshot_writer: BackgroundSnapshotWriter | None = None,
+        snapshot_store: SnapshotStore | None = None,
     ) -> None:
         self._world = world
         self._simulator = simulator
@@ -48,6 +54,7 @@ class GameRuntime:
         self._ledger = ledger or RunLedger()
         self._config = config
         self._snapshot_writer = snapshot_writer
+        self._snapshot_store = snapshot_store
         self._lock = Lock()
         self._tick_status = TickStatus()
         self._pending_commands: list[PendingCommand] = []
@@ -155,6 +162,29 @@ class GameRuntime:
             return
         self._snapshot_writer.submit(build_snapshot(self._world, self._players.snapshot()))
 
+    def reset_world(self) -> tuple[HTTPStatus, dict[str, Any]]:
+        """Wipe the live world: fresh world, no players, deleted snapshot files.
+
+        Used by the Admin panel. Drops any in-flight snapshot first so the
+        background writer cannot resurrect the deleted state, then clears the
+        store on disk.
+        """
+        if self._config is None:
+            return HTTPStatus.INTERNAL_SERVER_ERROR, {
+                "error": "reset_unavailable",
+                "message": "Runtime has no config to rebuild the world from.",
+            }
+        with self._lock:
+            if self._snapshot_writer is not None:
+                self._snapshot_writer.drop_pending()
+            self._world = create_world(self._config)
+            self._players = PlayerManager()
+            self._tick_status = TickStatus()
+            self._pending_commands = []
+            if self._snapshot_store is not None:
+                self._snapshot_store.clear()
+            return HTTPStatus.OK, {"ok": True, "tick": self._world.tick}
+
     # -- player characters (external agents over MCP) ---------------------- #
     def create_player(
         self,
@@ -423,6 +453,7 @@ def create_game_runtime(
     config: GameConfig,
     players: PlayerManager | None = None,
     snapshot_writer: BackgroundSnapshotWriter | None = None,
+    snapshot_store: SnapshotStore | None = None,
 ) -> GameRuntime:
     simulator = create_world_simulator(config)
     return GameRuntime(
@@ -432,6 +463,7 @@ def create_game_runtime(
         players=players,
         config=config,
         snapshot_writer=snapshot_writer,
+        snapshot_store=snapshot_store,
     )
 
 

tests/test_gradio_app.py

@@ -37,10 +37,9 @@ def test_gradio_app_serves_missing_frontend_page(tmp_path: Path) -> None:
     assert response.status_code == 503
     assert "frontend is not built" in response.text
 
-    # The landing page redirects to the public lobby.
-    redirect = client.get("/", follow_redirects=False)
-    assert redirect.status_code in (302, 307)
-    assert redirect.headers["location"] == "/connect"
+    # The public lobby is served directly at the root path.
+    lobby = client.get("/")
+    assert lobby.status_code == 200
 
 
 def test_gradio_app_force_deterministic_disables_modal_runtime(

tests/test_persistence.py

@@ -104,6 +104,24 @@ def test_snapshot_store_falls_back_when_newest_slot_is_corrupt(tmp_path) -> None
     assert loaded["tick"] == 0  # falls back to the older, intact slot
 
 
+def test_snapshot_store_clear_deletes_slots(tmp_path) -> None:
+    store = SnapshotStore(tmp_path)
+    world = create_world(_config(npc_count=3))
+    store.save(build_snapshot(world, PlayerManager().snapshot()))
+    world.tick = 4
+    store.save(build_snapshot(world, PlayerManager().snapshot()))
+
+    store.clear()
+
+    assert not list(tmp_path.glob("world_state.*.json"))
+    assert store.load() is None
+    # Clearing again (nothing on disk) is a no-op, not an error.
+    store.clear()
+    # The next save starts the ping-pong from slot 0 again.
+    store.save(build_snapshot(world, PlayerManager().snapshot()))
+    assert (tmp_path / "world_state.0.json").exists()
+
+
 def test_background_writer_persists_latest(tmp_path) -> None:
     store = SnapshotStore(tmp_path)
     writer = BackgroundSnapshotWriter(store)