Agent Playtest

an LLM agent drives a running SimVX game, headless.

📄 Docs only

Tags: ai

Run it two ways:

Real LLM loop against your OpenWebUI / vLLM / llama.cpp endpoint:

SIMVX_LLM_BASE_URL=http://host:8000/v1 SIMVX_LLM_MODEL=your-model SIMVX_LLM_API_KEY=sk-… uv run python examples/features/ai/agent_playtest.py

Offline (no endpoint): runs a scripted walk-through of the session verbs.

uv run python examples/features/ai/agent_playtest.py

The game is a trivial “reach 5 points” toy so the loop is easy to follow; the session verbs (observe / send_input / set_state / step, terminated vs truncated) are identical for any real game.

Source

"""Agent Playtest: an LLM agent drives a running SimVX game, headless.

Run it two ways:

  # Real LLM loop against your OpenWebUI / vLLM / llama.cpp endpoint:
  SIMVX_LLM_BASE_URL=http://host:8000/v1 SIMVX_LLM_MODEL=your-model \
  SIMVX_LLM_API_KEY=sk-... uv run python examples/features/ai/agent_playtest.py

  # Offline (no endpoint): runs a scripted walk-through of the session verbs.
  uv run python examples/features/ai/agent_playtest.py

The game is a trivial "reach 5 points" toy so the loop is easy to follow; the
session verbs (observe / send_input / set_state / step, terminated vs
truncated) are identical for any real game.

# /// simvx
# web = { disabled = true, reason = "requires a local or remote LLM endpoint; not available in the browser runtime" }
# ///
"""

from __future__ import annotations

import asyncio
import os

from simvx.ai import AgentSession, OpenAICompatibleClient, dispatch, run_agent
from simvx.core import Input, Node2D, Property
from simvx.core.input import Key


class Scorer(Node2D):
    score = Property(0)

    def on_update(self, dt):
        # Holding SPACE scores a point per frame (a stand-in for real gameplay).
        if Input.is_key_pressed(Key.SPACE):
            self.score += 1


class Toy(Node2D):
    def on_ready(self):
        self.add_child(Scorer(name="Scorer"))


def _won(root) -> str | None:
    scorer = next((n for n in root.walk(include_self=True) if isinstance(n, Scorer)), None)
    return "win" if scorer and scorer.score >= 5 else None


def _make_session() -> AgentSession:
    return AgentSession(Toy(name="Toy"), terminal_fn=_won)


async def _real_run() -> None:
    client = OpenAICompatibleClient.from_env()
    session = _make_session()
    print(f"Driving model {client.model!r} at {client.base_url} ...\n")
    result = await run_agent(
        session,
        client,
        goal="Make the Scorer reach 5 points, then report how you did it.",
        max_turns=15,
    )
    print("\n=== AGENT REPORT ===")
    print(result.final_text)
    print(
        f"\nturns={result.turns} tool_calls={result.tool_calls} "
        f"terminated={result.terminated} reason={result.reason!r}"
    )


def _scripted_run() -> None:
    """No LLM configured: drive the same tools by hand to show the surface."""
    session = _make_session()
    print("No SIMVX_LLM_BASE_URL set -- running a scripted tool walk-through.\n")
    print(dispatch(session, "observe", {"kind": "describe"})["tree"], "\n")

    print(dispatch(session, "send_input", {"kind": "key", "key": "space", "mode": "down"}))
    for _ in range(6):
        out = dispatch(session, "step", {"frames": 1})
        score = dispatch(session, "observe", {"kind": "node", "path": "Scorer"})["properties"]["score"]
        print(f"  frame={out['result']['frame']} score={score} terminated={out['terminated']}")
        if out["terminated"]:
            print(f"\nReached terminal state: {out['reason']!r}")
            break


def main() -> None:
    if os.environ.get("SIMVX_LLM_BASE_URL"):
        asyncio.run(_real_run())
    else:
        _scripted_run()


if __name__ == "__main__":
    main()