![dynostic](dynostic.png)

A reusable **deterministic tactical-sim core** in **Rust** with a **LÖVE (LuaJIT) front-end**.

The goal: build simultaneous turn-based” combat loop games by reusing the *simulation + data pipeline*, while iterating quickly on *feel/UI* in LÖVE.

## Architecture
```
dynostic/
  rust/                 # Cargo workspace
    dynostic_core/      # pure deterministic simulation (no I/O, no rendering)
    dynostic_ffi/       # C ABI boundary (cdylib) for LuaJIT FFI
    dynostic_cli/       # tiny dev CLI (optional utilities / sanity checks)
  love/                 # LÖVE project (UI, rendering, input)
    main.lua
    dynostic.lua        # Lua wrapper around the Rust FFI
    native/             # place compiled native libs here (per platform)
```

### Design principles
- **Deterministic**: fixed-tick simulation, integer math, seeded RNG.
- **Event-sourced**: sim emits compact events; UI consumes events to animate.
- **FFI boundary stays dumb**: only POD types (ints, pointers, lengths), handle-based API.
- **Data-driven**: content can be loaded/compiled without changing engine code.

## Compatibility contract
See `docs/compatibility_contract.md` for ABI/schema/pack compatibility rules and migration policy.

## Documentation
Start with the guide at `docs/guide/README.md`.

## Quick start (dev)
### 1) Build the Rust native library
From repo root:
```bash
make build-native
```

This compiles `dynostic_ffi` and copies the resulting dynamic library into:
```
love/native/<platform>/
```

### 2) Run the LÖVE project
```bash
love love
```

You should see a small window with a moving dot driven by the Rust sim.

## Projection mode (prototype)
The LÖVE front-end defaults to orthographic projection. To try isometric projection:
```bash
export DYNOSTIC_PROJECTION=isometric
love love
```

Optional isometric tile height override (default is `tile_size / 2`):
```bash
export DYNOSTIC_ISO_TILE_H=20
love love
```

## New game scaffold
Generate a pack skeleton from the reference template:
```bash
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- new "My Game" --out games
```

The reference game lives at `examples/reference_game`.

## Profiling (headless)
Use the CLI to print hot-path counters (pathfinding, LOS, ability targeting, etc.):
```bash
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- --ticks 200 --profile
```

## Packaging
Build a portable `.love` archive and a platform folder with native libs:
```bash
make package-love
make package
```

## Shipping (reproducible + signed)
Deterministic `.love` packaging respects `SOURCE_DATE_EPOCH`:
```bash
SOURCE_DATE_EPOCH=1700000000 make package
```

Build a release manifest (engine + packs) and verify it:
```bash
make release
make release-verify
```

Sign packs and release manifests with an ed25519 key:
```bash
# generate keys
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- pack keygen --out-public keys/pack.pub --out-secret keys/pack.secret

# sign a pack.json
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- pack sign --pack dist/pack/pack.json --key keys/pack.secret

# sign a release manifest
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- release sign --manifest dist/release_manifest.json --key keys/pack.secret
```

`make release` will auto-sign `dist/pack/pack.json` when `RELEASE_SIGN_KEY` is set.
Set `RELEASE_ALLOW_UNSIGNED=1` to bypass pack signature checks (not recommended).

Auto-update check (local manifest only): set
`DYNOSTIC_UPDATE_MANIFEST=dist/release_manifest.json` before running the app to surface update
availability in the debug overlay.

## Mods (experimental)
Mods live under `mods/` and are enabled via `mods/mods.json`. Enabled mods are merged **after** the base pack.

Common commands:
```bash
# generate integrity hashes for a pack
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- pack hash --pack love/content/pack.json

# verify integrity hashes
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- pack verify --pack love/content/pack.json

# add/enable/disable mods
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- mod add --id cool_mod --path mods/cool_mod/pack.json --enable
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- mod list
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- mod disable cool_mod
```

Script permissions are gated by `pack.permissions.scripts` (default false). Set it to true in a pack to allow campaign scripts.

## Campaign lint + scripted runs
Validate campaign structure and branching requirements:
```bash
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- campaign lint --pack games/my_game/pack.json
```

Run a deterministic scripted campaign path and emit a final-state snapshot:
```bash
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- \
  campaign run --pack games/my_game/pack.json \
  --script games/my_game/tools/campaign_route_left_alliance.json \
  --out /tmp/campaign_left_snapshot.json
```

You can also audit asset handoff status (missing keys, placeholders, duplicate paths):
```bash
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- asset audit --pack games/my_game/pack.json
```

## Pack cache (compiled content)
Compile a pack into a deterministic cache blob for faster loads:
```bash
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- pack cache --pack love/content/pack.json
```

The runtime will use `pack.cache.json` automatically when present. Set `DYNOSTIC_PACK_CACHE=0` to disable.

## Cutscenes (prototype)
Validate and run a deterministic cutscene timeline:
```bash
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- cine validate --timeline tools/cutscene_demo.json
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- cine run --timeline tools/cutscene_demo.json
```

Branching + world effects example:
```bash
# choices file can be a JSON array like [0, 1] or { "choices": [0, 1] }
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- cine run --timeline tools/cutscene_branching.json --choices /tmp/cine_choices.json
```

