@mavonengine/cli 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +106 -2
  2. package/dist/index.js +1830 -0
  3. package/package.json +45 -4
package/README.md CHANGED
@@ -1,3 +1,107 @@
1
- # Temporary Holding Version
1
+ # @mavonengine/cli
2
2
 
3
- 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.
3
+ Command line tools for [MavonEngine](https://mavonengine.com).
4
+
5
+ Requires Node 24 or newer.
6
+
7
+ ```sh
8
+ npm install -D @mavonengine/cli
9
+ npx mavonengine --help
10
+ ```
11
+
12
+ ## `mavonengine create`
13
+
14
+ Creates a new project from the multiplayer template, installs its dependencies and starts it like [`mavonengine dev`](#mavonengine-dev). It replaces `@mavonengine/create-bootstrap`, which now forwards to it.
15
+
16
+ ```sh
17
+ npx @mavonengine/cli create my-game
18
+ ```
19
+
20
+ Asks for a name if none is given. While the template downloads and `npm install` runs, the startup screen shows each step and its output. Then the dev script starts, the dashboard takes over as soon as the game server answers, and the game opens in the browser. Quitting during setup stops it and leaves what was created so far in the project directory. Without an interactive terminal, or with `--no-dashboard`, the progress and the dev script's output go straight to the terminal.
21
+
22
+ | Option | Default | |
23
+ | --- | --- | --- |
24
+ | `--cwd <dir>` | current directory | Where to create the project directory |
25
+ | `--no-dashboard` | | Print the progress instead of showing the dashboard |
26
+ | `--port <port>` | `8050` | Game server HTTP port for the dashboard |
27
+ | `--theme <name>` | `dark` | Dashboard theme |
28
+ | `--transparent` | | Let a transparent terminal background show through |
29
+ | `--no-open` | | Don't open the game in the browser once the server is up |
30
+
31
+ ## `mavonengine dev`
32
+
33
+ Runs the `dev` script of the MavonEngine project you are in and shows the [dashboard](#mavonengine-dashboard) for it. For the multiplayer template that starts the game server and the client together.
34
+
35
+ While the game server starts, a startup screen shows the latest output of the dev script; the dashboard takes over as soon as the server answers. Once the server is up, the game it serves opens in your default browser (not over SSH, and only if the server answers `/` with a page); `--no-open` turns that off, and `o` opens it again any time. Quitting the dashboard (`q` or Ctrl-C) stops the dev script and everything it started. If the dev script exits on its own, the dashboard closes and its output is printed.
36
+
37
+ ```sh
38
+ npx mavonengine dev
39
+
40
+ # From somewhere else
41
+ npx mavonengine dev --cwd path/to/my-game
42
+ ```
43
+
44
+ The project root is the nearest `package.json`, from the current directory upwards, that depends on `@mavonengine/core` and has a `dev` script, so it also works from inside `client/` or `server/`. The package manager comes from the lockfile (`npm`, `pnpm`, `yarn` or `bun`, default `npm`). Without an interactive terminal, or with `--no-dashboard`, the dev script's output goes straight to the terminal instead. Ctrl-C stops everything, and the command exits with the dev script's exit code.
45
+
46
+ | Option | Default | |
47
+ | --- | --- | --- |
48
+ | `--cwd <dir>` | current directory | Where to start looking for the project |
49
+ | `--no-dashboard` | | Only run the dev script |
50
+ | `--port <port>` | `8050` | Game server HTTP port for the dashboard |
51
+ | `--theme <name>` | `dark` | Dashboard theme |
52
+ | `--transparent` | | Let a transparent terminal background show through |
53
+ | `--no-open` | | Don't open the game in the browser once the server is up |
54
+
55
+ ## `mavonengine dashboard`
56
+
57
+ A live terminal dashboard for a running game server, built with [hqtui](https://github.com/profullstack/hqtui).
58
+
59
+ It shows CPU, network bandwidth, tick timings against the tick budget, world/physics/memory stats, the connected players, the server's recent log output and the HTTP requests it received. It reads them from the server's `GET /api/game/metrics`, `GET /api/game/logs` and `GET /api/game/requests` endpoints, which need a `@mavonengine/core` release that includes them.
60
+
61
+ ```sh
62
+ # Local server on the default HTTP port (8050)
63
+ npx mavonengine dashboard
64
+
65
+ # Remote server with a metrics token
66
+ MAVONENGINE_METRICS_TOKEN=secret npx mavonengine dashboard --host game.example.com --port 8050
67
+
68
+ # No server needed: simulated data
69
+ npx mavonengine dashboard --sim
70
+ ```
71
+
72
+ | Option | Default | |
73
+ | --- | --- | --- |
74
+ | `--host <host>` | `localhost` | Server host |
75
+ | `--port <port>` | `8050` | Server HTTP port (`ServerOptions.httpPort`) |
76
+ | `--url <url>` | | Full metrics URL, overrides `--host` and `--port` |
77
+ | `--token <token>` | `$MAVONENGINE_METRICS_TOKEN` | Metrics token (`ServerOptions.metrics.token`) |
78
+ | `--interval <ms>` | `1000` | Poll interval |
79
+ | `--theme <name>` | `dark` | `dark`, `dracula`, `nord`, `tokyoNight`, `gruvbox`, `matrix`, `monochrome`, `highContrast`, `light` |
80
+ | `--transparent` | | Let a transparent terminal background show through. Text can be hard to read over a light wallpaper |
81
+ | `--sim` | | Simulated data instead of a server |
82
+
83
+ Keys: `q` quits, `r` refreshes now, `o` opens the game the server serves in the browser, `1`–`4` switch between the Overview, Players, Logs and HTTP tabs. The mouse wheel scrolls the players table, the logs and the requests; scroll the logs back to the bottom, or the requests back to the top, to follow new ones again.
84
+
85
+ The HTTP tab lists every request the game server's HTTP server received, newest first: the client (static files or Vite in dev), your own `onHttp` routes, the geckos.io signaling requests and WebSocket upgrades such as Vite's HMR socket, each with status, duration, size and client address. Query strings are left out since they can hold tokens, and the dashboard's own polling is not recorded. The game traffic itself is WebRTC, not HTTP, so it shows on the Players tab instead; with a separate `socketPort` the signaling requests go to that port and don't show up either.
86
+
87
+ ### Server access
88
+
89
+ The metrics endpoint is configured on the game server:
90
+
91
+ ```ts
92
+ const server = new MyServer(logger, physicsWorld, {
93
+ httpPort: 8050,
94
+ metrics: {
95
+ token: process.env.METRICS_TOKEN,
96
+ // Recent log entries kept for the dashboard, 0 turns the logs endpoint off
97
+ logBufferSize: 500,
98
+ // Recent HTTP requests kept for the dashboard, 0 turns the requests endpoint off
99
+ requestLogSize: 500,
100
+ },
101
+ })
102
+ ```
103
+
104
+ - With no token, the endpoint only answers requests from localhost.
105
+ - With `NODE_ENV=production` and no token, the endpoint is turned off.
106
+ - Set `metrics.enabled: false` to turn it off everywhere.
107
+ - The logs endpoint follows the same rules. It serves whatever passes your logger's level.