ue-bridge 1.0.0__tar.gz

ue_bridge-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+dist/
+*.egg-info/

ue_bridge-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rabbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ue_bridge-1.0.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: ue-bridge
+Version: 1.0.0
+Summary: Talk to a running UE4SS game: inspect objects, call functions, run Lua, while it plays. An MCP server and CLI plus the UEBridge mod.
+Project-URL: Source, https://github.com/littleRabbit94/ue-bridge
+License: MIT
+License-File: LICENSE
+Keywords: lua,mcp,modding,ue4ss,unreal
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.8
+Description-Content-Type: text/markdown
+
+# ue-bridge
+
+Talk to a running [UE4SS](https://github.com/UE4SS-RE/RE-UE4SS) game: inspect objects, call
+functions, run Lua, while it plays. Two parts, released separately:
+
+| Part | What | Where it goes |
+|---|---|---|
+| **UEBridge** (Lua mod) | Polls `ue4ss\bridge\request.json`, runs the request on the game thread, writes `response.json`. Game-agnostic. | The game: `ue4ss\Mods\UEBridge\` (Nexus / GitHub release zip) |
+| **ue-bridge** (Python) | An MCP server and CLI that write those files and read the answers. Finds the running game by itself. | Your machine: `uvx ue-bridge` or `pip install ue-bridge` |
+
+```
+AI agent / script  ->  ue-bridge (MCP stdio or HTTP, or CLI)  ->  request.json
+                                                                 UEBridge mod: ExecuteInGameThread
+                       ue-bridge  <-  response.json           <-
+```
+
+No sockets in the game, no admin rights, no changes to the game binary. The mod opens no network
+connection and starts no process. Only software already running on the same machine with write
+access to the game folder can talk to it.
+
+## Install the mod
+
+Extract the release zip into the game's install folder. It carries the path, so the files land in
+`<game>\<Project>\Binaries\Win64\ue4ss\Mods\UEBridge`. `enabled.txt` in that folder starts the
+mod; **no `mods.txt` edit**. `UE4SS.log` shows `[UEBridge] v1.0.0 ready` when it loaded.
+
+`scripts\settings.lua` in the mod folder:
+
+| Key | Default | Effect |
+|---|---|---|
+| `enabled` | `true` | `false` stops polling entirely |
+| `poll_ms` | `250` | request file check interval |
+| `allow_eval` | `true` | `false` refuses raw Lua (`eval_lua`); structured tools still work |
+| `allow_writes` | `true` | `false` is read-only: `set_property`, `call_function`, `console_command` and `eval_lua` are refused |
+| `bridge_dir` | unset | absolute path override for the request/response folder |
+
+## Install the server and point an agent at it
+
+Any MCP client works. The server finds the running game (an exe in a `Binaries\Win64` folder with
+`ue4ss\` beside it), so no path needs configuring; pass `--game-dir` or set `UE_BRIDGE_GAME_DIR` to
+pin one.
+
+**stdio** (Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Continue, ...):
+
+```json
+{ "mcpServers": { "ue-bridge": { "command": "uvx", "args": ["ue-bridge"] } } }
+```
+
+```bash
+claude mcp add ue-bridge -- uvx ue-bridge
+```
+
+**HTTP** (one long-running server, several clients): `ue-bridge --http` serves streamable-HTTP MCP
+on `http://127.0.0.1:8930/mcp`, loopback only.
+
+```bash
+claude mcp add --transport http ue-bridge http://127.0.0.1:8930/mcp
+```
+
+**Shell**, for scripts and for testing the channel:
+
+```bash
+ue-bridge status
+ue-bridge hello
+ue-bridge eval "return UEB.world()"
+ue-bridge props first:PlayerController
+ue-bridge types ^Narrative
+```
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `bridge_status` | Game found, running, mod answering, mod version and permissions, round-trip time. Call first. |
+| `eval_lua(code, timeout)` | Any Lua chunk on the game thread. Whole UE4SS API plus the `UEB` helpers in scope; `print` output captured. |
+| `world_info` | World, player controller, pawn, game instance, game mode. |
+| `find_object(path)` / `find_objects(class, limit)` | Resolve one reference / list live instances of a class. |
+| `list_types(pattern, limit)` | Loaded reflected types matching a Lua pattern. |
+| `inspect_object(ref, include_super, pattern)` | Every reflected property with its value. |
+| `list_functions(ref)` | Every UFunction on the class chain. |
+| `get_property` / `set_property` | One property. `set` returns `{previous, current}`. |
+| `call_function(ref, fn, args)` | Call a UFunction with positional args. |
+| `console_command(cmd)` | Run a console command. |
+| `batch(calls)` | Several of the above in one round trip. |
+| `dump(kind)` | UE4SS dumpers: `usmap`, `jmap`, `uht`, `cxx`, `actors`, `objects`, `static_meshes`. |
+
+Every tool except `eval_lua` goes through the structured `batch` op, so they keep working when a
+user turns `allow_eval` off.
+
+**Object references**: `/Script/Pkg.Object` (any full path), `first:ShortClassName` (first live
+instance), `cdo:/Script/Pkg.Class` (class default object).
+
+**Serialisation**: UObjects become `{"__object": fullname, "address": n}`, `FName`/`FString`/`FText`
+become strings, `TArray` becomes a list (first 200), structs are walked through their reflected
+type including inherited fields. `SoftObjectProperty` values are skipped by default (reading one
+has hard-crashed a game inside UE4SS's own property reader).
+
+## Wire protocol (1)
+
+```
+request : {"id": str, "op": "hello"|"ping"|"eval"|"batch", "code": str, "calls": [ {op, ...} ]}
+response: {"id", "ok": bool, "result", "output": [str], "error": str|null, "ms": int, "protocol": 1}
+```
+
+`hello` returns the mod's version, protocol and permissions; the server refuses to proceed on a
+protocol mismatch. Anything that can write a JSON file can be a client.
+
+## Failure modes
+
+- **Request never picked up**: no game running, or the mod is not installed or is disabled.
+  Check for `[UEBridge] ... ready` in `UE4SS.log`.
+- **Picked up, no response**: the game thread is blocked (loading screen) or the request is long.
+  `dump` uses a 600 s timeout for that reason. If the process is gone, the error names the
+  in-flight operation from `bridge\lastop.log` and the newest crash report.
+- **One request at a time.** A `request.json` younger than 10 s is another client's; older is a
+  leftover and is reclaimed.
+
+## Developing
+
+```
+uv venv --python 3.11 .venv
+uv pip install --python .venv\Scripts\python.exe "mcp>=1.8,<2"
+.venv\Scripts\python.exe -m ue_bridge status        # from the repo root
+python tools/build-release.py                       # dist/UEBridge-<version>.zip
+```
+
+Edit `ue4ss/UEBridge/scripts/main.lua`, then `ue-bridge eval "return UEB.reload()"`: the mod
+re-runs its source in place and retires the old poll loop, no relaunch.
+
+MIT.

ue_bridge-1.0.0/README.md

@@ -0,0 +1,130 @@
+# ue-bridge
+
+Talk to a running [UE4SS](https://github.com/UE4SS-RE/RE-UE4SS) game: inspect objects, call
+functions, run Lua, while it plays. Two parts, released separately:
+
+| Part | What | Where it goes |
+|---|---|---|
+| **UEBridge** (Lua mod) | Polls `ue4ss\bridge\request.json`, runs the request on the game thread, writes `response.json`. Game-agnostic. | The game: `ue4ss\Mods\UEBridge\` (Nexus / GitHub release zip) |
+| **ue-bridge** (Python) | An MCP server and CLI that write those files and read the answers. Finds the running game by itself. | Your machine: `uvx ue-bridge` or `pip install ue-bridge` |
+
+```
+AI agent / script  ->  ue-bridge (MCP stdio or HTTP, or CLI)  ->  request.json
+                                                                 UEBridge mod: ExecuteInGameThread
+                       ue-bridge  <-  response.json           <-
+```
+
+No sockets in the game, no admin rights, no changes to the game binary. The mod opens no network
+connection and starts no process. Only software already running on the same machine with write
+access to the game folder can talk to it.
+
+## Install the mod
+
+Extract the release zip into the game's install folder. It carries the path, so the files land in
+`<game>\<Project>\Binaries\Win64\ue4ss\Mods\UEBridge`. `enabled.txt` in that folder starts the
+mod; **no `mods.txt` edit**. `UE4SS.log` shows `[UEBridge] v1.0.0 ready` when it loaded.
+
+`scripts\settings.lua` in the mod folder:
+
+| Key | Default | Effect |
+|---|---|---|
+| `enabled` | `true` | `false` stops polling entirely |
+| `poll_ms` | `250` | request file check interval |
+| `allow_eval` | `true` | `false` refuses raw Lua (`eval_lua`); structured tools still work |
+| `allow_writes` | `true` | `false` is read-only: `set_property`, `call_function`, `console_command` and `eval_lua` are refused |
+| `bridge_dir` | unset | absolute path override for the request/response folder |
+
+## Install the server and point an agent at it
+
+Any MCP client works. The server finds the running game (an exe in a `Binaries\Win64` folder with
+`ue4ss\` beside it), so no path needs configuring; pass `--game-dir` or set `UE_BRIDGE_GAME_DIR` to
+pin one.
+
+**stdio** (Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Continue, ...):
+
+```json
+{ "mcpServers": { "ue-bridge": { "command": "uvx", "args": ["ue-bridge"] } } }
+```
+
+```bash
+claude mcp add ue-bridge -- uvx ue-bridge
+```
+
+**HTTP** (one long-running server, several clients): `ue-bridge --http` serves streamable-HTTP MCP
+on `http://127.0.0.1:8930/mcp`, loopback only.
+
+```bash
+claude mcp add --transport http ue-bridge http://127.0.0.1:8930/mcp
+```
+
+**Shell**, for scripts and for testing the channel:
+
+```bash
+ue-bridge status
+ue-bridge hello
+ue-bridge eval "return UEB.world()"
+ue-bridge props first:PlayerController
+ue-bridge types ^Narrative
+```
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `bridge_status` | Game found, running, mod answering, mod version and permissions, round-trip time. Call first. |
+| `eval_lua(code, timeout)` | Any Lua chunk on the game thread. Whole UE4SS API plus the `UEB` helpers in scope; `print` output captured. |
+| `world_info` | World, player controller, pawn, game instance, game mode. |
+| `find_object(path)` / `find_objects(class, limit)` | Resolve one reference / list live instances of a class. |
+| `list_types(pattern, limit)` | Loaded reflected types matching a Lua pattern. |
+| `inspect_object(ref, include_super, pattern)` | Every reflected property with its value. |
+| `list_functions(ref)` | Every UFunction on the class chain. |
+| `get_property` / `set_property` | One property. `set` returns `{previous, current}`. |
+| `call_function(ref, fn, args)` | Call a UFunction with positional args. |
+| `console_command(cmd)` | Run a console command. |
+| `batch(calls)` | Several of the above in one round trip. |
+| `dump(kind)` | UE4SS dumpers: `usmap`, `jmap`, `uht`, `cxx`, `actors`, `objects`, `static_meshes`. |
+
+Every tool except `eval_lua` goes through the structured `batch` op, so they keep working when a
+user turns `allow_eval` off.
+
+**Object references**: `/Script/Pkg.Object` (any full path), `first:ShortClassName` (first live
+instance), `cdo:/Script/Pkg.Class` (class default object).
+
+**Serialisation**: UObjects become `{"__object": fullname, "address": n}`, `FName`/`FString`/`FText`
+become strings, `TArray` becomes a list (first 200), structs are walked through their reflected
+type including inherited fields. `SoftObjectProperty` values are skipped by default (reading one
+has hard-crashed a game inside UE4SS's own property reader).
+
+## Wire protocol (1)
+
+```
+request : {"id": str, "op": "hello"|"ping"|"eval"|"batch", "code": str, "calls": [ {op, ...} ]}
+response: {"id", "ok": bool, "result", "output": [str], "error": str|null, "ms": int, "protocol": 1}
+```
+
+`hello` returns the mod's version, protocol and permissions; the server refuses to proceed on a
+protocol mismatch. Anything that can write a JSON file can be a client.
+
+## Failure modes
+
+- **Request never picked up**: no game running, or the mod is not installed or is disabled.
+  Check for `[UEBridge] ... ready` in `UE4SS.log`.
+- **Picked up, no response**: the game thread is blocked (loading screen) or the request is long.
+  `dump` uses a 600 s timeout for that reason. If the process is gone, the error names the
+  in-flight operation from `bridge\lastop.log` and the newest crash report.
+- **One request at a time.** A `request.json` younger than 10 s is another client's; older is a
+  leftover and is reclaimed.
+
+## Developing
+
+```
+uv venv --python 3.11 .venv
+uv pip install --python .venv\Scripts\python.exe "mcp>=1.8,<2"
+.venv\Scripts\python.exe -m ue_bridge status        # from the repo root
+python tools/build-release.py                       # dist/UEBridge-<version>.zip
+```
+
+Edit `ue4ss/UEBridge/scripts/main.lua`, then `ue-bridge eval "return UEB.reload()"`: the mod
+re-runs its source in place and retires the old poll loop, no relaunch.
+
+MIT.

ue_bridge-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ue-bridge"
+version = "1.0.0"
+description = "Talk to a running UE4SS game: inspect objects, call functions, run Lua, while it plays. An MCP server and CLI plus the UEBridge mod."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["unreal", "ue4ss", "mcp", "modding", "lua"]
+classifiers = [
+    "Environment :: Win32 (MS Windows)",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment",
+]
+# 1.8 is where streamable HTTP arrived; 2.x renamed FastMCP.
+dependencies = ["mcp>=1.8,<2"]
+
+[project.scripts]
+ue-bridge = "ue_bridge.server:main"
+
+[project.urls]
+Source = "https://github.com/littleRabbit94/ue-bridge"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ue_bridge"]
+
+[tool.hatch.build.targets.sdist]
+include = ["ue_bridge", "ue4ss", "README.md", "LICENSE"]

ue_bridge-1.0.0/ue4ss/UEBridge/mod.toml

@@ -0,0 +1,14 @@
+schema = 1
+
+[mod]
+id          = "ue-bridge"
+name        = "UEBridge"
+version     = "1.0.0"
+author      = "Rabbit"
+description = "Lua side of the ue-bridge live MCP bridge; game-agnostic, the server is the ue_bridge Python package."
+
+[[lua]]
+name    = "UEBridge"
+source  = "."
+order   = 400
+enabled = true

ue_bridge-1.0.0/ue4ss/UEBridge/scripts/json.lua

@@ -0,0 +1,165 @@
+-- Minimal JSON encode/decode for UEBridge. Pure Lua 5.4, no dependencies.
+-- Encodes: nil, boolean, number, string, table (array if keys are 1..n, else object).
+-- Non-finite numbers encode as null. Decodes the full JSON grammar including \uXXXX.
+
+local json = {}
+
+local escapes = { ['"'] = '\\"', ['\\'] = '\\\\', ['\b'] = '\\b', ['\f'] = '\\f',
+                  ['\n'] = '\\n', ['\r'] = '\\r', ['\t'] = '\\t' }
+
+local function escapeStr(s)
+    return '"' .. s:gsub('[%c"\\]', function(c)
+        return escapes[c] or string.format('\\u%04x', c:byte())
+    end) .. '"'
+end
+
+local function isArray(t)
+    local n = 0
+    for k in pairs(t) do
+        if type(k) ~= "number" or k <= 0 or math.floor(k) ~= k then return false end
+        n = n + 1
+    end
+    for i = 1, n do if t[i] == nil then return false end end
+    return true, n
+end
+
+local function encode(v, seen)
+    local tv = type(v)
+    if v == nil then return "null" end
+    if tv == "boolean" then return v and "true" or "false" end
+    if tv == "number" then
+        if v ~= v or v == math.huge or v == -math.huge then return "null" end
+        if math.type(v) == "integer" then return tostring(v) end
+        return string.format("%.17g", v)
+    end
+    if tv == "string" then return escapeStr(v) end
+    if tv == "table" then
+        seen = seen or {}
+        if seen[v] then return '"<cycle>"' end
+        seen[v] = true
+        local out = {}
+        local arr, n = isArray(v)
+        if arr then
+            for i = 1, n do out[i] = encode(v[i], seen) end
+            seen[v] = nil
+            return "[" .. table.concat(out, ",") .. "]"
+        end
+        local keys = {}
+        for k in pairs(v) do keys[#keys + 1] = k end
+        table.sort(keys, function(a, b) return tostring(a) < tostring(b) end)
+        for _, k in ipairs(keys) do
+            out[#out + 1] = escapeStr(tostring(k)) .. ":" .. encode(v[k], seen)
+        end
+        seen[v] = nil
+        return "{" .. table.concat(out, ",") .. "}"
+    end
+    return escapeStr(tostring(v))
+end
+
+function json.encode(v) return encode(v, nil) end
+
+-- Decoder -------------------------------------------------------------------------------
+
+local function decodeError(str, pos, msg)
+    error(string.format("json: %s at position %d (%s)", msg, pos, str:sub(pos, pos + 20)), 0)
+end
+
+local function skipWs(str, pos)
+    return str:find("[^ \t\r\n]", pos) or #str + 1
+end
+
+local decodeValue
+
+local simpleEscapes = { b = "\b", f = "\f", n = "\n", r = "\r", t = "\t",
+                        ['"'] = '"', ["\\"] = "\\", ["/"] = "/" }
+
+local function decodeString(str, pos)
+    local out, i = {}, pos + 1
+    while true do
+        local c = str:sub(i, i)
+        if c == "" then decodeError(str, i, "unterminated string") end
+        if c == '"' then return table.concat(out), i + 1 end
+        if c == "\\" then
+            local e = str:sub(i + 1, i + 1)
+            if simpleEscapes[e] then
+                out[#out + 1] = simpleEscapes[e]
+                i = i + 2
+            elseif e == "u" then
+                local cp = tonumber(str:sub(i + 2, i + 5), 16)
+                if not cp then decodeError(str, i, "bad \\u escape") end
+                i = i + 6
+                if cp >= 0xD800 and cp <= 0xDBFF and str:sub(i, i + 1) == "\\u" then
+                    local lo = tonumber(str:sub(i + 2, i + 5), 16)
+                    if lo and lo >= 0xDC00 and lo <= 0xDFFF then
+                        cp = 0x10000 + (cp - 0xD800) * 0x400 + (lo - 0xDC00)
+                        i = i + 6
+                    end
+                end
+                out[#out + 1] = utf8.char(cp)
+            else
+                decodeError(str, i, "bad escape")
+            end
+        else
+            local j = str:find('["\\]', i) or (#str + 1)
+            out[#out + 1] = str:sub(i, j - 1)
+            i = j
+        end
+    end
+end
+
+function decodeValue(str, pos)
+    pos = skipWs(str, pos)
+    local c = str:sub(pos, pos)
+    if c == "{" then
+        local obj = {}
+        pos = skipWs(str, pos + 1)
+        if str:sub(pos, pos) == "}" then return obj, pos + 1 end
+        while true do
+            pos = skipWs(str, pos)
+            if str:sub(pos, pos) ~= '"' then decodeError(str, pos, "expected key") end
+            local key; key, pos = decodeString(str, pos)
+            pos = skipWs(str, pos)
+            if str:sub(pos, pos) ~= ":" then decodeError(str, pos, "expected ':'") end
+            local val; val, pos = decodeValue(str, pos + 1)
+            obj[key] = val
+            pos = skipWs(str, pos)
+            local d = str:sub(pos, pos)
+            if d == "}" then return obj, pos + 1 end
+            if d ~= "," then decodeError(str, pos, "expected ',' or '}'") end
+            pos = pos + 1
+        end
+    elseif c == "[" then
+        local arr = {}
+        pos = skipWs(str, pos + 1)
+        if str:sub(pos, pos) == "]" then return arr, pos + 1 end
+        while true do
+            local val; val, pos = decodeValue(str, pos)
+            arr[#arr + 1] = val
+            pos = skipWs(str, pos)
+            local d = str:sub(pos, pos)
+            if d == "]" then return arr, pos + 1 end
+            if d ~= "," then decodeError(str, pos, "expected ',' or ']'") end
+            pos = pos + 1
+        end
+    elseif c == '"' then
+        return decodeString(str, pos)
+    elseif str:sub(pos, pos + 3) == "true" then return true, pos + 4
+    elseif str:sub(pos, pos + 4) == "false" then return false, pos + 5
+    elseif str:sub(pos, pos + 3) == "null" then return nil, pos + 4
+    else
+        local num = str:match("^-?%d+%.?%d*[eE]?[-+]?%d*", pos)
+        if not num or num == "" then decodeError(str, pos, "unexpected character") end
+        local n = tonumber(num)
+        if not n then decodeError(str, pos, "bad number") end
+        return n, pos + #num
+    end
+end
+
+function json.decode(str)
+    local v, pos = decodeValue(str, 1)
+    pos = skipWs(str, pos)
+    if pos <= #str then decodeError(str, pos, "trailing garbage") end
+    return v
+end
+
+return json