# Lost Souls Launcher + District Kit — Build Plan for Codex (v2)

**Prepared:** 9 Oct 2026 · **For:** Codex (builder) · **Reviewed by:** Claude · **Approver:** Legend (@Marley)
**Repo:** `215GrandAve/lost-souls` · **Base branch:** `unreal-island-archipelago` (Quik's Unreal work)
**Supersedes:** v1 of this plan (same day). v2 adds the scaling layer: district manifests, a standard asset spec, an asset lifecycle, batch production and a second-district pilot.

---

## 0. Read this first

You are building two things:

1. **The Launcher**: a local desktop tool that runs the team's existing Unreal / Blender scripts from buttons, reports pass/fail with evidence, and keeps a history.
2. **The District Kit**: the standards and templates that let every new part of the island be built with the same pipeline instead of from scratch.

The goal in one line: **every district and every asset should make the next one faster.** Brickell is the first deployment of the kit, not a one-off.

Ground rules (non-negotiable):

1. **Nothing goes to `main` without Legend's explicit approval.** A push to `main` deploys `thelostsouls.world` live.
2. **Work on new branches** created from `unreal-island-archipelago` (start with `tools/launcher`). Open PRs into `unreal-island-archipelago` and wait for Quik's review. Never commit directly to it.
3. **Don't change the behavior of Quik's existing scripts.** Where generalization needs a script change, keep it small and opt-in, default to today's behavior, and put it in its own PR for Quik.
4. **Allowlist only.** The launcher runs registered jobs with validated parameters. It never runs arbitrary commands or text a user typed.
5. **Report honestly.** Same rule as the branch's `AGENTS.md`: no claim without evidence (log line, test count, screenshot). List what was not verified.
6. **The game script is NOT finalized.** Nothing here approves story or canon.
7. **Keep company material out.** Use only Lost Souls project material in the repo.

---

## 1. Background: what Lost Souls is

**Island of Lost Souls** is a dystopian sci-fi psychological thriller universe created by Legend (Asa Ferguson II, "Marley" in team handles). It spans a graphic novel (the main story, set in 2043), a 13-track soundtrack / visual album, a website (`thelostsouls.world`) and games.

Premise: Sophia escapes a surveillance-heavy Miami and arrives at a luxury island run by an AI system (Gemini / Immortal) and its human architect, Marley The Misfit. The island looks like paradise but hides enhancement experiments, memory manipulation and identity distortion. Core theme: the line between what's real and what's engineered.

**The game we are building toward:**
- **Unreal Game I, targeting PS5 / PlayStation Network.** A prequel spanning roughly 2030/2033 → 2043. The player "plays to build the island." GTA-style: switching between characters, a taste of futuristic Miami as the opener, most of the game on the island.
- The world is built **district by district** (Brickell Island = District 02 is first), with a shared world grid, then merged into a master world map. Miami is needed in a 2033 and a 2043 version. A shared Coconut Grove / CocoWalk sandbox is also planned with Quik's boxing game (Fight Club).
- The game script is a **draft** (Prequel v2, "The Cost of Paradise," is the current candidate).

**The team:**
- **Legend (@Marley)**: creator and creative director. Not a day-to-day Unreal operator. Rig: Ryzen 9 5950X, RTX 3090 Ti (24 GB), 32 GB RAM, Windows.
- **Quik (@Quik, GitHub `quikycode`)**: developer. Builds the Unreal game mostly by directing an AI coding agent (Claude Code) through command-line scripts.
- AI collaborators: Claude, ChatGPT/Codex, and OpenClaw (Legend's Telegram agent gateway).

---

## 2. Background: what already exists

### 2.1 The Unreal project (branch `unreal-island-archipelago`)

- Unreal Engine **5.8.3**, project `UEProject/Archipelago.uproject`, C++ module `LostSouls`.
- Main map `/Game/Maps/Brickell`: Brickell Island, 47 buildings, streets, marina, mall, court, bridges. Second cooked map: `/Game/Maps/Island`.
- **Systems built and tested** (see `docs/WEEK_LOG.md`, `docs/specs/utility_grid_and_jobs.md`):
  - Island-wide **utility grid** generated from road data (2 substations, 110 poles, 165 nodes, 47 powered buildings, 1,961 light lenses).
  - **Repair jobs**: broken pole → job → nearest idle NPC worker or a player claims and repairs it. Keyboard + gamepad. Slate HUD that works in shipping builds.
  - **Multiplayer**: in-editor listen-server tests, plus real two-process packaged tests (late join, join mid-job, disconnect).
  - **Packaged builds**: last run 96–98 fps at 1280×720 on Quik's machine.
- `AGENTS.md` on that branch still describes the original single-image mission and is out of date. Use `docs/WEEK_LOG.md` / `docs/PROGRESS.md` for current state.

### 2.2 How work gets done today

Almost every tool follows one pattern: **close the running editor → start a separate Unreal process → run a Python script → write a log → print filtered `ARCH …` lines.** Several scripts force-kill `UnrealEditor` first.

So the launcher must run **outside** Unreal and warn before any job that closes an open editor. An in-editor panel is the wrong design for these tools.

### 2.3 The asset pipeline today

1. Reference images (Midjourney / ChatGPT concept sheets). **32 reference PNGs** wait in `reference/districts/brickell_assets_refs/tripo_queue_T01_V04/` (trees T01–T08, plants S01–S09, street items U01–U11, vehicles V01–V04) with `ASSET_CATALOG.md` and `manifest.csv`.
2. **Tripo** image-to-3D: currently **manual**, one upload at a time on the website.
3. `tools/intake_glb.py` (Blender): cleanup, real height, base-centre pivot, texture unpack, FBX export, manifest update.
4. `tools/inspect_asset.py` (Blender): turnaround contact sheet + mesh health stats.
5. `scripts/brk_swap_*.py` (Unreal): swap stand-ins for new meshes.
6. `tools/brk_rebuild.ps1`: full Brickell re-import.

### 2.4 Why it doesn't scale yet (measured 9 Oct 2026)

- **88 of the scripts under `tools/` and `scripts/` reference Brickell** by map path, data file, asset folder or `BRK_` variable. Each new district would need copies or edits.
- Asset records live in `data/districts/brickell_assets.json` (34 entries). There is no status field: you can't tell an asset that's generated from one that's approved, in the map, and tested.
- There's no written standard for what a "game-ready asset" is. Intake fixes some things (pivot, normals), but nothing **checks** scale, triangle budget, materials or collision against a spec.
- Tests hard-code pilot-zone IDs (pole `F1c`, edges `E090`, `Worker1`). They're correct for Brickell but can't run on another district.
- Paths are hard-coded to Quik's machine (`C:\Program Files\Epic Games\UE_5.8`, `D:\Builds\`), so only one PC can run the pipeline.
- Each script reports results in its own format, so every new button needs a custom parser.

### 2.5 The website side (for Phase 5 only)

- `thelostsouls.world` runs on a Cloudflare Worker and is deployed by push to `main`.
- **Game Console V3** (`web/game-console/v3/`) is a planning workspace with Asset Needs and Tools & Trials but no execution link. Its README names "a local companion that runs an allowlisted existing job" as next. **The launcher is that companion.** A separate task adds shared saving to V3 (Cloudflare Access + D1).

---

## 3. Scaling principles (apply to every phase)

1. **Data, not code, describes a district.** Adding a district means adding a manifest and data, not copying scripts.
2. **One definition of "done."** An asset or district is done when it passes the standard checks, not when someone says so.
3. **Adapters, not rewrites.** Brickell's existing files stay where they are. Its district manifest points at them. Old scripts keep working.
4. **One result contract.** New and updated scripts emit one standard result line; old scripts get a legacy parser once.
5. **Every fix becomes a check.** When a bug is found, its test joins the district's standard test set, so it can't come back in the next district.
6. **Measure the speed-up.** Track how long each stage takes per asset and per district. If the second district isn't faster than Brickell, the kit isn't working.
7. **Any team machine can run it.** Machine-specific paths live in config, not in scripts.

---

## 4. Shared formats (define in Phase 1, use everywhere)

### 4.1 District manifest: `districts/<id>/district.json`

```json
{
  "id": "brickell",
  "name": "Brickell Island (District 02)",
  "era": "2043",
  "status": "active",
  "map": "/Game/Maps/Brickell",
  "content_root": "/Game/Brickell",
  "data": {
    "layout": "data/districts/brickell_layout_v02.json",
    "assets": "data/districts/brickell_assets.json",
    "grid": "data/districts/island_grid.json",
    "streets": "data/districts/brickell_streets.json"
  },
  "incoming_dir": "assets/incoming/brickell",
  "reference_queues": ["reference/districts/brickell_assets_refs/tripo_queue_T01_V04"],
  "camera_presets": {
    "street": [24000, 7500, 350, 2, -90],
    "aerial": [24000, 9000, 9000, -32, -90],
    "towers": [0, 9000, 11000, -22, -90]
  },
  "test_set": "districts/brickell/tests.json",
  "legacy": true
}
```

- Brickell's manifest **points at existing paths**. Move nothing. `"legacy": true` marks it as wrapping pre-kit scripts.
- New districts follow the default layout in §7.2.
- Every launcher job takes a `district` parameter and resolves paths from the manifest.

### 4.2 Standard asset spec: `standards/asset_spec.json`

A per-category rulebook. Codex drafts it from what intake already enforces plus the checks below. **Quik approves the numbers** (they're his performance budget).

| Check | Rule (draft values for Quik to confirm) |
|---|---|
| ID / naming | `^[A-Z]{1,3}\d{2}[a-z]?$`, unique within the district |
| Category | one of: building, tree, plant, street_prop, vehicle, interior_prop, landmark |
| Units / up axis | centimetres, Z-up |
| Pivot | base centre (within 1 cm) |
| Real-world size | height within the category's range (e.g. street_prop 0.3–8 m, tree 2–30 m) and within ±5% of the requested height |
| Triangle budget | per category, set by Quik (e.g. street_prop ≤ 20k, vehicle ≤ 150k; Nanite categories may be exempt) |
| Mesh health | no loose verts, no non-manifold edges above a threshold, normals outward, component count reported |
| UVs | UV0 present, no zero-area UV faces above a threshold |
| Materials | slot names from the district's material set; PBR textures present (basecolor, normal, roughness, metallic) |
| Textures | power-of-two, max 4096 (2048 for street props), correct colour space |
| Collision | required for categories the player can touch; type per category |
| Provenance | reference image path, generator (Tripo / manual / Fab), source file kept, rights note |

Validator: `tools/validate_asset.py` (Blender headless) → per-check PASS/FAIL plus the standard result line (§4.4). It runs automatically after intake.

### 4.3 Asset lifecycle

Each asset record gets a `status` and a `history` list:

`requested → reference → generated → cleaned → validated → approved → in_map → tested`

- `validated` = passes §4.2 automatically. `approved` = a human looked at the contact sheet and said yes. Those are deliberately separate steps.
- `in_map` and `tested` are set by the swap and test jobs.
- Implement as an added field in the existing manifest (`brickell_assets.json` gains `status` / `history` with a migration that defaults existing entries to `in_map`), or as a sidecar `districts/<id>/asset_status.json` if Quik prefers not to touch his manifest. **Ask Quik.**
- This lifecycle is what V3's "Asset Needs" will display in Phase 5.

### 4.4 Result contract

New or updated scripts print one final line:

```
LSRESULT {"job":"validate_asset","district":"brickell","status":"PASS","passed":11,"total":12,"summary":"...","images":["renders/inspect/U03_turn.png"],"metrics":{"tris":18452}}
```

- `status` is one of `PASS`, `FAIL`, `ERROR`.
- The launcher prefers `LSRESULT`. For legacy scripts it uses the per-job parsers (§5.3).
- Never report PASS just because the process exited with code 0.

### 4.5 Job registry: `launcher/jobs/*.json` (data, not code)

One file per job: id, label, group, one-line description, command template, parameters with validators, `districts` it supports (`["*"]` or `["brickell"]` for legacy-only), `closes_unreal`, resource class (`unreal`, `blender`, `python`), timeout, log path, parser (`lsresult` or a legacy parser name), output image globs.

Adding a button = adding a JSON file plus a test. No launcher code changes.

---

## 5. Phase 1: Launcher (district-aware from day one)

**Goal:** buttons for existing scripts, built on the shared formats so nothing has to be redone later.

### 5.1 Stack

- **Python 3 standard library** server (`http.server`, `subprocess`, `threading`). No new framework without a stated reason.
- One HTML page plus plain JS, styled with Lost Souls site tokens (fonts: Bodoni Moda, Instrument Sans, Martian Mono; dark ground, pink and teal accents from `web/lostsouls-world`).
- Binds to **`127.0.0.1` only**. Start with `python launcher/launcher.py`.

### 5.2 Layout

```
launcher/
  launcher.py  runner.py  parsers.py  registry.py
  jobs/*.json                 # §4.5
  ui/index.html app.js style.css
  launcher.config.example.json
  README.md                   # run it; add a job; add a district
  tests/                      # parsers, validation, registry (no Unreal needed)
districts/brickell/district.json  districts/brickell/tests.json
standards/asset_spec.json     # drafted in Phase 2, placeholder now
runs/                         # history (gitignored)
launcher.config.json          # machine settings (gitignored)
```

### 5.3 Jobs to register (existing scripts, unchanged)

Before coding each job, read the script's header to confirm arguments, environment variables, outputs and log tags.

**Assets**: Clean up Tripo model (`tools/intake_glb.py`), Preview asset (`tools/inspect_asset.py`), Swap buildings/towers/marina/streets/mall/terrain (`scripts/brk_swap_*.py`, closes Unreal), Full rebuild (`tools/brk_rebuild.ps1`, closes Unreal; done when `logs/brk_rebuild_done.txt` exists).
**World**: Rebuild grid data (`tools/build_island_grid.py`), Apply grid to map (`scripts/brk_grid_island.py`, closes Unreal).
**Shots**: Brickell shot (`tools/brk_shot.ps1`, camera presets from the manifest), Island aerial (`tools/island_shot.ps1`). A **Night** option passes `grid.Night 1` where the script supports cvars.
**Tests**: Grid (`brk_grid_pie_test`), Repair job (`brk_job_pie_test`), Island night (`brk_island_night_test`), Multiplayer suite (`tools/run_pie_multiplayer.ps1 …`), Unit tests (ask Quik which script runs the 20/20 suite), Package + full test (`tools/package_and_test.ps1`).

All of these register with `"districts": ["brickell"]` (legacy) for now.

Legacy parsers: `ARCH <TAG> RESULT|FAIL` lines, `PACKAGE: BUILD SUCCESSFUL/FAILED`, `NETTEST server/client PASS/FAIL`; `ERROR` on `Traceback`, `Fatal error`, `Unhandled`, `LogPython: Error`. Unit-test them against real log excerpts saved as fixtures.

### 5.4 Runner: built to scale

- **Resource queues**, not one global queue: `unreal` jobs run one at a time per machine (they close or launch the editor); `blender` jobs run up to `max_parallel_blender` at once (config, default 2, keeping the 24 GB GPU in mind); `python` jobs run freely. A job may need more than one resource.
- **Batches**: a batch is a list of jobs (e.g. "intake + validate + preview for 10 assets") with per-item results and a batch summary. Failures don't stop the batch unless the job says so.
- Timeouts stop the whole process tree. Cancel works and leaves no orphaned Unreal processes. `run_pie_multiplayer.ps1` rewrites `EditorPerProjectUserSettings.ini` and restores it by hash, so cancel must let that restore run, or restore from `%TEMP%\EditorPerProjectUserSettings.ini.pie_backup`. Test this specifically.
- **"This will close Unreal"** confirmation before any flagged job.
- Every run is stored in `runs/<timestamp>_<job>/`: `run.json` (job, district, params, machine id, git commit + dirty flag, start/end, status, summary, metrics), full log, copied images.

### 5.5 Machine config (portability is required, not optional)

`launcher.config.json` holds the UE root, Blender executable, builds folder, machine id and parallelism. On startup the launcher checks each path and disables jobs whose requirements are missing, with a plain message.

Separate small PR for Quik: optional environment overrides in the PowerShell runners (`LS_UE_ROOT`, `LS_BUILDS_DIR`), defaulting to today's values. The launcher sets them from config, so the same scripts run on Legend's PC.

### 5.6 Phase 1 acceptance

- [ ] Starts with one command; binds to 127.0.0.1 only.
- [ ] Job registry is data-driven; adding a job needs no code change (shown by adding one in the README walkthrough).
- [ ] Brickell district manifest exists and every job resolves paths through it.
- [ ] Every job has run at least once on Quik's machine, with its run folder as evidence. Failures are reported.
- [ ] Legacy parsers agree with a human reading the raw log, for every test job.
- [ ] Parallel Blender jobs and the one-at-a-time Unreal queue both work. Cancel works, including the multiplayer ini restore.
- [ ] Invalid parameters are refused before running (unit tested).
- [ ] History page shows status, district, machine, commit and images.
- [ ] Report: what works, what was tested, what wasn't, UI screenshots.

---

## 6. Phase 2: Standards (the definition of "done")

**Goal:** an asset can be checked automatically against one spec, and every asset has a visible status.

1. Draft `standards/asset_spec.json` (§4.2). Send the draft to Quik with the current Brickell assets' measured values, so he sets budgets from real data.
2. Build `tools/validate_asset.py` (emits `LSRESULT`). Run it on **all 34 existing Brickell assets** and publish the report. Expect failures; the point is to learn where the spec is wrong or the assets are. Don't "fix" assets in this phase.
3. Add the asset lifecycle (§4.3) with a migration for existing entries. The launcher gets an **Assets** view: filter by district, category and status; open the contact sheet; Approve / Reject.
4. Generalize intake and preview: add an optional `--district <id>` argument that reads `incoming_dir` and the asset manifest from the district manifest. The default stays `brickell` and existing commands behave identically (re-run one to prove it). Small PR for Quik.
5. `districts/brickell/tests.json`: the district's standard test set (grid, job, night, multiplayer, unit, package). The launcher gets **Run district test set**, one button producing one pass/fail table.

### Phase 2 acceptance
- [ ] Spec approved by Quik (his written OK in the PR).
- [ ] Validator report on all 34 Brickell assets, with a per-check failure count.
- [ ] Lifecycle visible in the launcher; Approve/Reject recorded with name and time.
- [ ] Intake/preview work with `--district`, and Brickell commands are unchanged.
- [ ] District test set runs from one button.

---

## 7. Phase 3: Asset factory (batch production)

**Goal:** reference image → validated, previewed asset, many at a time, with cost control.

### 7.1 Tripo API

- Read Tripo's **official API docs** (`https://developers.tripo3d.ai/en`) first. Confirm auth, image-to-3D task creation, polling, download format, rate limits and **credit cost**. Don't guess endpoints.
- `TRIPO_API_KEY` from the environment. Never commit it or write it to logs or run history.
- **Generate batch**: pick references from a district's queue (show the `ASSET_CATALOG.md` notes) → show **estimated total credits** → user confirms → submit within the rate limit → download `.glb` → intake → validate → preview, all automatic.
- **Budget guard**: a per-batch and per-month credit cap in config. The launcher refuses to submit past it.
- Results land as `generated` / `cleaned` / `validated` (or failed with reasons). A human still approves.
- Keep the source `.glb`, the reference image and the Tripo task id with each asset.

### 7.2 Default layout for new districts

```
districts/<id>/district.json  tests.json  asset_status.json (if sidecar)
data/districts/<id>/          # layout, streets, grid, assets
assets/incoming/<id>/<ASSET_ID>/
reference/districts/<id>/queue_<name>/
```

### Phase 3 acceptance
- [ ] A batch of 5 references (start with simple street items) runs end to end without manual steps.
- [ ] Estimated vs actual credits recorded; the cap is enforced (tested with a low cap).
- [ ] Failure paths handled: API error, timeout, validator failure.
- [ ] Metrics: median minutes from "pick reference" to "contact sheet," compared with the manual route.
- [ ] Then the full 32-image T01–V04 queue, with a report of first-pass validator rate.

---

## 8. Phase 4: Second-district pilot (the real test of scale)

**Goal:** prove the kit by standing up a second district from it, and measure that it's faster than Brickell was.

1. **Legend and Quik choose the pilot district** (candidates: a small Grove/CocoWalk block, a warehouse scene, or a small island district). Keep it small.
2. `tools/new_district.py <id>`: creates the manifest and folders (§7.2), duplicates a **template map** (a stripped base level with sky, water, lighting and player start; Quik picks or approves it), and registers the standard test set.
3. Generalize the grid where needed: `build_island_grid.py` and the grid map script take the district's layout from the manifest. Tests that hard-code pilot-zone IDs (`F1c`, `E090`, `Worker1`) read them from the district's `tests.json` instead. **Each of these is a small PR for Quik**, defaulting to Brickell's values.
4. Generalized swap: one `swap_assets.py` that places approved assets from the district's layout into its map, replacing the need for per-district `brk_swap_*` copies. Keep the Brickell scripts as they are.
5. Run the district test set on the pilot district.

### Phase 4 acceptance
- [ ] Pilot district created from the kit, with no copied-and-edited scripts.
- [ ] It's powered (grid), has approved assets placed, and passes its test set (or failures are reported with reasons).
- [ ] **Bootstrap time recorded** (new district → first passing test set) and compared with Brickell's history in `docs/WEEK_LOG.md` / `docs/PROGRESS.md`.
- [ ] A list of every Brickell-only assumption found and how it was resolved. This becomes the kit's checklist for district three.

---

## 9. Phase 5: Connect to V3 (design first)

**Depends on** V3 shared saving being live. Don't write Phase 5 code before that.

- The **launcher pulls**: it signs in to V3's shared store, reads queued requests ("build warehouse speaker U07 for district X"), and shows them as requests. A human clicks Run.
- After a run it **pushes a summary** (status, counts, commit, thumbnail, lifecycle status) back. V3's Asset Needs then shows real status from §4.3.
- A district progress view (assets by status, test-set status) is the "island lights up as it's built" view, fed by real data.
- Optional: draft a The Wire entry from highlight renders (team rule: "only the good ones").
- Write a one-page design for approval first. The launcher is never exposed to the internet.

---

## 10. Metrics (tracked from Phase 1, shown in the launcher)

| Metric | Why |
|---|---|
| Minutes per asset, reference → approved | Is the factory getting faster? |
| First-pass validator rate | Are references and generation improving? |
| Manual touches per asset | Where humans still have to step in |
| Credits per approved asset | Cost control |
| District bootstrap time | The headline number for the kit |
| Test-set pass rate per district, over time | Quality as the world grows |
| Regressions caught (tests that failed after once passing) | Proof that fixes stay fixed |

---

## 11. Out of scope

- New gameplay, C++ features, or map edits beyond what registered jobs do.
- Any change to `main` or the live website without Legend's approval.
- A cloud or remote runner; anything reachable from the internet.
- Running arbitrary commands, or the ~25 one-off probe/debug scripts (`brk_inspect*.py`, `probe_*.py`, `nav_*`, `*_probe.py`).
- Story or canon decisions.
- Spending money (Tripo credits included) beyond the budget Legend sets.

---

## 12. Open questions

**Quik**
1. Which scripts do you run most? Those jobs get built and polished first.
2. Which script runs the 20/20 headless unit suite?
3. Blender version, and is it on PATH?
4. Asset lifecycle: a new field in `brickell_assets.json`, or a sidecar file?
5. Triangle and texture budgets per category for the spec.
6. Which map should be the template for new districts?

**Legend**
7. Will the launcher run on your PC too? (Assumed yes, so portability is in Phase 1.)
8. Tripo: API key, plan and a monthly credit budget.
9. With Quik: which district is the Phase 4 pilot?

**Both**
10. Is `D:\Builds\` still the builds location?

---

## 13. Reporting

At the end of each phase: a short report (it can become a The Wire entry) with what was built, evidence (run folders, counts, screenshots), what was **not** verified, every change to Quik's scripts as a diff, the metrics so far, and open questions. Then stop and wait for review.
