# achimala/thelongsilence architecture

> Architecture diagram of the GitHub repository achimala/thelongsilence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/achimala/thelongsilence
- Repository: https://github.com/achimala/thelongsilence

## Overview

#### Purpose and Runtime

THE LONG SILENCE is a browser-based procedural space-exploration game. It runs as a Vite-built WebGL2 application, with procedural geometry, hand-written GLSL, and WebAudio rather than authored runtime content. Browser startup flows from `index.html` to `src/main.js`; deployment is static-oriented, with Cloudflare configuration in `wrangler.jsonc`.

#### Application Composition

`src/main.js` assembles the runtime. `src/core/Engine.js` owns the Three/WebGL renderer, frame loop, dynamic render-scale/quality behavior, and scene-level rendering. `src/core/Input.js` normalizes desktop and touch controls into gameplay actions. `src/game/Game.js` is the primary world-state coordinator; `src/game/Director.js` sequences cinematic or scripted moments.

#### Flight, Progression, and World-State Control

Gameplay state centers on the player ship, scans, landing, fold travel, map navigation, discoveries, and progression toward the seven Resonators. `src/game/Game.js` coordinates these systems, while `src/game/directives.js`, `src/game/encounters.js`, and `src/game/lore.js` define authored progression/event content. A floating-origin boundary is fundamental: the ship remains near world origin and distant system objects are transformed relative to it each frame.

#### Seeded Universe and Spatial Modes

Universe generation is deterministic and seed-driven in `src/world/generate.js`. Orbital content is split into specialized procedural entities: `src/world/Planet.js`, `src/world/Star.js`, `src/world/Station.js`, `src/world/Fleet.js`, `src/world/Asteroids.js`, and `src/world/Dust.js`. Traffic is clock-derived analytic motion rather than persistent physics simulation, allowing stable positions after time skips and fold jumps.

Landing changes the rendering/world representation: `src/world/Surface.js` provides close-range radial terrain, while `src/world/Planet.js` represents worlds from orbit. These modes must share terrain and atmospheric assumptions to avoid discontinuities.

#### Ship and Shared Construction Kit

`src/ship/Ship.js` and `src/ship/Player.js` implement the vessel and flight-facing player representation. The interior/cockpit experience is separately composed through `src/ship/Interior.js`, `src/ship/Cockpit.js`, `src/ship/HoloMap.js`, and `src/ship/HoloScreen.js`. Shared hard-surface construction and surfacing lives in `src/gfx/greeble.js`; it underpins the player hull, stations, fleets, and derelicts, establishing a common material/draw-call strategy.

#### Rendering Pipeline and Performance Boundaries

Rendering features are layered around `src/core/Engine.js`, `src/gfx/PostFX.js`, and `src/gfx/Sky.js`. `src/gfx/cubeBake.js` bakes procedural planet cubemaps so costly terrain evaluation is not performed per visible pixel each frame. Planet shader implementations are concentrated in `src/world/planetBakeShader.js` and `src/world/planetShaders.js`; shared GLSL, including manual logarithmic-depth support, is in `src/gfx/glsl/noise.js`.

The engine dynamically trades render resolution for frame time, retaining feature parity. Logarithmic depth and floating origin are cross-cutting rendering constraints for all custom materials.

#### Presentation, Audio, and Asset Pipeline

`src/ui/HUD.js` and `src/ui/Codex.js` expose flight state, map/archive information, and discoveries; styling is in `src/ui/style.css`. Procedural sound is managed by `src/audio/Audio.js` through browser WebAudio. The notable packaged asset is the baked interior kit at `public/models/interior_kit.glb`, generated via the Blender/Python pipeline under `tools/interior_bake/` and consumed with ship interior assets/material definitions in `src/ship/interiorAssets.js` and `src/ship/interiorMaterials.js`.

