Terrarum/CLAUDE.md

# Terrarum

A modular 2D side-scrolling tilemap platformer engine and game, built on LibGDX with Kotlin/Java. GPL-3.0.

## Build & Run

- **IDE**: IntelliJ IDEA (project files: `Terrarum_renewed.iml`, `TerrarumBuild.iml`)
- **JDK**: 21
- **Language**: Kotlin + Java mixed; Kotlin is primary, `App.java` and `FrameBufferManager.java` are Java
- **Dependencies**: All libraries are in `lib/` (fat-jar approach, no Maven/Gradle). Includes LibGDX, GraalVM JS (modified), dyn4j (Vector2 only), custom bitmap font lib
- **Entry point**: `net.torvald.terrarum.Principii.main()` (Java) which launches `App` (the LibGDX `ApplicationListener`)
- **Distribution**: `buildapp/` scripts produce per-platform bundles with jlink'd runtimes
- **Assets**: `assets/` for development, `assets_release/` for distribution. Custom `.tevd` archive format for release assets (`AssetCache.kt`)

## Project Structure

```
src/net/torvald/terrarum/
  App.java                  -- Main application class (LibGDX ApplicationListener). GL thread, render loop, splash screen
  CommonResourcePool.kt     -- Thread-safe GL resource loading with dispatch queues
  ModMgr.kt                 -- Module manager. Scans/loads game modules, provides getGdxFile/getJavaClass
  IngameInstance.kt          -- Base class for game screens (show/hide/render/resize lifecycle)
  Terrarum.kt               -- Game-level singleton (ingame instance management, extension functions)
  GameUpdateGovernor.kt      -- Update/render tick governors (ConsistentUpdateRate, Anarchy)
  MusicService.kt            -- Music playback management

  modulebasegame/
    EntryPoint.kt            -- Basegame module entry point (registers items, fixtures, blocks, weather)
    TitleScreen.kt           -- Title screen (demo world rendering, async loading)
    TerrarumIngame.kt        -- Main gameplay screen
    IngameRenderer.kt        -- World rendering pipeline (FBO composition, lightmap, blur, shadows)
    BuildingMaker.kt         -- Building editor screen

  worlddrawer/
    WorldCamera.kt           -- Camera position tracking (follows player, interpolated movement)
    LightmapRenderer.kt      -- Per-tile RGB+UV light calculation and rasterisation
    BlocksDrawer.kt          -- Tile rendering
    FeaturesDrawer.kt        -- Wire/feature overlay rendering

  gamecontroller/
    IME.kt                   -- Input Method Engine (GraalVM JS keyboard layouts, loaded on daemon thread)

  weather/
    WeatherMixer.kt          -- Weather state machine, skybox rendering
    SkyboxModelHosek.kt      -- Physically-based sky model
```

## Architecture: Threading & GL Dispatch

All OpenGL calls (Texture, ShaderProgram, FrameBuffer creation) **must** happen on the GL thread. The codebase uses a dispatch mechanism to safely create GL resources from background threads.

### CommonResourcePool (the dispatch hub)

```
Background Thread                          GL Thread (App.render)
     |                                          |
     |-- addToLoadingList("name", { Texture() })|
     |-- loadAll()                              |
     |     |                                    |
     |     +-- if on GL thread: run directly    |
     |     +-- if not: enqueue to               |
     |         glDispatchQueue + latch.await()  |
     |                                     CommonResourcePool.update()
     |                                          |-- poll glDispatchQueue
     |                                          |   run loadfun, latch.countDown()
     |                                          |-- poll glRunnableQueue
     |                                          |   run block, latch.countDown()
     |                                          |-- poll slowLoadingQueue (one per tick)
     |                                          |
     +-- latch released, continues <------------+
```

Key methods:
- `loadAll()` -- batch load; blocks background thread until GL thread processes
- `loadAllSlowly()` -- timesliced; one resource per tick via `update()`
- `runOnGLThread { }` -- run arbitrary block on GL thread, blocking caller
- `update()` -- called every tick from `App.render()`, processes all queues
- `getOrPut(name, loadfun, killfun)` -- thread-safe get-or-create with GL dispatch

### App.java Boot Sequence

```
create()
  -> postInit()          [GL thread, synchronous]
       |-- load shaders, fonts, audio device, IME
       |-- CommonResourcePool.setGLThread(currentThread)
       |-- spawn Terrarum-PostInitLoader thread:
       |     ModMgr.invoke()           // module entry points (dispatched to GL via runOnGLThread)
       |     CommonResourcePool.loadAllSlowly()  // timesliced resource loading
       |     loadingThreadDone = true
       +-- return (non-blocking)

render() loop [GL thread]
  while currentScreen == null:
       |-- drawSplash()
       |-- CommonResourcePool.update()   // process GL dispatch queues
       |-- when loadingThreadDone && loaded:
       |     postLoadInit()              // tile atlas, audio mixer, Terrarum.initialise()
       |     setScreen(titleScreen)      // transitions to title screen
```

### TitleScreen Async Loading