Snapshot and resume:
```bash
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- cine save --timeline tools/cutscene_branching.json --ticks 2 --out /tmp/cine_snapshot.json
cargo run -p dynostic_cli --manifest-path rust/Cargo.toml -- cine resume --snapshot /tmp/cine_snapshot.json
```

`cine run` outputs `world_effects` so you can apply them at cutscene end (or ignore them for preview).

## Atmosphere (presentation-only)
Encounters can specify a biome or explicit atmosphere settings:
```json
{
  "biome": "wasteland",
  "atmosphere": {
    "preset": "dusty",
    "events": [
      { "kind": "time", "from": 0, "to": 200, "start": 0.2, "finish": 0.7 },
      { "kind": "fog", "from": 120, "to": 300, "start": 0.1, "finish": 0.35 }
    ]
  }
}
```

Presets include `clear`, `mist`, `dusk`, `night`, `storm`, `dusty`, and `smoky`.

## Cutscene Preview (LÖVE)
Launch the app and press `F7` to enter the cutscene preview tool. By default it loads `tools/cutscene_branching.json`.

Controls:
- `Space` play/pause, `Left/Right` step tick, `Shift+Left/Right` jump
- `1-9` choose options when a choice prompt is active
- `C` clear choices, `R` reload timeline, `L` cycle locale, `X` export preview bundle
- `[` / `]` adjust tick rate

Set `DYNOSTIC_CINE` to load a different timeline. Exported bundles go to `cine_preview_bundle.json` or `DYNOSTIC_CINE_BUNDLE`.

Localization + VO demo:
```bash
export DYNOSTIC_CINE=tools/cutscene_localized.json
export DYNOSTIC_CINE_LANG=es
```

`say` events accept `text_id` (localization key), optional `voice`, `portrait`, and `lip` frames; localization tables can live under `locales` in the timeline.

Camera macro demo:
```bash
export DYNOSTIC_CINE=tools/cutscene_macros.json
```

Macro events expand into ordinary `camera`/`fade` ops at load time, so replays stay simple. Each macro needs `x`, `y`, `zoom`, plus optional `duration` and a `preset` (`soft` or `bold`) to fill defaults.

Supported macros and parameters:
- `push_in`: `distance`, `offset_x`, `offset_y`
- `snap_zoom`: `delta`
- `smash_cut`: `duration`
- `handheld_sway`: `amplitude`, `steps`, `zoom_jitter`
- `rack_focus`: `delta`, `fade`

## Offline replay rendering (frames/video)
Render a replay into PNG frames (and optionally encode a video):
```bash
# render frames into render_frames/
DYNOSTIC_RENDER=1 DYNOSTIC_RENDER_REPLAY=../tools/golden/replay_combat.json make run

# render frames and run ffmpeg
DYNOSTIC_RENDER=1 DYNOSTIC_RENDER_REPLAY=../tools/golden/replay_combat.json DYNOSTIC_RENDER_FFMPEG=ffmpeg make run
```

Common options (env or CLI):
- `DYNOSTIC_RENDER_OUT` / `--render-out=`
- `DYNOSTIC_RENDER_PREFIX` / `--render-prefix=`
- `DYNOSTIC_RENDER_STEP=event|tick` / `--render-step=`
- `DYNOSTIC_RENDER_FROM` / `--render-from=` (event or tick index)
- `DYNOSTIC_RENDER_TO` / `--render-to=` (event or tick index)
- `DYNOSTIC_RENDER_SIZE=WxH` / `--render-size=` (or `--render-width=` / `--render-height=`)
- `DYNOSTIC_RENDER_HIDE_UI=0` / `--render-show-ui`
- `DYNOSTIC_RENDER_PREVIEW=1` / `--render-preview`
- `DYNOSTIC_RENDER_CAMERA` / `--render-camera=` (camera override JSON)
- `DYNOSTIC_RENDER_FFMPEG=ffmpeg` / `--render-ffmpeg`

Each run writes a manifest with per-frame hashes at:
```
render_frames/frame_manifest.json
```

Camera override example (fixed):
```json
{
  "x": 7,
  "y": 5,
  "zoom": 1200
}
```

Camera override example (shot list by event index):
```json
{
  "shots": [
    { "from": 1, "to": 120, "x": 6, "y": 5, "zoom": 1200 },
    { "from": 121, "to": 200, "entity_id": 3, "zoom": 1100 }
  ],
  "default": { "x": 7, "y": 5, "zoom": 1000 }
}
```

## Visual regression (golden frames)
Render golden frames and compare in CI:
```bash
make visual-record
make visual-check
```

The harness reads `tools/golden_manifest.json` and renders replay bundles only. Output layout:
- Golden frames: `tools/golden_frames/<label>/`
- New runs: `tools/visual_runs/<label>/`
- Diffs: `tools/visual_diffs/<label>/` and `tools/visual_diffs/summary.json`

Limit to specific bundles:
```bash
python3 tools/visual_regression.py check --label combat_basic --label stealth_smoke
python3 tools/visual_regression.py check --tag stealth
```

## Notes on distribution
Dynamic libraries cannot be loaded from inside a zipped `.love` archive. For distribution, ship platform builds (fused or not) with the correct native library file next to the executable/app bundle and load it via an absolute path.