Skip to main content

Visualization

AgentOdyssey includes a browser-based trajectory visualizer that replays an agent's gameplay on an interactive world map. It shows the agent moving between areas step by step, with the full observation text, chosen action, reward breakdown, and area contents (NPCs, objects) at each step. The visualizer tooling lives in tools/visualizer/.

Trajectory Visualizer​

The main entry point is tools/visualizer/main.py. It reads the agent's log and the game configuration, builds the world graph, generates area icons if needed, and launches a local HTTP server that opens an interactive HTML page in your browser.

python tools/visualizer/main.py \
  --agent_log <path_to_agent_log.jsonl> \
  --world_definition_path <path_to_world_definition.json> \
  --config <path_to_config.jsonl>

This starts a server on localhost:8003 and opens the visualizer in your default browser. The --config path must point to a .jsonl file (the cumulative config log, not a plain .json). You can generate a config.jsonl from a config.json using tools/generate_cumulative_config.py.

The visualizer displays a force-directed world graph where each area is a circular node with a background icon. Places are shown as grouped outlines. Locked edges appear as dashed lines. The agent's trajectory is drawn as a path with directional arrows, and a pulsing marker shows the agent's current position. Hovering over an area node expands it to show the NPCs and objects currently in that area.

Useful flags:

  • --port 8080 to change the server port.
  • --no_browser to start the server without auto-opening a browser window.
  • --skip_assets_generation to skip icon generation if icons already exist.
  • --bundle output/my_bundle to produce a self-contained folder with the HTML, data, and icons that can be shared or hosted statically.
  • --stats_only to print trajectory statistics (steps, areas visited, reward breakdown, action distribution) to the terminal and exit without launching the server.

Area Icons​

Area icons are generated by tools/visualizer/generate_assets.py. By default, main.py calls this automatically, so you do not need to run it separately. If you want to pre-generate or regenerate icons independently:

python tools/visualizer/generate_assets.py \
  --world_definition_path assets/world_definitions/generated/v1/default.json \
  --output_dir assets/visualizer_icons

This uses a diffusion model to generate scene images for each area. If you don't have a GPU or don't want to run the diffusion model, pass --no_diffusion to generate simple colored placeholder icons instead.

Other Utilities​

Dependency graph. tools/visualizer/dep_graph.py takes a dependency tracker JSON export and produces Mermaid flowcharts or SVG timeline diagrams showing causal chains across steps:

python tools/visualizer/dep_graph.py dep.json --format svg -o graph.svg

Interactive web game. tools/web_server.py is a Flask app that lets a human play the game in a browser. It is separate from the trajectory visualizer and is useful for exploring the game world manually:

python tools/web_server.py --port 5000