Play Mosslight — the live island adventure · No SDK installation needed.
An open-source skill for understanding game files, choosing a porting route,
and building a browser version you can actually play.
Codex · Claude Code · Agent Skills compatible harnesses
Quick start · How it works · Game types · Helpers · FAQ · Documentation
Have a game project gathering dust, or an old game that only runs on one machine? Give your agent the files. port2browser guides it through finding the engine, mapping the platform dependencies, and getting a small slice playable in a browser. When the files are not enough, the result is a concrete explanation of what is missing.
The repository contains a portable routing skill, 12 task skills, engine-specific playbooks, and three optional Python helpers. Your agent uses its own tools to do the engineering.
A small browser game you can interact with, plus a report stating exactly what was built, tested, and left unresolved. The original examples use generated shapes and sound, so you can inspect and share them.
From the Mosslight port report:
Status: playable slice — complete original island game, tested scope below. Target: desktop Chromium and Firefox; native C++ and raw/compressed Wasm.
Explore, collect three sunstones, avoid thorns, and restore the lighthouse. The
live demo runs locally in your browser, with generated artwork/sound and durable
saves. Try it, then
reproduce the C++ port and compressed release.
It demonstrates one original game, not automatic conversion of arbitrary files.
For an agent-produced handoff, read the actual JavaScript pilot report.
It reported build_only; separate browser replay evidence is recorded in the
paired pilot.
Clone this repository into your agent's skill directory, keeping the folder
named port2browser and its supporting files together. Git is enough to install
the skill. The optional helpers require Python 3.10+ with no extra packages;
each game route has its own engine/SDK requirements.
mkdir -p ~/.agents/skills
git clone https://github.com/infinuts/port2browser.git ~/.agents/skills/port2browserThen ask:
Use $port2browser on ./my-game. Identify the engine and dependencies, choose
a browser porting route, and get one level playable with keyboard and audio.
Keep the desktop build working. Target desktop Chrome and Firefox first.
mkdir -p ~/.claude/skills
git clone https://github.com/infinuts/port2browser.git ~/.claude/skills/port2browserThen ask:
/port2browser Assess ./my-game for a browser port, then build and test the
smallest playable slice. Record blockers and the commands needed to run it.
Start a new session after installing. Other Agent Skills compatible harnesses can load the same skill directory using their own discovery instructions. See the official Codex and Claude Code documentation.
Windows, project-only installs, and updates
On Windows, use PowerShell. Change .agents to .claude for Claude Code:
$skillParent = Join-Path $env:USERPROFILE '.agents\skills'
New-Item -ItemType Directory -Force -Path $skillParent | Out-Null
git clone https://github.com/infinuts/port2browser.git (Join-Path $skillParent 'port2browser')For a project-only install, use .agents/skills/port2browser (Codex) or
.claude/skills/port2browser (Claude Code) inside that project. To vendor the
skill without a nested Git repository, copy SKILL.md, references/, scripts/,
skills/ and LICENSE into that folder. Keep those paths together when updating.
Update a cloned install with git -C /path/to/port2browser pull --ff-only.
Pin a reviewed commit with git -C /path/to/port2browser checkout <commit> when
you need a repeatable setup. To uninstall, remove that skill folder from your
agent's discovery directory.
The entrypoint loads only the instructions needed for the current task. Each
folder below has its own SKILL.md and license; engine notes live beside the
export, native and framework skills.
| Task folder | Responsibility |
|---|---|
| recon | Read-only inventory, versions, source completeness and conflicting clues |
| route | Feasibility, dependency ledger and hardest-first experiments |
| export | Unity, Godot, Unreal forks, Defold, Cocos, authoring tools and Ren'Py |
| native | C/C++, Emscripten, rendering backends and middleware |
| frameworks | Rust, Java, .NET, Haxe, Lua and Python runtimes |
| web | Electron/NW.js, RPG Maker and JavaScript libraries |
| open-runtime | Compatible open engines and legacy emulation |
| reverse | Bounded behavioral and format investigation |
| platform | Graphics, scheduling, input, sound, storage and network services |
| assets | Content reduction, compression, streaming and decoded-memory budgets |
| verify | Actual browser input, output, state, audio, focus and reload evidence |
| release | Allowlisted packaging, hosting and accurate port reports |
The 36-route catalog documents prerequisites, first probes and blockers. These are engineering workflows, not 36 demonstrated ports. Modern games require their own assessment of source access, renderer, shaders, plugins, middleware, asset memory and online services. An Unreal 4 HTML5 fork does not establish UE5 support; a desktop mod loader does not establish a browser runtime. Preserve gameplay and disclose any proposed reduced scope.
A normal clone keeps these modules inside the port2browser bundle. To make
separate task skills discoverable, contributors can create a minimal collection:
# Run from this checkout; choose a new directory outside the checkout.
python3 tools/package_skills.py --layout collection --output ../port2browser-skills
# Or create one minimal bundle, without examples or development dependencies:
python3 tools/package_skills.py --layout bundle --output ../port2browser-bundleCopy the generated folders into your harness's skill directory following its own discovery instructions. Collection packaging adjusts cross-folder links; bundle packaging retains local task modules. Neither command installs tools or starts agents. Separately discovered task invocation has packaging checks, but has not received a new blind agent evaluation. The recorded pilot predates this modular workflow and does not establish its effectiveness.
The original fixtures use MIT game logic, generated shapes, and generated sound. Engine runtimes/fonts retain their own terms. AssaultCube uses upstream source and locally selected game media. They are optional development material; installing the skill needs none of their toolchains or Node packages.
- AssaultCube: experimental C++/Wasm offline bot match using locally selected, hash-verified upstream game media. Includes browser instructions and a separate license notice.
- Mosslight: playable C++ island adventure, raw/optimized/gzip size comparison, native and compressed browser builds.
- Macroquad Beacon: Rust/Macroquad source compiled to Wasm with IndexedDB/Web Audio adaptation.
- LÖVE Beacon: Lua in a pinned love.js runtime, explicit audio activation and awaited IDBFS saves.
- SDL Beacon: minimal native C and Wasm regression fixture.
- Godot Beacon: native GDScript scene exported with the matching web runtime.
- Electron Beacon: filesystem/IPC desktop services adapted to browser storage and menu handling.
For the SDL example, activate Emscripten 4.0.16, then run from this repo:
python3 examples/sdl-beacon/build.py web
python3 scripts/serve.py examples/sdl-beacon/build/web --port 8000Open http://127.0.0.1:8000/, click Start, press Right eight times, Space, and S.
Expect position 120, a collected beacon, and Save ready; reload to check the
saved state. The completed report records
actual tested versions and limits. With Node.js 22+ and npm, optional automation:
npm ci
npx playwright install chromium firefox
# Build Godot with the pinned editor/templates first; see its README.
python3 examples/godot-beacon/build.py web
python3 examples/mosslight/build.py debug-web
python3 examples/mosslight/build.py web
python3 tools/build_demo.py --output examples/mosslight/build/demo
npm run test:browser| Route | Evidence level | Tested scope |
|---|---|---|
| AssaultCube 1.3.0.2 C++ → Wasm/WebGL | Tested offline slice | Chromium 141.0.7390.37 / Firefox 142.0.1; one map, three bots, movement/aim/fire, audio activation, focus and settings reload; stock media selected locally |
| C++/SDL2 → optimized/gzip Wasm | Evaluated Mosslight adventure | Chromium/Firefox versions and measured sizes in report; collision, three collectibles, hazards, completion, audio activation, focus, durable saves, corrupt-package rejection |
| SDL2/C → Emscripten 4.0.16 / SDL2 2.32.8 | Evaluated original example | Chromium 141.0.7390.37 / Firefox 142.0.1 on macOS 15.7.4; one scene, input, audio activation, focus, save/reload |
| Electron 44.8.0 → browser JavaScript | Evaluated original example | Same browser versions/OS; gameplay plus menu and persistence; desktop filesystem/IPC smoke |
| Godot 4.5.1 standard/GDScript → single-thread web export | Evaluated original example | Chromium 141.0.7390.37 / Firefox 142.0.1 on macOS 15.7.4; one scene, WebGL output, input, audio activation, save/reload |
| Macroquad 0.4.14 / Rust 1.85.1 → Wasm | Evaluated original example | Chromium 141.0.7390.37 / Firefox 142.0.1, macOS; actual input/render, sound activation, element focus and full-reload save |
| LÖVE 11.4 / love.js 11.4.1 compatibility → Wasm | Evaluated original example | Same browsers/OS; Lua gameplay, actual rendered pixels, OpenAL starts and awaited IDBFS reload persistence |
| Shipped Unity files without a project | Blocked synthetic assessment | Missing editable project; filename clues remain inferred |
| Godot descriptor with missing native dependency | Blocked synthetic assessment | Missing source/web extension build; config format 5 is not an engine version |
| Other engine exporters, emulation, open engines and reconstruction | Investigation only | No completed port bundled for these routes; verify the exact input/runtime |
The example checks are implementation regressions. The optional paired agent evaluation harness separately measures explicit skill invocation against the same tasks without the skill; see its recorded pilot. Manual listening, mobile/Safari, long sessions, and performance profiling are untested. Future CI runs attach their own browser versions and evidence. See the evaluation checklists and contribution guide.
- Understand the game. Identify the engine and version, distinguish source from shipped data, and trace rendering, audio, controls, saves and OS calls.
- Choose a route. Compare engine exports, Emscripten/WebAssembly, browser runtimes, emulation and scoped reconstruction against the files available.
- Prove a playable slice. Adapt the platform boundary, build one scene, and test its graphics, input, audio and save behavior before expanding the scope.
- Leave a usable handoff. Record the changes, exact build/run commands, browser results, performance measurements, and anything still blocked.
The workflow keeps the native build working where source is available and separates confirmed findings from guesses. A successful compile is recorded as a build; playability requires browser interaction and evidence.
| You have | What the agent investigates |
|---|---|
| An editable Unity, Godot, or other engine project | The matching web exporter, renderer settings, plugins and platform restrictions |
| C/C++ source with SDL or a portable graphics layer | An Emscripten/Wasm build and browser adaptations for the main loop, graphics, audio and files |
| A JavaScript game inside Electron or NW.js | Browser code that can stay, and Node, IPC or native services that need replacements |
| Ren'Py, LÖVE, RPG Maker or GameMaker material | The exact runtime/version, project completeness, and available web exporter or compatible runtime |
| A legacy executable, ROM or disk image | A compatible browser emulator, performance, controls, persistence and data rights |
| Game data supported by an open engine | A web-capable engine build with the original data kept under its own license |
| A proprietary binary with no source | Existing authorized ports/runtimes, bounded reverse engineering, and a feasibility decision |
These are investigation routes, not a compatibility list. Engine versions, native extensions, unavailable services and asset formats can change the answer. The approach reference explains what to check.
Start with an assessment:
Use port2browser to inspect ./game-files without executing them. I have no
source code. Compare compatible browser emulation and open-engine options.
Keep the original assets local and explain what would block a usable port.
An old DOS game may have a practical emulation route. A shipped Unity build does not supply an editable Unity project. A modern native binary may require substantial reverse engineering and still have no workable browser route. The skill helps the agent make that distinction early.
Run helpers from any working directory using the installed skill's full path.
Quote paths containing spaces. Use python3 or py -3 if that is your Python
launcher; the selected interpreter must be Python 3.10 or newer.
# Read-only inspection; JSON goes to stdout. Write the report outside game-files.
python /path/to/port2browser/scripts/inspect_game.py ./game-files > inspection.json
python /path/to/port2browser/scripts/inspect_game.py ./game-files --max-entries 5000
# Serve only the dedicated build output, never the whole game/repo directory.
python /path/to/port2browser/scripts/serve.py ./build-web --port 8000
# Add --isolate if the chosen runtime requires SharedArrayBuffer.The inspector samples filenames, binary headers, and small dependency manifests.
It leaves archives unopened and never runs the target. Its JSON separates
inferred engine candidates from file counts, binary formats, warnings, and scan
limits. Read truncated and limitations before drawing conclusions; it is not
a decompiler, full dependency resolver, license checker, or sandbox. Keep the
input tree unchanged during inspection. Output may include private paths and
filenames, so review it before sharing.
The optional size reporter streams raw/gzip file accounting and labels PNG/WAV decoded-memory estimates separately from measurements:
python /path/to/port2browser/scripts/size_report.py ./build-web > sizes.json
python /path/to/port2browser/scripts/serve.py ./build-web --throttle 512The server supports single byte-range GETs for media seeking and a per-response KiB/s throttle. Multipart and conditional ranges fall back to the normal response; the throttle does not simulate latency or shared network bandwidth.
The server binds 127.0.0.1 and supports Wasm MIME types, already compressed
gzip/Brotli files, and optional COOP/COEP headers. It is a local test server;
test HTTPS and deployment configuration separately. Stop it with Ctrl+C.
The optional verification helper runs a URL plus a JSON input/state plan with Playwright. It retains screenshots, console/network errors, Web Audio evidence, element-focus checks, reload persistence and limited navigation/frame-callback measurements. It supports Chromium, Firefox, WebKit and compatible device profiles. Node/Playwright/pngjs remain optional; installed Python helpers still use only the standard library.
The Electron example has touch buttons using the same gameplay actions as the keyboard. Its new matrix checks WebKit desktop and Pixel/iPhone browser emulation, including touch, sound, menu and reload saves. Those checks do not establish physical-device or shipping-Safari support, nor mobile controls for the other games. See the scoped verification record.
Does this automatically turn any executable into a web game?
No. port2browser is a workflow for coding agents. Some projects have a direct
web export; others need substantial porting work, a compatible emulator, or
source that is not available. An arbitrary .exe cannot be passed to emcc
and turned into a browser build.
Does it support GTA V, Skate, or other large commercial games?
No commercial game ports or compatibility benchmarks are bundled here. Large games can depend on unavailable source, desktop middleware, huge assets, or rendering features that make a browser port impractical. Each game needs its own feasibility assessment. A video of a game in a browser may also be remote streaming, which is a different deliverable from running the game in the browser.
Can I publish a port of a game I own?
Owning a copy does not establish permission to redistribute its code or assets. Check the game, engine, middleware and asset terms separately. A local file import workflow can keep private assets off your hosting, but it does not settle every rights question. See the no-source and rights reference. This repository contains no games, ROMs, BIOS images, or bypass tools.
Do I need REA, an MCP server, or a paid tool?
The skill has no required MCP server or paid service. REA is an optional aid for authorized reverse engineering. The chosen game route may require an engine editor, export license, SDK, emulator, or other tools; the agent should identify those requirements before relying on them.
Start with SKILL.md. The agent loads the relevant reference as the work calls for it; there is no need to load every note for every game.
Useful contributions include a corrected engine clue, a reproducible build fix, or a documented porting case with game/engine versions and browser evidence. Keep proprietary files out of fixtures. Prefer focused references over another framework or installer.
Run the helper and packaging tests with the standard library:
python -m unittest discover -s tests -vGitHub Actions runs the same suite on Windows, Linux and macOS with Python 3.10 and 3.14. It checks the helper behavior, local documentation links, manifest fields, and a minimal copied install launched from another directory.
For changes to the workflow, also use the manual evaluation cases.
Automated helper tests cannot establish that an agent can port an arbitrary game.
Keep existing helper arguments and JSON fields compatible; add fields within
schema_version: 1, and bump that version for a breaking schema change. Commit
related changes together so regressions can be traced and reverted.
For additive inspection fields and partial-scan interpretation, see the JSON contract. For release versions and update instructions, see the changelog. Report vulnerabilities using the security policy. CI pins both Emscripten 4.0.16 and its emsdk checkout in one setup action.
MIT, for port2browser's own code and documentation. Game files and external tools retain their own terms.
Inspired by REA's practice of grounding reverse engineering findings in evidence. The task-folder and engine-playbook organization is also inspired by universal-modder. Both are optional references; no code, hooks, tool installs or services from either project are bundled.