`TitleScreen.show()` returns immediately after starting a background thread. The splash screen continues displaying until all loading completes.

```
show()
  |-- quick GL setup (viewport, input processor, FBO, savegame list)
  |-- spawn Terrarum-TitleScreenLoader thread:
  |     load demo world, compute camera nodes, bogoflops, audio reset
  |     backgroundLoadDone = true
  +-- return

renderImpl() [GL thread, every frame]
  if !loadDone:
       |-- App.drawSplash()
       |-- processGLLoadStep()  // state machine, one step per frame:
       |     0: wait for backgroundLoadDone
       |     1: SkyboxModelHosek.loadlut()
       |     2: IngameRenderer.setRenderedWorld + WeatherMixer init
       |     3: load halfgrad texture
       |     4: UIFakeGradOverlay
       |     5: UIFakeBlurOverlay
       |     6: UIRemoCon
       |     7: MusicService.enterScene, gameUpdateGovernor.reset(), loadDone=true
  else:
       normal title screen rendering (world + UI via IngameRenderer)
```

### IME Loading

`IME.kt` object `init {}` spawns a `Terrarum-IMELoader` daemon thread for GraalVM JS context binding and key layout/IME file scanning. Icon texture loading remains synchronous (requires GL thread).

### ModMgr Class Initialisation

`ModMgr.kt` object `init {}` only does metadata loading and class instantiation (fast). The heavy `invoke()` method runs entry points wrapped in `CommonResourcePool.runOnGLThread { }` to avoid GL calls on the wrong thread. This separation prevents `<clinit>` lock deadlocks where a background thread holding the class init lock blocks on a GL dispatch latch while the GL thread tries to access the same class.

## Architecture: Rendering Pipeline

### IngameRenderer

Singleton object. Lazily initialised on first `invoke()` call via `invokeInit()`.

Render path (per frame):
1. `LightmapRenderer.recalculate()` -- every 3 frames, computes per-tile RGBA light values
2. `prepLightmapRGBA()` -- Kawase blur on lightmap into `lightmapFbo`
3. `BlocksDrawer.renderData()` -- prepare tile draw data
4. `drawToRGB()` -- render world tiles + actors into `fboRGB` (with shadow FBOs)
5. `drawToA()` -- render alpha/glow channel
6. Composite: sky -> world -> light multiply -> emissive blend -> vibrancy -> UI
7. Output to `App.renderFBO`, then `TerrarumPostProcessor.draw()` applies final effects

**Critical ordering in `resize()`**: `BlocksDrawer.resize()` and `LightmapRenderer.resize()` must be called **before** `lightmapFbo` creation, because `lightmapFbo` dimensions derive from `LightmapRenderer.lightBuffer` size.

### WorldCamera

Follows an `ActorWithBody` (player or camera actor). Position interpolated per frame. `WorldCamera.x/y` = top-left corner of visible area. `gdxCamX/Y` = centre of visible area. `moveCameraToWorldCoord()` positions the IngameRenderer camera for world-space drawing; `setCameraPosition(0,0)` positions it for screen-space drawing.

### FBO Extension Functions

- `FrameBuffer.inAction(camera, batch) { }` -- bind FBO, set camera to FBO dimensions (Y-down), run block, restore camera to screen dimensions
- `FrameBuffer.inActionF(camera, batch) { }` -- same but Y-up (for flipped FBO content)

Both save/restore `camera.position` and call `setToOrtho` with `App.scr.wf/hf` on exit.

## Key Conventions

- **GL thread safety**: Any code creating `Texture`, `TextureRegion`, `TextureRegionPack`, `ShaderProgram`, `FrameBuffer`, or `Pixmap` must run on the GL thread. Use `CommonResourcePool.runOnGLThread { }` when on a background thread.
- **Kotlin `object` singletons**: First access triggers `<clinit>`. Keep `init {}` blocks fast (no blocking, no GL dispatch). Defer heavy work to explicit `invoke()` methods.
- **`ConcurrentHashMap` cannot store null values**. Use `HashMap` for maps that need nullable values (e.g. `poolKillFun`).
- **`@Volatile`** for cross-thread boolean flags (`loadDone`, `backgroundLoadDone`, etc.)
- **`lateinit var` guards**: Use `::prop.isInitialized` checks in `resize()` and `dispose()` for properties set during async loading steps.
- **`ConsistentUpdateRate`**: Accumulates delta time; may call `updateFunction` multiple times before `renderFunction`. Call `.reset()` before transitioning to active rendering to avoid catch-up storms.
- **Textures**: Use TGA format. Images with semitransparency must be TGA; opaque images may be PNG.
- **Coordinate system**: Y-down (camera `setToOrtho(true, ...)`). `setCameraPosition(0, 0)` places origin at screen top-left, which is not LibGDX nor OpenGL works natively, hence the existence of `FlippingSpriteBatch`. If the user reports renders are flipped vertically, try draw()/drawFlipped() accordingly.
- **ROUNDWORLD**: World wraps horizontally. `WorldCamera.x` uses `fmod worldWidth`. Lightmap and tile drawing account for wrapping.