From 20dd6bc502d23859d9914330edd984c64f8a2ee6 Mon Sep 17 00:00:00 2001 From: claude Date: Thu, 3 Sep 2026 23:24:54 +0200 Subject: [PATCH] Keep asset packs out of git and out of Godot's importer The packs total 3.9GB, almost all of it Helton Yan's SFX shipped as 24-bit / 96kHz studio masters -- ~2MB for a single gunshot. Two guards, because they solve different problems: - .gitignore excludes the contents. The directory and its guard files stay tracked, so a fresh clone has the .gdignore in place before anyone drops packs back in. - assetpacks/.gdignore stops Godot descending into the tree at all. This is the urgent half: tools/check.sh runs --import, which walks all of res://, so the next check would have imported several thousand PNGs and 2,100 of those WAVs, and every run after it. Verified by controlled test rather than assumed -- an unguarded PNG under res:// imports and gets a .import file beside it; with .gdignore neither happens. check.sh stays at 3.3s and .godot/imported at 1.2MB. The trade the .gdignore buys is that nothing in assetpacks/ can be referenced from a scene or script. That is the intended shape: raw source on one side, game-ready files copied into res://assets/ on the other, so adding a huge pack costs the repo and the import step nothing. docs/ASSETS.md records attribution, because gitignoring the packs also gitignores their licence files. Worth flagging: four of the six packs shipped with no licence text at all, and two of the undecided ones are demo versions, which are often more restricted than the paid packs. Only RF Catacombs has explicit terms (public domain, no resale). Those rows need a source URL before anything ships. Also removed __MACOSX and .DS_Store extraction artefacts, and left considering_dont_use_yet/ untouched as the user's own "not chosen" marker. --- .gitignore | 9 ++++++++ assetpacks/.gdignore | 0 assetpacks/README.md | 32 ++++++++++++++++++++++++++ assets/README.md | 17 ++++++++++++++ docs/ASSETS.md | 54 ++++++++++++++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 3 +++ 6 files changed, 115 insertions(+) create mode 100644 assetpacks/.gdignore create mode 100644 assetpacks/README.md create mode 100644 assets/README.md create mode 100644 docs/ASSETS.md diff --git a/.gitignore b/.gitignore index c318b1c..d0bf673 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,14 @@ # Godot's import cache and editor state. Regenerated by `godot --import`. .godot/ +# Raw asset packs: gigabytes of source artwork and audio. Redistributable +# third-party material belongs where it was bought or downloaded, not in a code +# repo. The directory itself and its guards stay tracked, so a fresh clone has +# the .gdignore in place before anyone drops packs back in -- without it the +# next `tools/check.sh` tries to import the lot. +/assetpacks/* +!/assetpacks/.gdignore +!/assetpacks/README.md + # Export artefacts. build/ *.pck diff --git a/assetpacks/.gdignore b/assetpacks/.gdignore new file mode 100644 index 0000000..e69de29 diff --git a/assetpacks/README.md b/assetpacks/README.md new file mode 100644 index 0000000..fef3ce3 --- /dev/null +++ b/assetpacks/README.md @@ -0,0 +1,32 @@ +# Raw asset packs + +Source material as downloaded: unedited, uncropped, and mostly unused. **Not in +git** — this directory is gigabytes, and the contents are redistributable +artwork and audio that belong wherever you bought or downloaded them, not in a +code repository. Only this README and the `.gdignore` beside it are tracked, so +a fresh clone has the guard in place before anyone drops packs back in. + +## Why `.gdignore` + +Godot's importer walks everything under `res://`. Without the `.gdignore` here, +`tools/check.sh` — which runs `--import` — would try to import several thousand +PNGs and 2,100 studio-master WAVs on the next run, and every run after it. The +`.gdignore` makes the engine skip this tree entirely: nothing here is imported, +nothing lands in `.godot/imported/`, and nothing reaches an export. + +The cost of that is the point: **files here cannot be referenced from a scene or +script.** Godot does not know they exist. + +## Getting an asset into the game + +Copy the specific files you need into `res://assets/`, converted to something +game-ready first. That directory *is* imported and *is* committed, so it stays +small and every file in it is one the game actually uses. + +Audio in particular needs conversion. The Helton Yan pack is 24-bit / 96 kHz +stereo — studio masters, averaging ~2 MB for a single gunshot. Ship 16-bit / +44.1 kHz mono for SFX unless something specifically needs better. + +Attribution and licence status for every pack is recorded in +[docs/ASSETS.md](../docs/ASSETS.md). Keep it current — the licence files +themselves are not in git, because the packs are not. diff --git a/assets/README.md b/assets/README.md new file mode 100644 index 0000000..ec19961 --- /dev/null +++ b/assets/README.md @@ -0,0 +1,17 @@ +# Game-ready assets + +Assets the game actually references. Committed, imported by Godot, and expected +to stay small. + +Everything here should already be in its final form: cropped, atlased where it +helps, audio downsampled to something sane for a game. Raw packs live in +[`assetpacks/`](../assetpacks/README.md), which Godot ignores and git does not +track. + +The split exists so that adding a 3.9 GB pack of source material costs the +repository and the import step nothing, while the handful of files the game +loads stay reviewable. + +Nothing is here yet — the game currently draws itself from primitives and one +runtime-generated dot texture ([src/view/bullet_renderer.gd](../src/view/bullet_renderer.gd)). +Art is Stage 2 of [docs/ROADMAP.md](../docs/ROADMAP.md). diff --git a/docs/ASSETS.md b/docs/ASSETS.md new file mode 100644 index 0000000..9cafa6c --- /dev/null +++ b/docs/ASSETS.md @@ -0,0 +1,54 @@ +# Asset packs and attribution + +The packs themselves are **not in git** (see +[`assetpacks/README.md`](../assetpacks/README.md)), which means their bundled +licence files are not either. This file is the record that survives. Keep it +current when a pack is added or removed. + +## Why nothing is imported yet + +`assetpacks/` carries a `.gdignore`, so Godot skips it entirely. Nothing there +can be referenced from a scene or script until it is copied into +`res://assets/` in game-ready form. That is deliberate: the tree is 3.9 GB, and +`tools/check.sh` runs `--import`, which would otherwise walk all of it on every +run. + +## Packs + +| Pack | Size | Intended use | Licence | +| --- | --- | --- | --- | +| 0x72 Dungeon Tileset II v1.7 | 1.6 MB | Dungeon tiles — maps to the `MapGrid.Kind` tiles the generator already emits | **Unrecorded.** Bundled README is technical, not legal. Widely distributed as CC0 by Robert Norenberg (0x72), but confirm at the source before shipping. | +| Effect and FX Pixel All Free | 29 MB | Hit flashes, muzzle flashes, death effects | **Unrecorded** — no licence file in the pack. | +| Helton Yan's Pixel Combat | 3.9 GB | Combat SFX | **Unrecorded** — no licence file in the pack. | +| New All Fire Bullet Pixel 16x16 | 360 KB | Bullet sprites, to replace the generated dot in `bullet_renderer.gd` | **Unrecorded** — no licence file in the pack. | +| `considering_dont_use_yet/` — RF Catacombs v1.0 | part of 1.6 MB | Undecided | **Public domain**, per bundled `public-license.txt`. "Free to use, personal or commercial. Credit not required but appreciated. You can edit, but not resell the asset pack." Artwork by Szadi art. | +| `considering_dont_use_yet/` — Tiny RPG Character Pack 02, neo_zero v1.0 / 3.0 demo | part of 1.6 MB | Undecided | **Unrecorded.** | + +### Action needed before shipping anything + +Four of the six packs arrived with no licence text at all. Redistribution terms +for pixel-art and audio packs vary a lot — some free packs forbid commercial +use, some require credit, and "free demo" versions (two of the undecided packs +are demos) are often more restricted than the paid ones. + +Record the source URL and terms for each **Unrecorded** row above before any of +it goes into a build. The `considering_dont_use_yet/` packs are the user's own +"not chosen yet" marker; leave them there until that changes. + +## Converting audio before use + +Helton Yan's pack is 24-bit / 96 kHz stereo — studio masters, averaging ~2 MB +per file and 5 MB at the largest. That is roughly a hundred times what a game +needs for a gunshot. + +Downsample to 16-bit / 44.1 kHz mono before copying anything into +`res://assets/`. Godot imports `.wav` losslessly and keeps it in memory +uncompressed for low-latency playback, so the source format is what you pay for +in RAM and in export size. + +## Where converted assets go + +`res://assets/`, which is committed and imported. See +[`assets/README.md`](../assets/README.md). Art is Stage 2 in +[ROADMAP.md](ROADMAP.md); everything currently on screen is drawn from +primitives plus one runtime-generated dot texture. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 41a38ca..abb25e3 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -4,6 +4,9 @@ brief to its current state and the files that implement it, so you can find the relevant code without re-reading the whole project. +Art and audio source packs, and their licence status, are recorded in +[ASSETS.md](ASSETS.md) — the packs themselves are not in git. + Design decisions that are already settled — and the reasoning behind them — live in [DECISIONS.md](DECISIONS.md). Check there before asking the user something that may already have an answer.