|
| 1 | +# Use the data |
| 2 | + |
| 3 | +The catalog is published as machine-readable files on every deploy. The metadata is CC0: copy it, bundle it or build on it without asking. The assets it links to keep their own licences. |
| 4 | + |
| 5 | +> The licence facts are the catalog's reading of each source on the entry's `verified` date, not legal advice and not a guarantee that the terms are still the same. Re-check the source before you ship on one. |
| 6 | +
|
| 7 | +## Files |
| 8 | + |
| 9 | +| File | What it is | |
| 10 | +| --- | --- | |
| 11 | +| [`data.json`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/data.json) | The whole catalog: every entry with its licence fields, plus categories, guides and counts | |
| 12 | +| [`catalog.csv`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/catalog.csv) | One row per entry, for spreadsheets. Lists are joined with `; ` | |
| 13 | +| [`feed.xml`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/feed.xml) | Atom feed of newly added sources | |
| 14 | +| [`reverified.xml`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/reverified.xml) | Atom feed of entries whose licence was most recently re-read | |
| 15 | +| [`llms.txt`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/llms.txt) | A plain-text summary for language-model tools | |
| 16 | + |
| 17 | +These URLs always serve the latest build. To pin a version, download the same files from a tagged [release](https://github.com/TMHSDigital/Free-Game-Dev-Assets/releases). Releases are tagged `vYYYY.MM.DD`, and the attached `data.json` carries the same string as `version`. |
| 18 | + |
| 19 | +## Fields |
| 20 | + |
| 21 | +Each entry in `data.json` has these fields. `catalog.csv` has the ones marked CSV. |
| 22 | + |
| 23 | +| Field | CSV | Meaning | |
| 24 | +| --- | --- | --- | |
| 25 | +| `id` | yes | Short kebab-case id, unique across the catalog | |
| 26 | +| `name` | yes | Display name | |
| 27 | +| `url` | yes | The source's own page | |
| 28 | +| `category` | yes | One of the ten category folders, such as `3d`, `audio` or `tools` | |
| 29 | +| `subcategories` | yes | Finer grouping within the category | |
| 30 | +| `license` | yes | The licence as the catalog reads it. A value from [the vocabulary](../site/license-vocabulary.json), explained in [licenses.md](licenses.md) | |
| 31 | +| `license_spdx` | yes | SPDX identifier, where one fits | |
| 32 | +| `commercial` | yes | `true`, `false`, `varies` (per file) or `unknown` | |
| 33 | +| `attribution_required` | yes | `true`, `false` or `unknown` | |
| 34 | +| `attribution_string` | yes | The credit line as the source words it, where it gives one | |
| 35 | +| `publisher` | yes | Who publishes the source, where recorded | |
| 36 | +| `formats`, `tags` | yes | File formats and search tags | |
| 37 | +| `added` | yes | Date the entry joined the catalog | |
| 38 | +| `verified` | yes | Date the licence was last read at the source. A read date, not a validity date | |
| 39 | +| `status` | yes | `active`, `needs-review` (an open question, read the Notes) or `deprecated` | |
| 40 | +| `page` | yes | The entry's page on the site | |
| 41 | +| `summary` | | The first paragraph of the entry | |
| 42 | +| `path` | | The entry's file in this repository | |
| 43 | +| `thumb` | | `{ path, width, height, credit? }` of the preview image, or `null` | |
| 44 | +| `licenseFamily` | | Coarse grouping used by the site's filter: `public-domain`, `cc-by`, `permissive`, `copyleft`, `custom` and so on. Labels are in `filters.licenseFamilies` | |
| 45 | +| `attributionClass`, `licenseRank` | | Derived sort keys used by the site | |
| 46 | +| `engine_lock`, `grid_dimensions`, `camera_perspective` and other optional fields | | Present only where they apply; see [the site README](../site/README.md) | |
| 47 | + |
| 48 | +Top-level keys are `generatedAt`, `version`, `site`, `categories`, `guides`, `featured`, `stats` (counts of total, active, needs-review, deprecated and commercial entries), `filters` and `entries`. |
| 49 | + |
| 50 | +Field names are stable. New optional fields may appear, so ignore keys you do not know rather than failing on them. |
| 51 | + |
| 52 | +## Examples |
| 53 | + |
| 54 | +All CC0 audio that needs no credit, with `jq`: |
| 55 | + |
| 56 | +```sh |
| 57 | +curl -s https://tmhsdigital.github.io/Free-Game-Dev-Assets/data.json \ |
| 58 | + | jq -r '.entries[] | select(.category=="audio" and .license=="CC0" and .attribution_required==false and .status=="active") | "\(.name)\t\(.url)"' |
| 59 | +``` |
| 60 | + |
| 61 | +Everything usable commercially, as a table, with pandas: |
| 62 | + |
| 63 | +```python |
| 64 | +import pandas as pd |
| 65 | +df = pd.read_csv("https://tmhsdigital.github.io/Free-Game-Dev-Assets/catalog.csv") |
| 66 | +ok = df[(df.status == "active") & (df.commercial.astype(str).str.lower() == "true")] |
| 67 | +print(ok[["name", "license", "attribution_required", "attribution_string", "url"]]) |
| 68 | +``` |
| 69 | + |
| 70 | +Follow new sources in any feed reader by subscribing to `https://tmhsdigital.github.io/Free-Game-Dev-Assets/feed.xml`. |
| 71 | + |
| 72 | +## How to cite |
| 73 | + |
| 74 | +The repository has a [`CITATION.cff`](../CITATION.cff), and GitHub's "Cite this repository" button renders it. In text: |
| 75 | + |
| 76 | +> TMHSDigital. *Free Game Dev Assets: a dated, sourced catalog of free game assets and tools with licence metadata* (version vYYYY.MM.DD) [Data set]. https://github.com/TMHSDigital/Free-Game-Dev-Assets |
| 77 | +
|
| 78 | +```bibtex |
| 79 | +@misc{free_game_dev_assets, |
| 80 | + author = {TMHSDigital}, |
| 81 | + title = {Free Game Dev Assets: a dated, sourced catalog of free game assets and tools with licence metadata}, |
| 82 | + howpublished = {\url{https://github.com/TMHSDigital/Free-Game-Dev-Assets}}, |
| 83 | + note = {Dataset, version vYYYY.MM.DD}, |
| 84 | + license = {CC0-1.0} |
| 85 | +} |
| 86 | +``` |
| 87 | + |
| 88 | +Replace `vYYYY.MM.DD` with the release you used. |
0 commit comments