fiverunner 0.0.0-stage → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DariusHQ
+
+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.

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="src/dev/public/logo.svg" alt="" width="96" height="96">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">FiveRunner</h1>
+
+<p align="center">Run FiveM resources in your browser and in CI.<br>No GTA V, no FXServer, no restarts.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/fiverunner"><img src="https://img.shields.io/npm/v/fiverunner" alt="Version on npm"></a>
+  <a href="https://github.com/DariusHQ/fiverunner/actions/workflows/ci.yml"><img src="https://github.com/DariusHQ/fiverunner/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/DariusHQ/fiverunner/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/fiverunner" alt="License"></a>
+</p>
+
+> Where a resource behaves differently than in FiveM, [tell us](https://github.com/DariusHQ/fiverunner/issues/new/choose).
+
+![The appearance editor of illenium-appearance on the screen of a player, over a cartoon meadow where her little character wears what the editor picks](docs/media/appearance.png)
+
+**[Watch the demo](https://github.com/DariusHQ/fiverunner/releases/download/v0.9.0/fiverunner.mp4)** (122 seconds, with sound): the whole Stable recipe of Qbox for txAdmin, tested, then in the dev UI, where a player registers a character, dresses her in illenium-appearance, opens ox_inventory and the bank of Renewed-Banking, and is dragged across the map to a garage, where she takes her car out.
+
+**[Try it in your browser](https://dariushq.github.io/fiverunner/)**: a small city, in Lua and JavaScript, that runs in the page, with nothing to install. Edit its files, press Run, and walk around it.
+
+```bash
+npx fiverunner test
+npx fiverunner dev
+```
+
+Run them with Node 22 or later, in the folder of a resource or of a server, the one with `server.cfg` and `resources`. A script that needs a framework runs in the folder of its server, next to the framework.
+
+- **Real resources, as they are released.** The 43 resources of the Stable recipe of Qbox start on your machine in seconds: its core, its inventory, its garages, its bank, and its phone, which is JavaScript.
+- **Real NUIs.** Your pages run in a browser, and talk to your callbacks as they do in FiveM: the appearance editor, the inventory, the bank and the phone of the recipe work as players use them.
+- **Tests in CI.** Each test gets a server of its own, players, and a database in memory, and time moves as fast as it can.
+- **A world to look at.** Under the frames of NUI, the screen of each player shows the world round their ped, as a cartoon or in the style of GTA V, and the cartoon dresses them as your scripts do.
+
+## Testing resources
+
+Start with a test that your resource or server starts without script errors, and a GitHub workflow that runs it on each push:
+
+```bash
+npx fiverunner init
+```
+
+Write tests in files whose names end in `.test.lua`, next to your resource:
+
+```lua
+describe('bank', function()
+    it('takes deposits', function()
+        local ann = fiverunner.connect({ name = 'Ann' })
+        ann:emit('bank:deposit', 100)
+        expect(exports.bank:balance(ann.id)).toBe(600)
+    end)
+end)
+```
+
+Then run them, on your machine or in GitHub Actions:
+
+```bash
+npx fiverunner test
+```
+
+![The tests of QBox, passing in a terminal](docs/media/tests.png)
+
+Each test gets a server of its own, with your resources started, and players whose clients run your client scripts. Resources that use oxmysql get a database of their own, in memory, that speaks MariaDB's SQL and starts with the tables of your `.sql` files. Time moves as fast as it can, so tests that wait take no time. `--coverage` writes the lines of Lua that they ran, for lcov, and `--junit` a report for your CI. [docs/testing.md](docs/testing.md) tells all that tests can do, and [examples/bank](examples/bank) is a resource with tests.
+
+## Developing resources
+
+Run your project in your browser:
+
+```bash
+npx fiverunner dev
+```
+
+The dev UI has the console of your server, where you run commands, its resources, which you start, stop and restart, the events that the server and the players send each other, which you trigger too, its state bags, an inspector of what each resource has and of the time it takes, with a box that runs code inside it, and a map of its entities and of the blips of the players, classic, as a cartoon or in the style of GTA V, where you drag players to move them. Connect players, whose clients run your client scripts, each with a screen that shows the frames of its NUI over the world round their ped: click through your pages, which talk to your callbacks as they do in FiveM, and walk or drive with W, A, S and D. As you save files, the dev UI restarts the resources that they belong to, and the players stay. [docs/dev.md](docs/dev.md) tells all that it does, and [examples/city](examples/city) is a small server to play it on: citizens move in through a card, buy food, take a car out, and write to each other on a phone in JavaScript.
+
+![The Stable recipe of Qbox in the dev UI: the console of its server, the events that its player sent, its resources and state bags, and the map of its world](docs/media/dev-ui.png)
+
+![The inspector of the dev UI: the resources of the server, with the time that each takes, the exports, events and commands of Renewed-Banking, and the convars of the server](docs/media/inspector.png)
+
+![The map of the dev UI in the style of the pause menu of GTA V: the blips that the resources of Qbox put on the map of a player, with its header, a legend and its buttons](docs/media/map-gta.png)
+
+![The map of the dev UI as a cartoon: the blips of Qbox as the tokens of a board game, on a meadow with trees](docs/media/map-cartoon.png)
+
+## Frameworks
+
+QBCore, QBox and ESX run on FiveRunner: CI runs them, as they are released, on every change, with players who log in, earn money, carry items, get jobs and are saved as they leave. [docs/compatibility.md](docs/compatibility.md) lists what passes.
+
+The whole recipe of QBCore for txAdmin runs too, with its 72 resources, without errors. A player creates a character in qb-multicharacter, picks where to start in qb-spawn, gets dressed in qb-clothing, opens qb-inventory and qb-banking, and takes a car out of qb-garages, with what the database keeps of it, as [its tests](compat/qbcore/tests/qbcore.test.lua) check.
+
+![The first clothes of a character in qb-clothing, with the HUD of qb-hud, on the screen of a player, over a cartoon meadow by the apartment that she picked](docs/media/qbcore.png)
+
+So does the whole Stable recipe of Qbox for txAdmin, with its 43 resources, without errors. A player takes a car out of a garage of qbx_garages, picks clothes in illenium-appearance, opens ox_inventory and the bank of Renewed-Banking, and keeps a contact in the phone of npwd, whose server is JavaScript that talks to the database with its own mysql2, as [its tests](compat/qbox-stable/tests/recipe.test.lua) check, which CI runs on every change.
+
+![The character registration of QBox, from the NUI of ox_lib, on the screen of a player in the dev UI](docs/media/qbox-registration.png)
+
+![The Motel Parking of qbx_garages, from the NUI of ox_lib, with the car of the player and E - Open Garage, on the screen of a player in the dev UI](docs/media/garage.png)
+
+![The inventory of ox_inventory on the screen of a player, with the pictures of her money and her phone](docs/media/inventory.png)
+
+![The bank of Renewed-Banking on the screen of a player, with her personal account and her balance](docs/media/bank.png)
+
+![The phone of npwd, with its apps, on the screen of a player, over a cartoon meadow where her little character stands](docs/media/phone.png)
+
+## How it works
+
+Your scripts run on CfxLua, the Lua 5.4 runtime FiveM ships, compiled to WebAssembly: the same syntax extensions, vectors and quaternions, `json` and `msgpack`. Each resource gets its own Lua state, one per side and per player, the same isolation FiveM gives you. On top of that, FiveRunner reimplements the Cfx scripting runtime: events with `source` and net-safety, exports, function references, state bags, threads and `Wait`, and the natives API.
+
+JavaScript runs on QuickJS, compiled to WebAssembly too, in a context for each resource on each side, with the globals of FiveM's runtime: `on`, `emit`, `exports`, `setTick` and the natives by their names. Servers also give it what bundles ask of Node, such as `require`, `Buffer` and `fs`, and the drivers of MySQL that resources carry reach FiveRunner's database on its port.
+
+Servers also get FiveM's own `io` and `os` libraries, its VFS and file permissions, its HTTP client and server, its server variables and its console, and oxmysql, whose exports run on SQLite, which FiveRunner teaches MariaDB's SQL.
+
+## Differences from FiveM
+
+FiveRunner follows FiveM's Windows server and its clients down to their error messages and their quirks. Where it differs, on purpose or for now, [docs/differences.md](docs/differences.md) says so.
+
+## Clean room
+
+FiveRunner's scripting runtime is a clean-room implementation and contains no code from the FiveM platform. CfxLua, QuickJS and their libraries are open source; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). FiveRunner is not affiliated with or endorsed by Cfx.re, Rockstar Games or Take-Two Interactive.
+
+## Contributing
+
+Resources that behave differently than in FiveM help most. [CONTRIBUTING.md](CONTRIBUTING.md) tells how to report them, how to run FiveRunner from its source, and the rules of its clean room. [CHANGELOG.md](CHANGELOG.md) tells what each version brought.
+
+## License
+
+[MIT](LICENSE)