Main entry points: [`src/game/Game.js`](https://github.com/achimala/thelongsilence/blob/main/src/game/Game.js) (Game), [`src/core/Engine.js`](https://github.com/achimala/thelongsilence/blob/main/src/core/Engine.js) (Engine), [`src/main.js`](https://github.com/achimala/thelongsilence/blob/main/src/main.js) (Runtime assembly), [`src/gfx/greeble.js`](https://github.com/achimala/thelongsilence/blob/main/src/gfx/greeble.js) (Hard-surface kit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Browser Runtime"]
  node_entry["Browser entry<br/>Vite entry<br/>[index.html]"]
  node_main["Runtime assembly<br/>bootstrap<br/>[main.js]"]
  node_engine["Engine<br/>WebGL frame loop<br/>[Engine.js]"]
  node_input["Input<br/>control normalization<br/>[Input.js]"]
end

subgraph group_gameplay["Gameplay &amp; Universe"]
  node_game["Game<br/>world-state coordinator<br/>[Game.js]"]
  node_director["Director<br/>cinematic sequencer<br/>[Director.js]"]
  node_progression["Progression content<br/>authored directives"]
  node_universe["Seeded universe<br/>procedural generation<br/>[generate.js]"]
  node_orbital["Orbital entities<br/>procedural world objects"]
  node_surface["Surface mode<br/>radial terrain<br/>[Surface.js]"]
end

subgraph group_rendering["Rendering"]
  node_postfx["Post processing<br/>render effects<br/>[PostFX.js]"]
  node_sky["Procedural sky<br/>environment rendering<br/>[Sky.js]"]
  node_planet_render["Planet render pipeline<br/>cubemap bake and shaders"]
  node_glsl["Shared GLSL<br/>shader primitives<br/>[noise.js]"]
end

subgraph group_ship["Ship Experience"]
  node_ship_flight["Ship and player<br/>flight representation"]
  node_interior["Cockpit interior<br/>interior composition"]
  node_greeble["Hard-surface kit<br/>procedural construction<br/>[greeble.js]"]
end

subgraph group_presentation["Presentation &amp; Assets"]
  node_ui["HUD and Codex<br/>game UI"]
  node_audio["Procedural audio<br/>WebAudio<br/>[Audio.js]"]
  node_interior_assets["Interior asset pipeline<br/>baked GLB assets"]
end

node_entry -->|"loads"| node_main
node_main -->|"creates"| node_engine
node_main -->|"assembles"| node_game
node_main -->|"installs"| node_input
node_input -->|"gameplay actions"| node_game
node_engine -->|"frame updates"| node_game
node_game -->|"sequences"| node_director
node_game -->|"evaluates"| node_progression
node_game -->|"generates"| node_universe
node_universe -->|"populates"| node_orbital
node_game -->|"switches on landing"| node_surface
node_game -->|"controls"| node_ship_flight
node_engine -->|"renders with floating origin"| node_orbital
node_engine -->|"renders"| node_surface
node_engine -->|"composites"| node_postfx
node_engine -->|"renders"| node_sky
node_orbital -->|"planet visuals"| node_planet_render
node_planet_render -->|"uses"| node_glsl
node_greeble -->|"constructs hull"| node_ship_flight
node_greeble -->|"constructs structures"| node_orbital
node_interior_assets -->|"provides kit"| node_interior
node_interior -->|"embeds in vessel"| node_ship_flight
node_game -->|"publishes state"| node_ui
node_game -->|"drives sound"| node_audio

click node_entry "https://github.com/achimala/thelongsilence/blob/main/index.html"
click node_main "https://github.com/achimala/thelongsilence/blob/main/src/main.js"
click node_engine "https://github.com/achimala/thelongsilence/blob/main/src/core/Engine.js"
click node_input "https://github.com/achimala/thelongsilence/blob/main/src/core/Input.js"
click node_game "https://github.com/achimala/thelongsilence/blob/main/src/game/Game.js"
click node_director "https://github.com/achimala/thelongsilence/blob/main/src/game/Director.js"
click node_universe "https://github.com/achimala/thelongsilence/blob/main/src/world/generate.js"
click node_surface "https://github.com/achimala/thelongsilence/blob/main/src/world/Surface.js"
click node_postfx "https://github.com/achimala/thelongsilence/blob/main/src/gfx/PostFX.js"
click node_sky "https://github.com/achimala/thelongsilence/blob/main/src/gfx/Sky.js"
click node_glsl "https://github.com/achimala/thelongsilence/blob/main/src/gfx/glsl/noise.js"
click node_greeble "https://github.com/achimala/thelongsilence/blob/main/src/gfx/greeble.js"
click node_audio "https://github.com/achimala/thelongsilence/blob/main/src/audio/Audio.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_main,node_engine,node_input toneBlue
class node_game,node_director,node_progression,node_universe,node_orbital,node_surface toneAmber
class node_postfx,node_sky,node_planet_render,node_glsl toneMint
class node_ship_flight,node_interior,node_greeble toneRose
class node_ui,node_audio,node_interior_assets toneIndigo
```

## Components

### Browser Runtime

- [Browser entry](https://github.com/achimala/thelongsilence/blob/main/index.html): Vite entry · Starts the static WebGL2 application. · `index.html`
- [Runtime assembly](https://github.com/achimala/thelongsilence/blob/main/src/main.js): bootstrap · `src/main.js`
- [Engine](https://github.com/achimala/thelongsilence/blob/main/src/core/Engine.js): WebGL frame loop · Owns renderer, scene rendering, and adaptive render scale. · `src/core/Engine.js`
- [Input](https://github.com/achimala/thelongsilence/blob/main/src/core/Input.js): control normalization · Unifies desktop and touch actions. · `src/core/Input.js`

### Gameplay & Universe

- [Game](https://github.com/achimala/thelongsilence/blob/main/src/game/Game.js): world-state coordinator · Coordinates flight, scans, landing, travel, discoveries, and progression. · `src/game/Game.js`
- [Director](https://github.com/achimala/thelongsilence/blob/main/src/game/Director.js): cinematic sequencer · `src/game/Director.js`
- **Progression content**: authored directives · Defines directives, encounters, and lore toward the Resonators.
- [Seeded universe](https://github.com/achimala/thelongsilence/blob/main/src/world/generate.js): procedural generation · Deterministically creates systems from seeds. · `src/world/generate.js`
- **Orbital entities**: procedural world objects · Planets, stars, stations, fleets, asteroids, and dust use analytic motion.
- [Surface mode](https://github.com/achimala/thelongsilence/blob/main/src/world/Surface.js): radial terrain · Close-range landing representation sharing planet assumptions. · `src/world/Surface.js`

### Rendering

- [Post processing](https://github.com/achimala/thelongsilence/blob/main/src/gfx/PostFX.js): render effects · `src/gfx/PostFX.js`
- [Procedural sky](https://github.com/achimala/thelongsilence/blob/main/src/gfx/Sky.js): environment rendering · `src/gfx/Sky.js`
- **Planet render pipeline**: cubemap bake and shaders · Bakes terrain cubemaps and applies planet shaders.
- [Shared GLSL](https://github.com/achimala/thelongsilence/blob/main/src/gfx/glsl/noise.js): shader primitives · Includes noise and manual logarithmic-depth support. · `src/gfx/glsl/noise.js`

### Ship Experience

- **Ship and player**: flight representation
- **Cockpit interior**: interior composition · Builds cockpit, holomap, and holoscreen experience.
- [Hard-surface kit](https://github.com/achimala/thelongsilence/blob/main/src/gfx/greeble.js): procedural construction · Shared hull, station, fleet, and derelict surfacing strategy. · `src/gfx/greeble.js`

### Presentation & Assets

- **HUD and Codex**: game UI · Exposes flight state, discoveries, maps, and archive information.
- [Procedural audio](https://github.com/achimala/thelongsilence/blob/main/src/audio/Audio.js): WebAudio · `src/audio/Audio.js`
- **Interior asset pipeline**: baked GLB assets · Blender/Python output is consumed by interior asset and material definitions.

## Connections

- Browser entry → Runtime assembly: loads
- Runtime assembly → Engine: creates
- Runtime assembly → Game: assembles
- Runtime assembly → Input: installs
- Input → Game: gameplay actions
- Engine → Game: frame updates
- Game → Director: sequences
- Game → Progression content: evaluates
- Game → Seeded universe: generates
- Seeded universe → Orbital entities: populates
- Game → Surface mode: switches on landing
- Game → Ship and player: controls
- Engine → Orbital entities: renders with floating origin
- Engine → Surface mode: renders
- Engine → Post processing: composites
- Engine → Procedural sky: renders
- Orbital entities → Planet render pipeline: planet visuals
- Planet render pipeline → Shared GLSL: uses
- Hard-surface kit → Ship and player: constructs hull
- Hard-surface kit → Orbital entities: constructs structures
- Interior asset pipeline → Cockpit interior: provides kit
- Cockpit interior → Ship and player: embeds in vessel
- Game → HUD and Codex: publishes state
- Game → Procedural audio: drives sound