ARCLUX MMO — Quickstart (from Zero)

Clone → install → self-host → create vessel → play. No URL every login.

Requirements

Node.js >= 20
pnpm (not npm) — npm i -g pnpm
Git

1. Clone ARCLUX

git clone https://github.com/GSF-001/ARCLUX.git
cd ARCLUX
pnpm install
node scripts/build-cli.mjs
node scripts/build-game.mjs

This builds apps/cli (arclux command) and apps/game (dist/renderer).

2. Create Your Vessel (your repo = your ship)

Your vessel lives in your own repository, not inside ARCLUX.

mkdir ~/my-vessel && cd ~/my-vessel && git init
# Generate ARCLUX boilerplate in YOUR repo (Layer A/D)
../ARCLUX/apps/cli/dist/arclux.mjs connect . --name my-vessel --license open --owner your-handle
# Creates:
#   .arclux/arclux.json
#   .arclux/systems/engine.arclux.json
#   .arclux/systems/defense.arclux.json
#   .arclux/components/README.md
#   .arclux/state/README.md
# Edit .arclux/systems/*.arclux.json to tune baseStat / capability
git add . && git commit -m "init vessel"
gh repo create your-handle/my-vessel --public --push
# or git remote add origin <url> && git push -u origin main

1 repo → 1 vessel (D-007). Manifest is validated by packages/universe/schema.ts + license.ts (3-tier: open/shared/private) before buildVesselModel (packages/universe/stats.ts:183).
The .arclux/ directory stays in your repo — it is your vessel definition (source of truth). Live health/damage is generated by ARCLUX and stored under .arclux/state/ (versioned).

3. Self-Host a Region (you are the server)

No central server — each community self-hosts one region (D-009).

# Inside ARCLUX repo
./apps/cli/dist/arclux.mjs serve --region my-region --client ./apps/game/dist/renderer --vessel ~/my-vessel
# --region  unique shard id (region-1 is default)
# --client  path to bundled game client (served at /)
# --vessel  path to your vessel repo to auto-spawn on boot (analyzed via .arclux/)
# --port    optional, default 24001 (or $ARCLUX_GAME_PORT)
# --no-register  private shard (not listed in directory)

# Output:
# 🌌 Region "my-region" live at http://127.0.0.1:24001
#    API  : .../snapshot · /health · /intent · /deliver
#    Game : http://127.0.0.1:24001/  (static client)

World boots with packages/gameserver/server.ts:103 createGameServer() → WorldRegion + Environs + SimulationEngine 10 tick/s + HTTP /snapshot /intent /deliver + static client.
The vessel is auto-spawned via server.ts:216 spawnPlayerVessel({playerId, vessel}) — no manual POST /deliver needed.
Register is public by default (packages/directory registerServer) so others can listServers and join.

To play on someone else’s shard, skip serve and just open their URL.

4. Launch the Game (MMO Landing, not a web dashboard)

Open http://127.0.0.1:24001/ in a browser or pnpm --filter @arclux/game dev (Electron). Landing (apps/game/src/renderer/landing.ts) shows:

Top navbar — HOME / UNIVERSE / FEATURES / FACTIONS / MEDIA / ROADMAP / DOCS + LAUNCH GAME
Hero — live background from scene3d.ts (nebula, suns, Ark, vessels that are actually online) — not a static image
Live stats bar — PLAYERS ONLINE / REGIONS ONLINE / FACTIONS / SHIPS DESTROYED (polled from RegionSnapshot every 4s via net.fetchSnapshot())
Live universe — 3 feature cards + News panel (wreckage, treaties, storms) — all clickable
Footer — engine info

Click PLAY NOW or LAUNCH GAME — the overlay hides and you are in the cockpit. No URL to paste every login. First launch asks for playerId (e.g., your-handle). It is saved to localStorage (arclux:playerId). Next time you open the game the same vessel auto-loads from persistence.ts — no URL field. The server validates validator.ts:53 entity.owner === playerId and license.ts 3-tier. Damage is authoritative (combat.ts:39 DAMAGE_CEILING=12 per subsystem, collision.ts:92 kinetic, thermics.ts:28 radiation).

6. Play

Move: WASD + QE vertical, Sprint, Space brake, mouse look (pointer-lock) — input.ts
Dock: approach a docking port (<800m) → F → 3s cinematic bay door + light sweep → hangar with 32 InstancedMesh slots
Bazaar: walk promenade → 16 stalls (interior.ts) → trade ComponentBinding (component.ts:10) — only live health>0 components can be sold
Build a stadium: create a repo with arclux.stadium.json (ringCount, habitatDensity) → world.ts:115 spawnStation() → new StationEntity stadium appears

7. Public Server List

Landing Live Universe fetches packages/directory listServers({status:"ONLINE"}) — e.g., community shards (Nvidia, etc.) show with endpoint links. Click → handoff via gate.ts:86 notifyTarget + bridge.ts transactional ACK (crash-safe).

8. Troubleshooting

No vessel after serve --vessel? Check arclux connect created .arclux/arclux.json and node -e "require('./apps/cli/dist/arclux.mjs')" has no error; serve logs Vessel spawned: ... or Vessel spawn failed.
Port in use? ARCLUX_GAME_PORT=27000 pnpm arclux serve ...
Client not loading? Ensure --client ./apps/game/dist/renderer points to index.html built by build-game.mjs.
playerId reset? Clear localStorage key arclux:playerId or re-enter in login modal.

Getting Started

Reference

MMO & Blueprint

Progress Detail

Codebase Map

Release

MMO Quickstart

ARCLUX MMO — Quickstart (from Zero)

Requirements

1. Clone ARCLUX

2. Create Your Vessel (your repo = your ship)

3. Self-Host a Region (you are the server)

4. Launch the Game (MMO Landing, not a web dashboard)

6. Play

7. Public Server List

8. Troubleshooting

Links

​ARCLUX MMO — Quickstart (from Zero)

​Requirements

​1. Clone ARCLUX

​2. Create Your Vessel (your repo = your ship)

​3. Self-Host a Region (you are the server)

​4. Launch the Game (MMO Landing, not a web dashboard)

​5. Login (once)

​6. Play

​7. Public Server List

​8. Troubleshooting

​Links

ARCLUX MMO — Quickstart (from Zero)

Requirements

1. Clone ARCLUX

2. Create Your Vessel (your repo = your ship)

3. Self-Host a Region (you are the server)

4. Launch the Game (MMO Landing, not a web dashboard)

5. Login (once)

6. Play

7. Public Server List

8. Troubleshooting

Links