# JCOM and Conquer: Architecture

Compiled 2026-10-20 by the dolphin4 team.
This document describes the existing system architecture.
It sets no new rules.
Each section cites its verified sources.

Skills and approach live in `jcom_v0bb_simulation_svc_skills`.
Repository definitions live in [`REPOS.md`](REPOS.md).
Standards live in `standards/` across units, maps, logic, geometry, lookdev, and blueprints.

---

## 1. Two Code Trees

The game currently has two active code trees:

| Tree | Repository | Primary Stack & Role |
|---|---|---|
| **v3 Engine** (skirmish build) | `jcom_v0bb_simulation_jslcnc_v3_cnc_rev` | TypeScript + Three.js + Vite client with dedicated simulation core. Supports browser RTS skirmish and campaign modes. |
| **2.5D Shell App** | `jcom_v0bb_simulation_jslcnc` | 2.5D shell app mounted in the Mainframe shell (`simulation-jslcnc-battlefield`). Derives sim core from the 2D game core. |

Dispatch briefs decide which tree receives a given change.
This document does not decide between them.

---

## 2. Shell and Modules

- A module is a folder with `module.json`, `index.html` with `data-app-id`, `guest.js` handshake, theme sync, `serve.mjs`, and tests.
- Applications mount in the shell at `/apps/<id>`.
- The shell navigation bar renders the registry `sidebarModules`.
- The game module talks to the host shell via `postMessage` through `shellBridge.ts`.
- Integration procedures follow `svc_skills/architecture-module-integration`.

---

## 3. Client: Skirmish and Campaign (v3 Tree)

- The entry point is `src/main.ts`.
- Pages include `index.html`, `campaign.html`, `builder.html`, `gallery.html`, and `compare.html`.
- Simulation code lives in `src/sim.ts` and `src/core/`.
- Simulation runs at a fixed tick rate (`TICK_HZ = 30`) with seeded pseudo-random number generation.
- Simulation is fully deterministic for multiplayer lockstep and replay verification.
- New mechanics live in `src/mechanics/<area>/`. Each mechanic carries a `MECHANICS-<name>.md` record.
- Shared files carry only hook lines to prevent merge collisions.

---

## 4. Rendering System

- Built on Three.js using WebGL2 (`three` version `^0.170.0`).
- Model contracts require facing `-Z` with `+Y` pointing up. Models use named pivots and LOD levels.
- Team colour uses a dedicated `houseTint` material.
- **WebGPU Status:** Currently blocked on WebGL2. Custom shaders for terrain splatting and water use `MeshStandardMaterial.onBeforeCompile`. WebGPURenderer does not support `onBeforeCompile`. Migration to TSL (Three Shading Language) node materials is planned.

---

## 5. Game Data and Rules

- All tunable parameters live in JSON rules files with a `source` column.
- Hard-coded literals inside TypeScript logic are prohibited.
- Data directory root holds: `rules/`, `missions/`, `maps/`, `factions/`, `weapons/`, and `rigs/`.
- Balance and stats belong to `jcom_v0bb_simulation_svc_data`.
- Mission scripts belong to `jcom_v0bb_simulation_svc_maps`.
- Audio cues belong to `jcom_v0bb_simulation_svc_audio`.

---

## 6. Asset Pipeline

- Headless 3D models build with Blender on dedicated build workers.
- Textures generate through Substance Designer.
- Review process: Sol builds models; Opus reviews against reference photographs.
- Assets store on private storage and index in Postgres catalogues.
- The game resolves asset models through authoritative asset registry versions, never through hard-coded paths.

---

## 7. Maps and Missions

- Maps are JSON files containing heightmaps, terrain layers, spawn points, and objects.
- Map cell scales are standardized: 5 m (infantry/base), 20 m (tactical default), 80 m (operational coast).
- Map generation runs through `npm run gen-map` and checks with map validation tools.
- Map lab development lives in `jcom_v0bb_simulation_svc_lab_map`.
- Map specifications follow `jcom_v0bb_simulation_design_standards_maps`.

---

## 8. Automated Testing

- Test suites run with Vitest (`npm test`).
- Performance and simulation benchmarks run with `test:perf` and `bench:sim`.
- Game test suites execute on dedicated test workers (SV3/SV4) via `lane-test.ps1`.
- Tests never run on development worker SV2.
- Every new game mechanic must provide unit tests and verify determinism.

---

## 9. Deployment Architecture

- Production hosting runs on Cloudflare Pages with automated deployment on git push.
- Dual-site release topology: authenticated internal shell (`jslc.io`) and public shell (`jewishspacelasercommand.com`).
- Public mirrors include `jcnc.io` (game site) and `jslcnc.com`.
- Public deployment gates enforce: allowlist verification, public build, secret scanning, and promotion checks.
- Changes deploy only after verification. Rollback artifacts stay preserved.

---

## 10. House Design System

- Built on the JSLC design token vocabulary (`shell-tokens.css`).
- Mobile-first target viewport: 393 × 852 px (iPhone reference).
- In-game HUD follows the JCOM and Conquer HUD design system (`hud-tokens.json`).
- UI styling avoids amber or decorative yellow colors.
- Component layouts maintain strict contrast and touch target heights.