> ## Documentation Index
> Fetch the complete documentation index at: https://arclux-os.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MMO Quickstart

> Clone repo jadi kapal, self-host region, main dari nol

# 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

```bash theme={null}
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.

```bash theme={null}
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).

```bash theme={null}
# 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.

## 5. Login (once)

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.

## Links

* Blueprints: `docs/blueprint/01-spatial-ux.md` … `08-persistent-world.md`, `09-client-polish.md` (Fase 1-4 done, Fase 5-12 in progress)
* Implementation map: `docs/blueprint/progres/MMO-IMPLEMENTATION.md`
* License: `LICENSE-MMO` (game) + `LICENSE-ENGINE` (Apache 2.0 for engine)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.