flash-mod-bridge

Live Flash / Ruffle bridge for AI agents and tools via MCP (Model Context Protocol).

Inspect a running SWF, walk the display list, get/set properties, call methods, and edit SharedObject data — without reloading for in-memory state — through a forked Ruffle player plus a Python MCP hub.

This is not stock Ruffle (no agent API). It is not AwayFL, Unity, or HTML5/Phaser (see suite links below).

Status: Early public release. Core path is desktop + Flashpoint; web inject is optional.

What you can do

Not supported: stock ruffle.rs builds (no modBridgeRpc), AwayFL runtimes, or rewriting the SWF on disk. Prefer live paths over re-decompiling ActionScript unless you have a separate pipeline.

Always start with ping_flash_bridge so you know a player/agent is connected before bulk get/set.

How it fits together

  Agent (Cursor / Claude / Grok)
       │  MCP stdio
  run_mcp.py + translator/          hub :8767
       │  HTTP
  ┌────┴──────────────────────────┐
  │ Desktop forked ruffle         │  :8768  ← Flashpoint / local SWF
  │ Web forked Ruffle + inject/   │  optional browser path
  └───────────────────────────────┘
       │
  AVM display list / SharedObject

MCP tools

Names as exposed by translator/server.py:

Connection

• ping_flash_bridge — hub health, desktop player, connected agents

• list_connected_agents — which inject/desktop endpoints are live

• flash_ping — ping the player RPC

• flash_mod_rpc — raw JSON request string to the player

Display list & values

• flash_list_display — walk tree (max_depth, limit)

• flash_find — keyword search (money, score, day, …)

• flash_list_props — properties on a path (default root)

• flash_get / flash_set — read/write by path (value_json for set)

• flash_call — path + method + args_json

SharedObject

• flash_list_so — known SharedObjects

• flash_set_so_prop — set one SO field (name, prop, value_json)

Paths

Requirements

• Windows x64 for the prebuilt desktop player (typical)

• Python 3.10+ for the MCP hub

• A patched Ruffle build with mod bridge (prebuilt release or apply engine/ yourself)

• Optional: Flashpoint for archive SWFs

• Optional: Chrome for inject/ + web selfhosted Ruffle

Upstream Ruffle quality limits AS1/AS2/AS3 compatibility — this bridge cannot fix content Ruffle cannot run.

Quick start

1. Get the patched player (recommended)

From Releases (tag continuous):

.\ruffle_desktop.exe "D:\path\to\game.swf"

Building from source is optional — see engine/README.md.

2. Run the MCP hub

git clone https://github.com/rkuhn153/flash-mod-bridge.git
cd flash-mod-bridge
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
python run_mcp.py

Hub listens on 8767 by default (FLASH_MOD_BRIDGE_PORT).

3. Wire an MCP client

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "flash-mod-bridge": {
      "command": "C:/Python313/python.exe",
      "args": ["C:/path/to/flash-mod-bridge/run_mcp.py"],
      "env": {
        "FLASH_MOD_BRIDGE_PORT": "8767"
      }
    }
  }
}

Grok Build (~/.grok/config.toml):

[mcp_servers.flash-mod-bridge]
command = 'C:\Python313\python.exe'
args = ['C:\path\to\flash-mod-bridge\run_mcp.py']
enabled = true

[mcp_servers.flash-mod-bridge.env]
FLASH_MOD_BRIDGE_PORT = "8767"

Restart the client (or reload MCP) after config changes.

4. Flashpoint (best for archive SWFs)

Pin the prebuilt player so every Flashpoint .swf launches with the bridge:

cd flash-mod-bridge\flashpoint
.\install-to-flashpoint.ps1 -DesktopExe "C:\Downloads\ruffle_desktop.exe"
# .\install-to-flashpoint.ps1 -FlashpointRoot "D:\Flashpoint" -DesktopExe "..."

Then:

1. Restart Flashpoint Launcher

2. Play any Flash game → forked Ruffle → :8768

3. MCP hub running (python run_mcp.py)

4. Agent: ping_flash_bridge

Full notes: flashpoint/README.md.

5. Web / inject (optional)

• Build web selfhosted from a patched Ruffle tree; serve host/

• Load inject/ as an unpacked Chrome extension; hard-refresh the player tab

For Flashpoint standalone you usually do not need inject.

6. First agent session

ping_flash_bridge
  → flash_list_display / flash_find
  → flash_list_props / flash_get
  → flash_set / flash_call
  → flash_list_so / flash_set_so_prop

Player JSON RPC (reference)

The desktop/web player speaks the same ops the MCP wraps:

{"op":"ping"}
{"op":"list_display","max_depth":3,"limit":100}
{"op":"list_props","path":"root"}
{"op":"get","path":"root.someProp"}
{"op":"set","path":"root.someProp","value":999999}
{"op":"call","path":"root","method":"play","args":[]}
{"op":"find","keywords":"money,tip,score","max_depth":5,"limit":60}
{"op":"list_so"}
{"op":"set_so_prop","name":"//example_so","prop":"coins","value":999}

Use flash_mod_rpc with a JSON string when you need an op not wrapped by a dedicated tool.

AI skills

Copy-Item ".\skills\flash-mod-bridge" "$env:USERPROFILE\.cursor\skills\flash-mod-bridge" -Recurse -Force

Related projects (same suite)

Limits

• Stock Ruffle has no modBridgeRpc — must use prebuilt or patched build.

• Content must run in Ruffle; bridge quality follows emulator support.

• AwayFL / some Coolmath hosts need rehost on the fork.

• Bad paths or spammy set/call can still upset a SWF.

• Nested object writes are more limited than simple primitives.

Layout

flash-mod-bridge/
  run_mcp.py              # MCP entry
  translator/             # FastMCP + HTTP hub
  inject/                 # Chrome extension agent
  host/                   # Simple self-host page
  engine/                 # Ruffle patch sources
  flashpoint/             # Install/uninstall pin scripts
  skills/flash-mod-bridge/
  samples/
  requirements.txt
  README.md
  LICENSE

License

• MCP, inject, host, samples, scripts: MIT — see LICENSE.

• Ruffle engine: MIT / Apache-2.0 (upstream). Patches in engine/ are intended for that tree.

• Prebuilt ruffle_desktop.exe includes our mod-bridge patches on top of Ruffle.