Skip to main content

​
Overview

loader-server is a Bun process that runs the compiled server-side game code. It scans a built game directory, locates /main.js, then forks an isolated child process — the worker — that loads the game and calls its exported main() function. The parent process manages the worker lifecycle and restarts it when files change in watch mode.

​
Usage

Or invoke directly after building the loader packages:

​
How it works

The server loader runs as two processes:
  1. Server (server.js) — the entry point. Scans the game directory, finds /main.js, and forks the worker. In --watch mode it restarts the worker on any file change.
  2. Worker (worker.js) — an isolated child process forked by the server. It requires the game’s main.js via createRequire and calls main({ files, env }) to start the game.
This two-process split ensures that a game crash or process.exit() call in the game code does not terminate the loader itself.

​
Options

​
Watch mode

When --watch is enabled, the loader watches the game directory recursively. On any file change the running worker is killed and a new worker is immediately forked with a clean state. Changes are debounced to 100 ms to avoid redundant restarts during bulk builds.

​
Environment variables

The server loader collects all environment variables whose name starts with NANOFORGE_, strips the prefix, and passes the resulting object to the game via the env field of main():
The game receives these inside the worker:

​
Game interface

The worker calls the game’s main export with the following shape:

​
Examples

Start with a custom game directory:
Start in watch mode:
Pass environment variables to the game: