react-godot-bridge

Bidirectional, event-driven bridge between a React / Next.js app and a Godot 4 WebAssembly game running inside an <iframe>.

Designed to feel like Socket.io — you just call emit("event") and on("event"). The library handles the iframe, postMessage, and JavaScriptBridge complexity underneath.

---

Repository Structure

react-godot-bridge/
  addons/           ← Godot plugin (Asset Library & manual install)
  npm/              ← npm package source  (published as "react-godot-bridge")
  example/          ← Next.js demo app

---

React / Next.js — npm package

npm install react-godot-bridge

import { GodotBridgeProvider, GodotFrame, useGodot } from 'react-godot-bridge';

// Wrap your layout
<GodotBridgeProvider appKey={process.env.NEXT_PUBLIC_BRIDGE_KEY ?? ''}>
  <GodotFrame src="/game/index.html" className="w-full h-screen" />
  <HUD />
</GodotBridgeProvider>

// Use anywhere inside the Provider
const { emit, on } = useGodot();
emit('jump', { height: 2 });
const unsub = on('player_died', (p) => setScore(p.score as number));

See npm/README.md for full API docs.

---

Godot — Plugin

Option A — Godot Asset Library (recommended) Search ReactBridge in the AssetLib tab inside the Godot editor and click Install.

Option B — Manual Copy addons/react_bridge/ from this repo into your Godot project root, then add the autoload in Project Settings:

[autoload]
ReactBridge="*res://addons/react_bridge/ReactBridge.gd"

# Receive from React
func _ready():
    ReactBridge.on_react_event.connect(_on_event)

func _on_event(event: String, data: Dictionary):
    if event == "jump":
        $Player.position.y += data.get("height", 1.0)

# Send to React
ReactBridge.emit_to_react("player_died", { "score": 1500 })

See addons/react_bridge/README.md for full docs.

---

How It Works

React                              Godot (iframe)
──────                             ──────────────
emit("jump", { height: 2 })
  → postMessage(envelope)    →     ReactBridge._on_message()
                                     on_react_event.emit("jump", data)
                                       $Player.position.y += data.height
                                     ReactBridge.emit_to_react("pong", {...})
  on("pong", cb) ←           ←       window.parent.postMessage(envelope)

All messages use a standard JSON envelope:

{
  "event": "jump",
  "payload": { "height": 2 },
  "metadata": { "secret": "APP_KEY", "timestamp": 1711910000 }
}

---

Links

• npm — npmjs.com/package/react-godot-bridge
• GitHub — github.com/MakerDZ/react-godot-bridge