Openrct2

Tests

Bridge a running OpenRCT2 game to Cursor (or any MCP client) so AI agents can read park state, optimize parks, and build roller coasters.

Quick links: License · Issues · Third-party notices

Prerequisites

• OpenRCT2 0.5.x with RCT2 game files installed
• Python 3.11+
• Node.js 18+ (plugin packaging only)

This repo was tested against OpenRCT2 v0.5.1 on macOS.

Quick setup

# 1. Install Python deps + openrct2-bridge plugin
chmod +x scripts/*.sh
./scripts/install-bridge.sh

# 2. Install ride-builder coaster plugin
./scripts/build-plugins.sh

# 3. Launch OpenRCT2, load a park save
#    Check the in-game console for:
#      - Bridge port (starts at 20020)
#      - Ride-builder port (starts at 20021)

# 4. Verify connections (with OpenRCT2 running and a park loaded)
./scripts/check-connection.sh

# Optional: automated headless smoke test
.venv/bin/python scripts/verify-e2e.py

Cursor MCP

Project MCP config lives at .cursor/mcp.json (portable template: .cursor/mcp.json.example). Paths use ${workspaceFolder} and set PYTHONPATH to mcp-server/ so python -m openrct2_mcp resolves without a global install. Copy or adapt the example if your editor does not expand ${workspaceFolder}.

Reload MCP servers in Cursor after OpenRCT2 is running with a loaded park.

Note: End-to-end tools (live park mutations, vision capture, coaster placement) require a running OpenRCT2 instance with plugins loaded. CI runs offline unit tests only.

Example prompts:

• "Use openrct2_status, then get_park_overview and suggest three improvements."
• "List rides sorted by excitement and close the worst performer."
• "Build a small wooden coaster: coaster_create, then loop coaster_get_valid_pieces / coaster_place_piece until the circuit completes."

Architecture

Cursor AI  --MCP-->  Python MCP server  --TCP-->  openrct2-bridge (park ops)
                                              `--TCP-->  ride-builder (coasters)

Component	Role
openrct2-bridge	82 game actions, 77 state queries via pyrct2
ride-builder.js	Coaster-specific TCP API (valid pieces, place track, test ratings)
mcp-server/openrct2_mcp	Curated MCP tools wrapping both plugins

MCP tools

Park optimization

Tool	Description
openrct2_status	Connection health for bridge + ride-builder
get_park_overview	Rating, guests, cash, scenario objective
list_rides	All rides with ratings and profit (fast per-ride queries)
get_ride	One ride by id
get_park_messages	Complaints and awards
get_guest	One guest by entity id
list_guests	Guest count by default; full_scan=true for samples (slow)
place_flat_ride	Place flat rides (e.g. gentle.MERRY_GO_ROUND)
place_stall	Place stalls (e.g. stall.DRINKS_STALL)
manage_paths	Paths, queues, benches, bins
manage_staff	Hire staff, list, set patrol/orders (by staff_id)
list_staff_tool / set_staff_patrol_tool	Per-staff patrol management
assign_staff_to_path_corridor_tool	Patrol box covering path tiles
optimize_staff_coverage_tool	Hire + assign staff along main paths
park_health_report_tool	Complaints, low satisfaction, recommendations
get_map_bounds_tool / get_map_region_tool	Park-scale spatial grids
get_path_graph_tool / find_buildable_loop_tool	Path graph and build surveys
apply_theme_preset_tool	Theme along paths (see themes/cute.json)
place_small_scenery_tool / paint_terrain_tool	Decoration and terrain
set_ride_price / open_ride / close_ride	Ride operations
list_refurbish_candidates_tool	Rank rides needing refurbish by downtime and reliability (Maintenance tab metrics)
refurbish_ride_tool	Renew a ride (resets age/reliability; closes and waits for guests by default)
set_park_settings	Entrance fee, open/close park
advance_time	Step simulation ticks
get_research	Research state

Coaster building

Tool	Description
coaster_create	Start a new coaster shell
coaster_get_valid_pieces	Legal next track pieces
coaster_place_piece	Place validated track (z_is_train_entry for endpoint Z)
coaster_place_next_piece	Place next piece from valid endpoint (Z-safe)
coaster_build_perimeter	Build flexible perimeter loop along guide ring (detours around obstacles)
coaster_obstacle_map_tool	Perimeter obstacle heatmap (paths, track, scenery, slopes, unowned ring stats)
coaster_plan_route_tool	Dry-run simulate route (probe+undo, no permanent build)
coaster_plan_ahead_tool	Beam search 2–4 pieces ahead
coaster_prepare_corridor_tool	Buy/clear/flatten along guide corridor (dry_run default)
coaster_track_context_tool / coaster_full_track_context_tool	Endpoint context with height + collisions
get_tile_height_tool / coaster_site_survey_tool	Ground tile_z, slope, flat build sites near x,y
coaster_height_context_tool / coaster_probe_piece_tool	Z vs ground; per-piece collision probe
coaster_start_track_tool	Create coaster + BeginStation at surveyed tile
coaster_rank_next_pieces_tool	Rank pieces by clearance, height fit, and collisions
coaster_undo	Remove last piece
coaster_finish_station	Place entrance/exit
coaster_test	Test ride and return ratings
coaster_stats	Current excitement/intensity/nausea
coaster_delete	Demolish coaster
list_loaded_ride_objects	Valid ride object indices

Coaster workflow

1. list_loaded_ride_objects — pick a valid ride_object index
2. coaster_site_survey_tool(x, y) — find flat tile_z and nearby obstacles
3. coaster_start_track_tool(x, y) or coaster_create + manual station placement
4. Loop: coaster_rank_next_pieces_tool or coaster_probe_piece_tool → coaster_place_next_piece
5. When circuit completes: coaster_finish_station → coaster_test

Use get_tile_height_tool for a single tile; coaster_height_context_tool for endpoint Z vs ground.

Perimeter coaster workflow

1. coaster_obstacle_map_tool(inset=18) — survey ring clearance and unowned tiles on the guide ring
2. coaster_plan_route_tool(inset=18) — simulate trace without building
3. Optional: coaster_prepare_corridor_tool(dry_run=true) then apply with confirm_destructive=true
4. coaster_build_perimeter(dry_run=true) → coaster_build_perimeter — execute build

Terminal debug (no MCP): .venv/bin/python scripts/plan-coaster-route.py --simulate --inset 18

Vision (screenshots + spatial context)

The MCP server can see the park window while also returning structured map data.

Tool	What it does
capture_game_view	Screenshot of the OpenRCT2 window (returned as an MCP image)
inspect_area_at_tile	ASCII path/queue grid + nearby rides + optional screenshot

Recommended build loop:

1. inspect_area_at_tile(39, 44) — Triple Corkscrew entrance area (example)
2. Plan paths / queue / ride placement from ASCII map + screenshot
3. Apply changes via manage_paths, place_stall, coaster_*, etc.
4. capture_game_view — verify visually

macOS setup: System Settings → Privacy & Security → Screen Recording → enable Cursor (and Terminal if testing from CLI). Without this, tools fall back to text-only context.

Set OPENRCT2_VISION_MAX_WIDTH=1280 (default) to limit screenshot size.

Agent skill

See skills/openrct2-park-director/SKILL.md for orchestration workflows (perimeter coasters, cute themes, staff patrol).

Reload ride-builder after updates: ./scripts/build-plugins.sh then restart OpenRCT2 (plugin loads at launch).

Ride operations (P6)

Tool	Description
set_ride_inspection_interval_tool	Inspection every 10–120 minutes
set_ride_mode_tool / set_num_trains_tool / set_cars_per_train_tool	Throughput tuning
optimize_ride_throughput_tool	Composite fix for struggling rides (dry_run supported)
demolish_ride_tool	Demolish any ride (confirm_destructive=true)
manage_paths	Now supports remove_tile and remove_line

Land, finance, guests (P7–P9)

Tool	Description
find_open_land_tool / terraform_region_tool / buy_land_tool / clear_area_tool	Land survey and terraforming
get_finance_summary_tool / optimize_park_pricing_tool / start_marketing_campaign_tool	Business loop
fund_research_tool / scenario_progress_tool	Research and objectives
get_complaint_hotspots_tool / guest_flow_summary_tool	Guest intelligence

Advanced building and safety (P10–P11)

Tool	Description
coaster_build_along_path_tool / import_track_design_tool	Path-following coasters, clipboard designs
place_ride_at_best_tile_tool / extend_queue_tool	Smart placement
pre_change_snapshot_tool / get_action_log_tool	Safety checkpoints and action journal
Destructive tools	Require confirm_destructive=true; composites support dry_run=true

Performance

Large parks (1000+ guests, many rides) make bulk bridge queries slow or prone to timeout.

The MCP server avoids the worst patterns:

Slow (avoid)	Fast (used instead)
rides (all at once)	listAllRides + rides?id=N per ride
guests (all peeps)	park.guests count + get_guest(id)
game.state.park() for overview	Scalar park.name, park.rating, park.cash, …
Tile-by-tile map scans	Not exposed via MCP (too many round-trips)
Footpath scan (fill benches/bins)	get_elements_by_type("footpath") bulk first; tile chunk fallback

list_guests defaults to guest count only. Pass full_scan=true only if you accept a long wait.

Reload the MCP server after pulling performance updates.

Configuration

Environment variables (set in .cursor/mcp.json):

Variable	Default	Purpose
OPENRCT2_BRIDGE_PORT	20020	Bridge plugin TCP port
OPENRCT2_RIDE_BUILDER_PORT	20021	Ride-builder TCP port
OPENRCT2_BRIDGE_TIMEOUT	30	Per-request bridge timeout (seconds)
OPENRCT2_RIDE_BUILDER_TIMEOUT	15	Per-request ride-builder timeout (seconds)

OpenRCT2 config.ini recommendations:

• macOS: ~/Library/Application Support/OpenRCT2/config.ini
• Linux: ~/.config/OpenRCT2/config.ini

Override the user data directory with OPENRCT2_USER_PATH (used by install-bridge.sh).

[plugin]
enable_hot_reloading = true

install-bridge.sh enables hot reloading automatically.

Contributing

1. ./scripts/install-bridge.sh — Python venv, bridge plugin, hot reload
2. ./scripts/build-plugins.sh — ride-builder plugin
3. pytest mcp-server/tests -q — offline unit tests (no OpenRCT2 required)
4. .venv/bin/python scripts/verify-e2e.py — optional smoke test with OpenRCT2 running

Development

# Run MCP server manually
export PYTHONPATH=mcp-server
.venv/bin/python -m openrct2_mcp

# Rebuild ride-builder after edits
./scripts/build-plugins.sh
# Reload plugin in-game (hot reload) or restart OpenRCT2

Safety notes

• Building tools pause the game before mutations.
• build_in_pause_mode cheat is enabled on connect for automation.
• Coaster tools require the ride-builder plugin; park tools require openrct2-bridge.

License

MIT. See NOTICE for third-party attribution. Ride-builder plugin derived from openrct2-ridecreation-api.