The engine: the folder, sound and the profile store
What is in the folder
| Path | What it is |
|---|---|
src/paraloop/ |
the engine: sim loop, rules glue, renderer, input, audio, save, the web shell |
template/ |
the skeleton para new copies into games/<name>/ |
games/ |
your games, one folder and one git repository each |
examples/hello/ |
the small game the engine's own tests and the web smoke test use |
tools/para/ |
the para CLI; tools/art/ the pixel-art cleanup; tools/web/ the wasm build and smoke test; tools/docs/ this documentation site |
.agents/skills/ |
the producer's playbook and its helpers (builder, checker, scout, art) |
skills/ |
para and pararules skills an agent can install |
Working on the engine
tmp/para test --filter test_audio # only the test files whose path contains that text
tmp/para test --area game # the game tests, plus the `para` tests that link a game
tmp/para build --game hello # compile a game natively, with structured errors
tmp/para sim --game hello --seed 7 --ticks 3600 # headless run: state, perf, state hash
A bare tmp/para test runs everything (about ten minutes from a cold cache); testing.md
says when to use which. Engine rules (pararules habits, what a game's rules.nim may import) are in AGENTS.md.
Sound
paraloop/audio is the engine's sound module, on native and on the web. A sound is
a recipe: a few synth tones (wave, start/length in ms, MIDI pitch with an optional
glide, gain, envelope) that rendering turns into 16-bit PCM, handed to a backend --
the same synthesise-at-startup, one-sound-per-effect shape parasurvivors uses, with a
tiny synth in place of paramidi and its 31 MB soundfont, so a render is exact and
reproducible and unit-testable.
initAudio(backend, recipes, master)renders every recipe;play(slot, volume),setMaster,setMuted/toggleMute,shutdown.Audio()(no backend) is the silent player, andNullBackendrecords plays for tests: nothing inpara test,para simorpara shotever opens a device -- only a game's own entry point does, by importingparaloop/audio_deviceunderwhen isMainModuleand passingopenDevice()(nil when there is no output device) toinitAudio.- A
Backendgets each rendered recipe once, as PCM (load(slot, pcm, rate): monoint16samples and their sample rate), thenplay,setMasterandclose. Throttle/pickrate-limit cues deterministically in sim ticks (a per-effect gap and a cap on voices per observation), never the wall clock.- A game keeps its effects as rows (a
sfxdata.nimof its own) and decides what to play from facts after the fact (ansfx.nim, called fromdraw): it reads the sim and never writes it, so a run'sstateHashis the same with or without sound.
A melody is easier to write as a line of text than as tone calls: tune in
paraloop/tune turns a small score into seq[Tone] -- notes c d e f g a b with +/-,
rests r, lengths that stick (c8), o4/>/< octaves and c/e/g chords -- and runs at
compile time, so it fits a const row. It is a notation over the tone synth, not a music
engine (no instruments, voices or repeats), and a bad character raises ValueError naming
its position. The notation is in the header of src/paraloop/tune.nim.
import paraloop/[audio, tune]
const levelUp = Recipe(name: "level_up", tones: tune("o5 c16 e g >c", Square))
# c5 e5 g5 c6 as 125 ms sixteenths at the default tempo of 120 quarter notes a minute;
# `tempo = ` and `gain = ` change the speed and the loudness
Backends (openDevice() picks one at compile time):
- Native: miniaudio through
parasound(already a dependency); it loads the system's ALSA/PulseAudio/PipeWire at run time, so building needs no extra system package.PARALOOP_AUDIO=offnever opens a device. - Web (
-d:emscripten): Web Audio.src/paraloop/audio_web.nimis a thin Nim shell oversrc/paraloop/web/audio.js, whichtools/web/build.shlinks into the wasm with--pre-js(a web build compiled any other way has noModule.psAudioand is silent rather than broken). Each recipe becomes oneAudioBufferat startup and the browser mixes on its own audio thread: no threads, noSharedArrayBuffer, no special hosting headers, about 2 KB of wasm. -d:noaudioleaves the device out of the build entirely (openDevice()is nil).
The unlock rule (web). Browsers keep audio locked until the page has seen a user
gesture, so the context starts suspended and the first keydown, pointerdown or
touchend resumes it. A sound requested before that is dropped, not queued -- a burst
replayed at the first key press would be noise -- so a game that wants its first sound
heard plays it in response to input (a title screen's Enter, a start button), not at
load. A keyboard-only player hears sound after their first key press. para web smoke --sound checks this for a game that beeps on ArrowRight (see web.md).
Config: PARALOOP_VOLUME=NN (percent, run time, native) overrides a game's master
volume and PARALOOP_AUDIO=off never opens a device. A game's mute key and any
compile-time volume define are the game's own.
Profile store (paraloop/save)
paraloop/save keeps the progress a game carries between runs as one versioned JSON
file in the OS data directory. It is game-agnostic: the engine reads and writes the
envelope {"version": N, "game": "<id>", "payload": {...}} and never looks inside the
payload; the game owns its fields, its version number and its migrations.
- Path:
profilePath(game)is<data home>/paraloop/<game>/profile.json; the data home is$XDG_DATA_HOME(an absolute path, else~/.local/share) on Linux,~/Library/Application Supporton macOS and%APPDATA%on Windows. loadProfile(path, game, version, migrations)never raises and never writes. ItsLoadResult.statusislsOk,lsMissing,lsCorrupt,lsWrongGame,lsNewerorlsUnavailable; an older file is migrated one version at a time throughmigrations((fromVersion, proc (payload): payload)entries, N -> N + 1).saveProfile(path, game, version, payload)writes a temp file beside the target and renames it over, so a failure leaves the old file whole. A corrupt, another game's, newer or older (pre-migration) file it is about to replace is copied toprofile.json.bakfirst.- The web target is a stub (every call reports it is unavailable) until browser storage lands.