> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/docs/sample-projects/web-games/fal-ai-relic-rumble.md).

# fal.ai Relic Rumble

Make a fal.ai game multiplayer with edgegap: a three.js game written by a coding agent with fal-generated 3d characters, props and sounds, matchmaking and one authoritative node.js server per match.

Learn how to make a game built with [fal.ai](https://fal.ai/) assets online multiplayer on Edgegap.

![Relic Rumble: four fal-generated characters in a match](https://raw.githubusercontent.com/edgegap/netcode-sample-fal-relic-rumble/main/docs/images/gameplay.jpg)

Relic Rumble is a [three.js](https://threejs.org/) party game for 4 players: grab a relic, carry it to your corner, and shove anyone who tries the same. A coding agent wrote the code, and fal.ai generated everything you see and hear: four rigged characters with walk and run animations, the props, the floor and the sounds.

* **fal.ai**: used while you build the game, to generate its assets.
* **Edgegap**: used while people play, for matchmaking and one dedicated server per match, near its players.

This sample shows:

* **Rules in one file**: `client/rules.js` has no browser code, so the page runs it for solo play and the game server runs the same file for online play.
* **Assets that stay in the page**: the server treats characters as circles and pillars as boxes. No model, texture or sound is copied into the server image, and new art needs no server release.
* **Every asset optional**: with an empty `client/assets.js` the game draws plain shapes. The sample was built and tested online this way before any asset was generated.
* **The fal pipeline**: one concept image per character, then image-to-3D with rigging. Every prompt, model and price is in the sample's `PROMPTS.md`.
* **Find match from the page** with the [Edgegap JavaScript SDK](https://www.npmjs.com/package/@edgegap/sdk): 2 to 4 players per match, and bots fill the empty seats.

{% hint style="info" %}
See the [sample repository](https://github.com/edgegap/netcode-sample-fal-relic-rumble) for the game, the fal scripts and prompts, the game server, and an end-to-end test of the whole flow.
{% endhint %}

## ✔️ Preparation

Before we start, you will need:

* [fal.ai Relic Rumble sample](https://github.com/edgegap/netcode-sample-fal-relic-rumble), pushed to your own GitHub repository.
* [Node.js](https://nodejs.org/) 22 or newer, to run the server and page locally.
* To generate your own assets: a [fal.ai account](https://fal.ai/dashboard) with a few dollars of credit, and fal's `genmedia` CLI or the [fal MCP server](https://fal.ai/mcp) connected to your coding agent. The sample's assets are included, so this is optional.

☑️ Try the game locally first:

{% code collapsedlinecount="10" %}

```bash
npm install
npm run test:local
npm run client
```

{% endcode %}

`npm run test:local` plays a full match with two headless players on a local server. Open `http://localhost:8080` and click **Play vs bots** to play solo.

☑️ To play online on your own machine, run `npm run server` in a second terminal, then click **Local server :7777** in two browser tabs.

## 🎨 Generate Assets with fal.ai

### 1. Characters, Props and Sounds

☑️ Generate one concept image per character. Ask for a full body in an A-pose with arms away from the body and empty hands, so the character can be rigged automatically:

{% code collapsedlinecount="10" %}

```bash
bash art/gen-concepts.sh
```

{% endcode %}

☑️ Turn each image into a rigged 3D model. The result includes the model and separate walk and run animations:

{% code collapsedlinecount="10" %}

```bash
genmedia run meshy/v7.1/image-to-3d --image_url "<concept url>" --enable_rigging true --pose_mode "a-pose" --target_polycount 12000 --async --json
genmedia status meshy/v7.1/image-to-3d <request_id> --result --json
```

{% endcode %}

☑️ Download each model, shrink its texture for the web, and list it in `client/assets.js`:

{% code collapsedlinecount="10" %}

```bash
python art/fetch.py raider-blue
bash art/build.sh raider-blue
```

{% endcode %}

Props, the floor texture and the sounds follow the same steps with `art/gen-props.sh` and `art/gen-sfx.sh`.

{% hint style="success" %}
**Your assets never reach the game server.** Collisions, reach and speed are numbers in `client/rules.js`. The renderer scales each model to a size in world units, so you can replace any model without changing a rule.
{% endhint %}

{% hint style="warning" %}
**A rigged model reports the wrong size** to three.js's default bounding box, because its skeleton carries its own scale. Measure the skinned vertices instead, as `fit()` does in `client/render.js`, or the character renders far too small.
{% endhint %}

✅ You may now proceed to the next step.

## ⚡ Deploy and Connect

### 2. Build the Server Image

☑️ To get started, you'll need to [create a free account with Edgegap](https://app.edgegap.com/auth/register). No credit card required.

☑️ Find your [Container Registry](https://docs.edgegap.com/learn/advanced-features/edgegap-container-registry.md) project name and credentials.

☑️ In your GitHub repository, open **Settings**, then **Secrets and variables**, then **Actions**, and add:

* variable `EDGEGAP_REGISTRY_PROJECT` - your registry project name,
* secret `EDGEGAP_REGISTRY_USERNAME` - your registry username,
* secret `EDGEGAP_REGISTRY_TOKEN` - your registry token.

☑️ Run the **Server image** workflow from the **Actions** tab. It plays the local match test, then builds and pushes `registry.edgegap.com/<project>/relic-rumble:<tag>`, tagged with the build time. The tag is shown in the run's summary.

✅ You may now proceed to the next step.

### 3. Create the App Version

☑️ [Create an application](https://app.edgegap.com/application-management/applications/list) named `relic-rumble`, with one version named after your tag:

* **Image**: registry `registry.edgegap.com`, repository `<project>/relic-rumble`, tag `<tag>`,
* **Resources**: 0.25 vCPU and 512 MB memory,
* **Port**: `7777`, name `gameport`, protocol **WS**, with **TLS Upgrade** enabled,
* **Restart policy**: Never,
* **Environment variables**:
  * `EMPTY_TIMEOUT_S` - `15`, to stop a server everyone left,
  * `FIRST_JOIN_TIMEOUT_S` - `60`, to stop a server nobody joined,
  * `RESULTS_SECONDS` - `8`,
  * `IDLE_TIMEOUT_S` - `75`, to drop players whose page is gone,
* **Max duration**: 30 minutes, as a safety net: the server stops itself.

{% hint style="warning" %}
**TLS Upgrade** lets browsers on `https` pages connect to `wss://<id>.pr.edgegap.net:<port>`. Edgegap terminates TLS and forwards plain WebSocket traffic to port `7777`.
{% endhint %}

✅ You may now proceed to the next step.

### 4. Create the Matchmaker

☑️ Set `application.version` in the sample's `matchmaker/rumble.json` to your version, and add the address of your page to `allowed_cors_origins`.

☑️ Open the [Matchmaker](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) page in the dashboard, click **Create**, upload the config, and click **Create and Start**.

The `rumble` profile matches 2 to 4 players. After 20 seconds, a player waiting alone gets a server, and bots fill the empty seats.

☑️ When the matchmaker shows **Online**, copy its **API URL** and **Auth Token** into `client/config.local.js`, a copy of `client/config.js`.

{% hint style="success" %}
The **matchmaker Auth Token is safe to ship in web pages**: it can only ask for matches. Never put your Edgegap API token in a page or in the server image.
{% endhint %}

✅ You may now proceed to the next step.

### 5. Find a Match

☑️ Open your page in two browser tabs and click **Find match** in both within 20 seconds.

Each page:

1. joins the matchmaker and waits for `HOST_ASSIGNED`,
2. connects to `wss://<fqdn>:<port>` and sends its ticket ID,
3. plays: it sends inputs and draws the state the server sends back, with the same renderer and assets as solo play.

The game server:

1. waits for the matched players, then fills the empty seats with bots,
2. runs `client/rules.js` 60 times a second and sends positions 20 times a second,
3. stops its own deployment after the results screen.

🙌 Both players are now in the same match, on a server placed near them.

☑️ To test the whole path without a browser, run the end-to-end test. It queues two headless players, plays a match, and waits for the deployment to stop itself:

{% code collapsedlinecount="10" %}

```bash
MM_URL=<API URL> MM_TOKEN=<Auth Token> node tests/e2e.mjs rumble 2
```

{% endcode %}

## 📦 Ship Your Game

* Host the page anywhere: `client/` is static files with no build step. The sample includes a GitHub Pages workflow.
* Check the size of `client/assets/` before you publish. The sample's four characters, three props, floor and sounds total 7 MB.
* Keep your fal prompts, so you can generate one more asset in the same style later.
* Turn `inspect` off in the matchmaker config before launch.
* To ship new rules, push a new image tag and point the app version at it. New matches use it, and running ones keep the old build. New assets only need the page to be published again.

{% hint style="info" %}
Using a coding agent? The `edgegap-fal` skill in [Edgegap's agent skills](https://github.com/edgegap/llm-agent-skills) holds the game brief, the fal asset pipeline, the server templates and the tests, and walks your agent through the same steps for your own game.
{% endhint %}
