From bbb9caefd1ece6a6085dc567c47e8a69745dac8b Mon Sep 17 00:00:00 2001 From: mentallyunstable-lab <193638771+mentallyunstable-lab@users.noreply.github.com> Date: Wed, 11 Nov 2026 21:30:02 +0200 Subject: [PATCH] docs(loader): mark --dir as required and describe the watch throttle The READMEs gave -d, --dir a default of .nanoforge/client and .nanoforge/server, but both loaders have no default and throw "No game dir specified". The server README also said changes are debounced; the watcher acts on the first change and ignores the next 100 ms. Closes #143 Co-Authored-By: Claude Opus 5.5 --- README.md | 26 +++++++++++++------------- apps/client/README.md | 18 +++++++++--------- apps/server/README.md | 10 +++++----- 3 files changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index f338360..866c963 100644 --- a/README.md +++ b/README.md @@ -61,15 +61,15 @@ The client loader is a Bun HTTP server that bridges the browser and the compiled - Supports HTTPS/TLS via `--cert` and `--key` - Supports hot-reload via WebSocket watch mode (`--watch`) -| Option | Default | Description | -| -------------------------- | ------------------- | ---------------------------------------------- | -| `-p, --port ` | `3000` | Port the HTTP server listens on | -| `-d, --dir ` | `.nanoforge/client` | Directory of compiled client game files | -| `--watch` | `false` | Enable file watcher and browser hot-reload | -| `--watch-port ` | auto | Port for the WebSocket watch server | -| `--watch-server-dir ` | — | Also watch a server game directory for changes | -| `--cert ` | — | TLS certificate file (enables HTTPS) | -| `--key ` | — | TLS private key file (enables HTTPS) | +| Option | Default | Description | +| -------------------------- | -------- | ---------------------------------------------- | +| `-p, --port ` | `3000` | Port the HTTP server listens on | +| `-d, --dir ` | required | Directory of compiled client game files | +| `--watch` | `false` | Enable file watcher and browser hot-reload | +| `--watch-port ` | auto | Port for the WebSocket watch server | +| `--watch-server-dir ` | — | Also watch a server game directory for changes | +| `--cert ` | — | TLS certificate file (enables HTTPS) | +| `--key ` | — | TLS private key file (enables HTTPS) | ### `@nanoforge-dev/loader-server` @@ -80,10 +80,10 @@ The server loader is a Bun process that runs the server-side game code. It: - Passes all game files and `NANOFORGE_*` environment variables to the game - Restarts the worker on file changes when `--watch` is enabled -| Option | Default | Description | -| ----------------- | ------------------- | ------------------------------------------------ | -| `-d, --dir ` | `.nanoforge/server` | Directory of compiled server game files | -| `--watch` | `false` | Enable file watcher and worker restart on change | +| Option | Default | Description | +| ----------------- | -------- | ------------------------------------------------ | +| `-d, --dir ` | required | Directory of compiled server game files | +| `--watch` | `false` | Enable file watcher and worker restart on change | ### `@nanoforge-dev/loader-website` diff --git a/apps/client/README.md b/apps/client/README.md index 7bd901f..ee5871f 100644 --- a/apps/client/README.md +++ b/apps/client/README.md @@ -58,15 +58,15 @@ The client loader exposes the following HTTP routes: ## Options -| Option | Default | Description | -| -------------------------- | ------------------- | ---------------------------------------------- | -| `-p, --port ` | `3000` | Port the HTTP server listens on | -| `-d, --dir ` | `.nanoforge/client` | Directory of compiled client game files | -| `--watch` | `false` | Enable file watcher and browser hot-reload | -| `--watch-port ` | auto | Port for the WebSocket watch server | -| `--watch-server-dir ` | — | Also watch a server game directory for changes | -| `--cert ` | — | TLS certificate file (enables HTTPS) | -| `--key ` | — | TLS private key file (enables HTTPS) | +| Option | Default | Description | +| -------------------------- | -------- | ---------------------------------------------- | +| `-p, --port ` | `3000` | Port the HTTP server listens on | +| `-d, --dir ` | required | Directory of compiled client game files | +| `--watch` | `false` | Enable file watcher and browser hot-reload | +| `--watch-port ` | auto | Port for the WebSocket watch server | +| `--watch-server-dir ` | — | Also watch a server game directory for changes | +| `--cert ` | — | TLS certificate file (enables HTTPS) | +| `--key ` | — | TLS private key file (enables HTTPS) | ## Watch Mode diff --git a/apps/server/README.md b/apps/server/README.md index 57debb3..d29d9bc 100644 --- a/apps/server/README.md +++ b/apps/server/README.md @@ -53,14 +53,14 @@ The server loader runs in two processes: ## Options -| Option | Default | Description | -| ----------------- | ------------------- | ------------------------------------------------ | -| `-d, --dir ` | `.nanoforge/server` | Directory of compiled server game files | -| `--watch` | `false` | Enable file watcher and worker restart on change | +| Option | Default | Description | +| ----------------- | -------- | ------------------------------------------------ | +| `-d, --dir ` | required | Directory of compiled server game files | +| `--watch` | `false` | Enable file watcher and worker restart on change | ## 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 fresh state. Changes are debounced to 100 ms to avoid redundant restarts during bulk builds. +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 fresh state. The first change restarts the worker, and further changes in the next 100 ms are ignored, so a burst of changes within that window causes one restart. ## Environment Variables