Compiled game executable with scenario launcher (no Godot IDE for users)

[justinmadison]

Problem

Issue #70 identified the real pain point: when a developer runs python run.py, there's no clear path to get the game running. The original fix proposed documentation and screenshots for navigating the Godot IDE. But the root problem is deeper: Agent Arena users should never touch the Godot editor at all.

Our target audience is AI/Python developers learning agentic programming. Requiring them to install and navigate a game engine IDE is a massive barrier. The Godot editor is a developer tool for us (the framework maintainers), not for agent developers.

Vision

The user experience should be:

1. Write agent code in agent.py
2. Run python run.py --scenario foraging
3. A game window appears, the scenario loads, and their agent starts running

One command. No Godot IDE. No manual scene selection. No pressing SPACE.

Design: Option D (Combination)

Primary flow: Python-driven launch

python run.py --scenario foraging

• Starts the Python agent server on port 5000
• Auto-launches the compiled game executable with --scenario foraging
• Game loads the scene, auto-connects to backend, auto-starts simulation

Fallback: In-game launcher menu

If the game executable is launched directly (double-click or no --scenario arg):

• Shows a simple launcher/menu scene listing available scenarios
• Each scenario shows: name, description, difficulty tier, concepts taught
• User clicks one → scene loads → waits for Python backend connection → auto-starts

Power user: CLI args to executable

agent_arena.exe --scenario foraging --port 5000 --auto-start

For scripting, CI/eval runs, and advanced workflows.

Implementation Plan

Phase 1: Godot — Launcher scene + CLI args

• Create a new scenes/launcher.tscn menu scene (simple UI with scenario cards)
• Add CLI argument parsing in a new autoload (scripts/autoload/launch_config.gd) using OS.get_cmdline_user_args()
  • --scenario <name> → load that scene directly
  • --port <number> → override IPC port (default 5000)
  • --auto-start → skip waiting for SPACE, start simulation immediately
• Set launcher.tscn as the new main scene in project.godot
• Add scene-switching logic: launcher → selected benchmark scene
• Auto-start simulation when backend connection is detected (replace SPACE-to-start for non-editor mode)

Phase 2: Godot — Export as executable

• Set up Windows export preset (export_presets.cfg)
• Configure GDExtension DLLs to be included in export
• Test exported build runs standalone (no Godot editor needed)
• Add export instructions to dev docs (for maintainers only)
• Decide on distribution: ship .exe in releases? Separate download? Git LFS?

Phase 3: Python — Auto-launch integration

• Update starter run.py scripts to accept --scenario flag
• Add game executable auto-launch: subprocess.Popen() to start the game
• Auto-detect executable location (configurable via env var or config)
• Graceful shutdown: kill game process when Python script exits
• Update run_foraging_demo.py to use new launch flow

Phase 4: Documentation

• Update all starter READMEs with new single-command workflow
• Add troubleshooting section (connection refused, executable not found, etc.)
• Update CLAUDE.md and project-context.md with new architecture
• Screenshots/GIFs of the new launcher menu and workflow

Acceptance Criteria

• python run.py --scenario foraging launches game + agent with zero manual steps
• Launching agent_arena.exe directly shows a scenario selection menu
• agent_arena.exe --scenario foraging --auto-start loads and starts immediately
• No Godot editor installation required for agent developers
• All three starters (beginner, intermediate, llm) work with new flow
• Launcher menu shows available scenarios with descriptions and difficulty tiers

Architecture Notes

Current state (what changes)

• project.godot main scene: foraging.tscn → launcher.tscn
• Simulation start: manual SPACE key → auto-start on backend connection
• Scene selection: open .tscn in editor → CLI arg or launcher menu
• Game delivery: source project → compiled executable

New autoload: LaunchConfig

Parses CLI args and exposes them as a singleton:

# scripts/autoload/launch_config.gd
var scenario: String = ""     # --scenario value, empty = show launcher
var port: int = 5000          # --port value
var auto_start: bool = false  # --auto-start flag

Existing autoloads (unchanged)

• IPCService — HTTP client to Python backend (just needs to read port from LaunchConfig)
• ToolRegistryService — tool schema management

Estimated Effort

~3-4 days across all phases (can be split across multiple PRs)

Supersedes

This issue supersedes #70 (onboarding guide with screenshots). The documentation work from #70 is captured in Phase 4, but the core approach changes from "document the Godot IDE workflow" to "eliminate the Godot IDE workflow entirely."

[justinmadison]

Cross-Platform Export Needed

Phase 2 currently only mentions Windows export. Andrew develops on Ubuntu, so we need Linux builds too.

Suggestion: Add to Phase 2:

• Set up Linux export preset (x86_64)
• Test GDExtension .so files included in Linux export
• CI-based export for both platforms (optional, but prevents manual builds)

Distribution options:

• GitHub Releases with platform-specific zip files (agent_arena_windows.zip, agent_arena_linux.zip)
• Auto-detect platform in run.py and download the right binary on first run

Also: the --auto-start flag should be the default when launched from Python's run.py. The SPACE-to-start should only apply if the user double-clicks the executable directly and wants to poke around manually first.

Related: #82 (end-to-end onboarding gate requires this to work on both platforms)