diff --git a/CLAUDE.md b/CLAUDE.md index 9f7a474..5feaba0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -68,6 +68,8 @@ continuity. | `make effects-captures` | Renders the visual effects (A7): a shot striking a player over the shoulder with the HUD's hit marker, a keg blast beside a collapsing wall, build dust, chips and a splash, and 24 players firing with kegs going off at the largest particle budget (`captures/effects_*.png`, about 6 min). Needs Docker. Look at them. | | `make audio` | Regenerates every sound and the score's layers in `assets/audio/` from `tools/audio/` (about 6 s), with `manifest.json`. Commit the WAVs it changes. | | `make audio-check` | Checks each file in `assets/audio/` matches its manifest hash and its loudness target, and the mix order (tide loudest). Also run by `test_audio_assets`, which regenerates everything and compares. | +| `make qa-captures` | H6: renders every capture scenario and the HUD at 4K into `captures/qa/`, one container at a time (waits when memory is short), with contact sheets (about 40 min). Needs Docker. Judge each against [docs/VISUAL_QA.md](docs/VISUAL_QA.md). | +| `tools/godot.sh --script res://tools/provenance.gd` | R4: rewrites [docs/ASSET_PROVENANCE.md](docs/ASSET_PROVENANCE.md), tracing every file under `assets/` to its generator. A new kind of asset needs a rule in `tools/provenance.gd`; `test_asset_provenance` fails otherwise. | | `make capture-test` | Proves the capture harness works and rejects a blank frame. Needs Docker, so it isn't part of `make check`. | Run one group of tests with `tools/run_tests.sh --root=res://test/sim` or diff --git a/CREDITS.md b/CREDITS.md index 0f195da..eb19098 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -14,7 +14,8 @@ Contributors add themselves here. See [CONTRIBUTING.md](CONTRIBUTING.md). Every model, texture, icon, sound and piece of music is made by a script in this repository. Nothing is sampled, recorded, downloaded or taken from a third party. How -each file was made is recorded in [assets/PROVENANCE.md](assets/PROVENANCE.md). The +each kind of file is made is recorded in [assets/PROVENANCE.md](assets/PROVENANCE.md), and +every file is traced to its generator in [docs/ASSET_PROVENANCE.md](docs/ASSET_PROVENANCE.md). The music is an original tune written for Tidewall. Licence: CC BY-SA 4.0 ([LICENSE-ASSETS](LICENSE-ASSETS)). diff --git a/docs/ASSET_PROVENANCE.md b/docs/ASSET_PROVENANCE.md new file mode 100644 index 0000000..ea7a2d4 --- /dev/null +++ b/docs/ASSET_PROVENANCE.md @@ -0,0 +1,178 @@ +# Asset provenance, file by file + +Every file under `assets/` and where it comes from: the script in this repository that +generates it, or "written by hand" for an original source written for Tidewall. Nothing +is sampled, recorded, downloaded or taken from a third party. How each kind of asset is +made is described in [assets/PROVENANCE.md](../assets/PROVENANCE.md); the licence is +CC BY-SA 4.0 ([LICENSE-ASSETS](../LICENSE-ASSETS)). + +Code-built art (terrain, sea, points of interest, props, build pieces, the barge, sea +chests and effects) isn't a file here: it's drawn by the scripts under `src/client/`. + +This file is written by `tools/godot.sh --script res://tools/provenance.gd`, and +`test/test_asset_provenance.gd` fails if it falls out of date or a file has no source. + +| File | Source | What it is | +|---|---|---| +| `assets/PROVENANCE.md` | written by hand | The summary of how each kind of asset is made. | +| `assets/audio/amb_rain.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/amb_surf.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/amb_wind.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/bell.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/break_driftwood.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/break_salvage_iron.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/break_stone.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/build_driftwood.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/build_salvage_iron.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/build_stone.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/chest_open.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/chop.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/eliminated.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/foghorn.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/hit_ground.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/hit_iron.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/hit_player.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/hit_stone.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/hit_wood.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/hurt.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/keg_blast.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/land.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/lighthouse.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/manifest.json` | `tools/audio/generate.gd` | Each sound's category, length, SHA-256, peak and loudness, written as the sounds are baked. | +| `assets/audio/music_concertina.wav` | `tools/audio/score.gd` | A layer of the original score: note lists written for Tidewall, synthesized by tools/audio/dsp.gd. | +| `assets/audio/music_drone.wav` | `tools/audio/score.gd` | A layer of the original score: note lists written for Tidewall, synthesized by tools/audio/dsp.gd. | +| `assets/audio/music_drum.wav` | `tools/audio/score.gd` | A layer of the original score: note lists written for Tidewall, synthesized by tools/audio/dsp.gd. | +| `assets/audio/music_fiddle.wav` | `tools/audio/score.gd` | A layer of the original score: note lists written for Tidewall, synthesized by tools/audio/dsp.gd. | +| `assets/audio/pickup.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/reload.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/shot_dock_carbine.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/shot_fowling_piece.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/shot_harpoon_gun.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/shot_line_thrower.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/shot_rivet_repeater.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/shot_signal_revolver.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/shot_whalers_longgun.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/splash.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_grass_1.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_grass_2.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_rock_1.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_rock_2.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_sand_1.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_sand_2.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_shallows_1.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_shallows_2.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_wood_1.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/step_wood_2.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/surge.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/swim.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/swing_boathook.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/ui_back.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/ui_click.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/ui_confirm.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/audio/ui_hover.wav` | `tools/audio/recipes.gd` | Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd). | +| `assets/icons/app/tidewall-128.png` | `tools/app_icon.gd` | The hand-written SVG rasterised by the engine's SVG loader. | +| `assets/icons/app/tidewall-16.png` | `tools/app_icon.gd` | The hand-written SVG rasterised by the engine's SVG loader. | +| `assets/icons/app/tidewall-24.png` | `tools/app_icon.gd` | The hand-written SVG rasterised by the engine's SVG loader. | +| `assets/icons/app/tidewall-256.png` | `tools/app_icon.gd` | The hand-written SVG rasterised by the engine's SVG loader. | +| `assets/icons/app/tidewall-32.png` | `tools/app_icon.gd` | The hand-written SVG rasterised by the engine's SVG loader. | +| `assets/icons/app/tidewall-48.png` | `tools/app_icon.gd` | The hand-written SVG rasterised by the engine's SVG loader. | +| `assets/icons/app/tidewall-512.png` | `tools/app_icon.gd` | The hand-written SVG rasterised by the engine's SVG loader. | +| `assets/icons/app/tidewall-64.png` | `tools/app_icon.gd` | The hand-written SVG rasterised by the engine's SVG loader. | +| `assets/icons/app/tidewall.svg` | written by hand | The application icon, an SVG written for Tidewall in Palette colours. | +| `assets/icons/items/birdshot.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/boathook.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/brine_tonic.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/cartridges.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/cork_vest.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/dock_carbine.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/fowling_piece.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/harpoon_gun.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/harpoons.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/heavy_balls.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/line_thrower.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/lines.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/powder_keg.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/rivet_repeater.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/sailcloth_bandage.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/signal_revolver.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/tar_patch.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/icons/items/whalers_longgun.png` | `tools/models/items.py` | The item's model rendered with Cycles on the CPU in headless Blender. | +| `assets/models/figure/figure.json` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/forearm_l.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/forearm_l.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/forearm_r.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/forearm_r.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/head.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/head.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/pelvis.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/pelvis.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/sail.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/sail.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/shin_l.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/shin_l.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/shin_r.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/shin_r.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/thigh_l.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/thigh_l.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/thigh_r.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/thigh_r.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/torso.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/torso.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/upper_arm_l.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/upper_arm_l.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/upper_arm_r.mtl` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/figure/upper_arm_r.obj` | `tools/models/figure.py` | A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender. | +| `assets/models/items/birdshot.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/birdshot.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/birdshot.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/boathook.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/boathook.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/boathook.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/brine_tonic.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/brine_tonic.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/brine_tonic.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/cartridges.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/cartridges.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/cartridges.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/cork_vest.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/cork_vest.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/cork_vest.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/dock_carbine.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/dock_carbine.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/dock_carbine.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/fowling_piece.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/fowling_piece.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/fowling_piece.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/harpoon_gun.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/harpoon_gun.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/harpoon_gun.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/harpoons.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/harpoons.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/harpoons.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/heavy_balls.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/heavy_balls.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/heavy_balls.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/line_thrower.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/line_thrower.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/line_thrower.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/lines.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/lines.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/lines.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/powder_keg.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/powder_keg.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/powder_keg.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/rivet_repeater.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/rivet_repeater.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/rivet_repeater.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/sailcloth_bandage.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/sailcloth_bandage.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/sailcloth_bandage.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/signal_revolver.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/signal_revolver.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/signal_revolver.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/tar_patch.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/tar_patch.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/tar_patch.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/whalers_longgun.json` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/whalers_longgun.mtl` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | +| `assets/models/items/whalers_longgun.obj` | `tools/models/items.py` | An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender. | diff --git a/test/test_asset_provenance.gd b/test/test_asset_provenance.gd new file mode 100644 index 0000000..5d4aa13 --- /dev/null +++ b/test/test_asset_provenance.gd @@ -0,0 +1,23 @@ +extends TestCase + +## R4: every file under assets/ is traced to a generating script in this repository or +## to an original hand-written source, and docs/ASSET_PROVENANCE.md lists them all. + +const Provenance = preload("res://tools/provenance.gd") + + +func test_every_asset_has_a_source_that_exists() -> void: + var rows: Array[Array] = Provenance.rows() + assert_true(rows.size() > 100, "assets/ was read (%d files)" % rows.size()) + var found: Array[String] = Provenance.problems_with(rows) + assert_eq(found, [] as Array[String], "\n".join(found)) + + +func test_the_document_is_up_to_date() -> void: + var written: String = FileAccess.get_file_as_string(Provenance.DOC) + assert_eq(written, Provenance.render(), "regenerate with: tools/godot.sh --script res://tools/provenance.gd") + + +func test_an_unknown_file_is_caught() -> void: + var table: Array[Array] = [["audio/sample_pack.wav", "", ""], ["models/items/x.obj", "tools/models/nowhere.py", ""]] + assert_eq(Provenance.problems_with(table).size(), 2) diff --git a/test/test_asset_provenance.gd.uid b/test/test_asset_provenance.gd.uid new file mode 100644 index 0000000..bc7af0a --- /dev/null +++ b/test/test_asset_provenance.gd.uid @@ -0,0 +1 @@ +uid://6mvjs0qd6apg diff --git a/tools/deb.sh b/tools/deb.sh index 0377ece..7c58a94 100755 --- a/tools/deb.sh +++ b/tools/deb.sh @@ -54,6 +54,7 @@ install -m 0644 packaging/deb/copyright "$doc/copyright" install -m 0644 packaging/dist/README.md "$doc/README.md" install -m 0644 "$package/server.cfg" "$doc/examples/server.cfg" gzip -9n -c "$package/PROVENANCE.md" >"$doc/PROVENANCE.md.gz" +gzip -9n -c "$package/ASSET_PROVENANCE.md" >"$doc/ASSET_PROVENANCE.md.gz" gzip -9n -c "$package/ENGINE-LICENSES.txt" >"$doc/ENGINE-LICENSES.gz" { printf 'tidewall (%s) unstable; urgency=medium\n\n' "$debversion" diff --git a/tools/dist.sh b/tools/dist.sh index 2746338..92727e9 100755 --- a/tools/dist.sh +++ b/tools/dist.sh @@ -20,7 +20,7 @@ # tidewall.png the application icon # server.cfg an example server configuration # ENGINE-LICENSES.txt the Godot engine's licence and its third-party notices -# LICENSE, LICENSE-ASSETS, README.md, PROVENANCE.md, VERSION +# LICENSE, LICENSE-ASSETS, README.md, PROVENANCE.md, ASSET_PROVENANCE.md, VERSION set -euo pipefail repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" @@ -87,6 +87,7 @@ install -m 0644 LICENSE LICENSE-ASSETS "$package/" install -m 0644 packaging/server/server.cfg "$package/server.cfg" install -m 0644 packaging/dist/README.md "$package/README.md" install -m 0644 assets/PROVENANCE.md "$package/PROVENANCE.md" +install -m 0644 docs/ASSET_PROVENANCE.md "$package/ASSET_PROVENANCE.md" install -m 0755 packaging/dist/tidewall "$package/tidewall" install -m 0755 packaging/dist/install-desktop-entry.sh "$package/install-desktop-entry.sh" install -m 0644 assets/icons/app/tidewall-256.png "$package/tidewall.png" diff --git a/tools/dist_check.sh b/tools/dist_check.sh index d2f8436..6c47f49 100755 --- a/tools/dist_check.sh +++ b/tools/dist_check.sh @@ -37,7 +37,7 @@ package="$work/$name" export HOME="$work/home" XDG_DATA_HOME="$work/home/data" XDG_CONFIG_HOME="$work/home/config" XDG_CACHE_HOME="$work/home/cache" XDG_STATE_HOME="$work/home/state" mkdir -p "$HOME" -expected="ENGINE-LICENSES.txt LICENSE LICENSE-ASSETS PROVENANCE.md README.md VERSION install-desktop-entry.sh server.cfg tidewall tidewall-server tidewall.pck tidewall.png tidewall.x86_64" +expected="ASSET_PROVENANCE.md ENGINE-LICENSES.txt LICENSE LICENSE-ASSETS PROVENANCE.md README.md VERSION install-desktop-entry.sh server.cfg tidewall tidewall-server tidewall.pck tidewall.png tidewall.x86_64" actual="$(cd "$package" && ls -A | LC_ALL=C sort | tr '\n' ' ' | sed 's/ $//')" [[ "$actual" == "$expected" ]] || fail "the package holds '$actual', expected '$expected'" version="$(sed -n 's/^Tidewall //p' "$package/VERSION")" diff --git a/tools/provenance.gd b/tools/provenance.gd new file mode 100644 index 0000000..0cf74ee --- /dev/null +++ b/tools/provenance.gd @@ -0,0 +1,100 @@ +## R4: traces every file under assets/ to the script that makes it, or to its original +## hand-written source, and writes the per-file table in docs/ASSET_PROVENANCE.md. +## `test_asset_provenance` fails if a file has no rule, a rule names a generator that +## doesn't exist, or the document is out of date. +## tools/godot.sh --script res://tools/provenance.gd +extends SceneTree + +const ASSETS: String = "res://assets" +const DOC: String = "res://docs/ASSET_PROVENANCE.md" + +## Path pattern (relative to assets/, `*` wildcards) -> [source, how]. First match wins. +const RULES: Array[Array] = [ + ["PROVENANCE.md", "written by hand", "The summary of how each kind of asset is made."], + ["audio/manifest.json", "tools/audio/generate.gd", "Each sound's category, length, SHA-256, peak and loudness, written as the sounds are baked."], + ["audio/music_*.wav", "tools/audio/score.gd", "A layer of the original score: note lists written for Tidewall, synthesized by tools/audio/dsp.gd."], + ["audio/*.wav", "tools/audio/recipes.gd", "Synthesized from seeded noise, oscillators, filters and decaying modes (tools/audio/dsp.gd)."], + ["models/items/*", "tools/models/items.py", "An item model (OBJ and MTL) and its grip data (JSON), built from primitives in headless Blender."], + ["icons/items/*.png", "tools/models/items.py", "The item's model rendered with Cycles on the CPU in headless Blender."], + ["models/figure/*", "tools/models/figure.py", "A part of the player figure (OBJ and MTL) or its joint data (JSON), built from primitives in headless Blender."], + ["icons/app/tidewall.svg", "written by hand", "The application icon, an SVG written for Tidewall in Palette colours."], + ["icons/app/tidewall-*.png", "tools/app_icon.gd", "The hand-written SVG rasterised by the engine's SVG loader."], +] + +const HEADER: String = """# Asset provenance, file by file + +Every file under `assets/` and where it comes from: the script in this repository that +generates it, or "written by hand" for an original source written for Tidewall. Nothing +is sampled, recorded, downloaded or taken from a third party. How each kind of asset is +made is described in [assets/PROVENANCE.md](../assets/PROVENANCE.md); the licence is +CC BY-SA 4.0 ([LICENSE-ASSETS](../LICENSE-ASSETS)). + +Code-built art (terrain, sea, points of interest, props, build pieces, the barge, sea +chests and effects) isn't a file here: it's drawn by the scripts under `src/client/`. + +This file is written by `tools/godot.sh --script res://tools/provenance.gd`, and +`test/test_asset_provenance.gd` fails if it falls out of date or a file has no source. + +| File | Source | What it is | +|---|---|---| +""" + + +func _init() -> void: + var problems: Array[String] = problems_with(rows()) + if not problems.is_empty(): + for problem: String in problems: + push_error(problem) + quit(1) + return + var file: FileAccess = FileAccess.open(DOC, FileAccess.WRITE) + file.store_string(render()) + file.close() + print("asset provenance: %d files in %s" % [rows().size(), DOC]) + quit(0) + + +## Every file under assets/, sorted, without the engine's .import and .uid sidecars. +static func files(dir: String = ASSETS, prefix: String = "") -> Array[String]: + var found: Array[String] = [] + for name: String in DirAccess.get_files_at(dir): + if name.ends_with(".import") or name.ends_with(".uid"): + continue + found.append(prefix + name) + for sub: String in DirAccess.get_directories_at(dir): + found.append_array(files(dir.path_join(sub), prefix + sub + "/")) + found.sort() + return found + + +## [path, source, how] for each file, with an empty source where no rule matches. +static func rows() -> Array[Array]: + var out: Array[Array] = [] + for path: String in files(): + var row: Array = [path, "", ""] + for rule: Array in RULES: + if path.match(rule[0]): + row = [path, rule[1], rule[2]] + break + out.append(row) + return out + + +static func problems_with(table: Array[Array]) -> Array[String]: + var found: Array[String] = [] + for row: Array in table: + var source: String = row[1] + if source.is_empty(): + found.append("assets/%s: no recorded source; add a rule to tools/provenance.gd" % row[0]) + elif source != "written by hand" and not FileAccess.file_exists("res://" + source): + found.append("assets/%s: its generator %s doesn't exist" % [row[0], source]) + return found + + +static func render() -> String: + var lines: Array[String] = [] + for row: Array in rows(): + var source: String = row[1] + var shown: String = source if source == "written by hand" else "`%s`" % source + lines.append("| `assets/%s` | %s | %s |" % [row[0], shown, row[2]]) + return HEADER + "\n".join(lines) + "\n" diff --git a/tools/provenance.gd.uid b/tools/provenance.gd.uid new file mode 100644 index 0000000..b03dd0a --- /dev/null +++ b/tools/provenance.gd.uid @@ -0,0 +1 @@ +uid://bj441upyje41c