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).

Piece	Path	Role
Patched Ruffle (desktop)	Releases → ruffle_desktop.exe	Play SWF + HTTP mod bridge :8768
Engine patches	engine/	modBridgeRpc sources to drop into a Ruffle tree
MCP hub	run_mcp.py, translator/	FastMCP tools (hub :8767)
Chrome inject	inject/	Optional page agent for web Ruffle
Self-host page	host/	Simple local player host
Flashpoint pin	flashpoint/	Install fork as Flashpoint’s default Ruffle
Agent skill	skills/flash-mod-bridge/	How agents should use the tools

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

What you can do

Area	Capabilities
Discover	List display tree, find by keywords, list props on a path
Read / write	Get/set AVM properties by path (root, stage, root/Child)
Call	Invoke methods on display objects with JSON args
SharedObject	List SOs, set SO properties (saves / persistent data)
Raw RPC	Pass through any player JSON op via flash_mod_rpc
Transport	Desktop HTTP bridge, or Chrome inject when using web Ruffle

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

Port	Who
8767	Python MCP hub (agents connect here)
8768	Desktop Ruffle mod-bridge HTTP (hub falls back here)
8765 / 8766	Other suite tools (Unity WebGL / HTML5) — not this repo

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

Path	Meaning
stage	Stage AS3 object
root	Root movie clip
root/Child/Grand	Display-list walk
so:name	Live SharedObject data
so:name|prop	SO property (| when name has / or .)

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):

Asset	Role
ruffle_desktop.exe	Patched Ruffle + mod bridge (:8768)
flash-mod-bridge-mcp.zip	Python hub + inject/host (optional zip)

.\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

Detail
Installed as	%Flashpoint%\Data\Ruffle\standalone\latest\ruffle.exe
Pin	Data\Ruffle\.mod-bridge-pin (blocks stock auto-update)
Undo	flashpoint\uninstall-pin.ps1

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

Skill	Role
skills/flash-mod-bridge	Tool order, paths, Flashpoint, limits

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

Related projects (same suite)

Need	Repo
Live Flash / Ruffle (this)	flash-mod-bridge
Live Unity get/set/patch	bepinex-mcp
Live Unreal runtime (UE4SS)	unreal-engine-mcp
Mono C# search	gamecode-rag
IL2CPP static decompile	il2cpp-decompiler

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.