Tilesets¶
Tilesets map game IDs and variants to sprites and tilesheets. Runtime loading, composition, package metadata, ID fallback, rotations, multitile/connect rules, overlays, and licensing are all part of the contract.
Authoritative paths¶
doc/TILESET.mddescribes the supported tile JSON concepts and composition model.gfx/contains bundled tileset metadata and assets;gfx/tile_config_template.jsonis a starting shape, not a substitute for a real load.src/sdltiles.*and the tile loader define runtime behavior..github/workflows/compose-tilesets.ymldefines checked composition and distributable assets.
Ownership and IDs¶
Game JSON owns entity IDs. A tile entry references those IDs and may add variants, rotations, multitile pieces, seasonal/gender forms, overlays, or fallback. Renaming a game ID without coordinating tiles can silently degrade to fallback art even when JSON still loads.
Contributor workflow¶
Keep source sprites, tile entry JSON, tilesheet metadata, and license/attribution together. Compose with the workflow/tool used by the repository, review its warnings, then launch the result in a tiles build. Do not edit a generated tilesheet when the compositing source is the maintained input.
Validation¶
Validate JSON/composition, missing and duplicate IDs, sprite bounds, fallback behavior, rotations/connections, overlays, zoom/scaling, both map and overmap views, and a clean packaged load. Sample changed IDs in game; composition success alone cannot prove visual correctness.
Performance and packaging¶
Atlas dimensions, texture count, fallback chains, and repeated variant lookup affect startup, memory, and redraw. Keep generated sheets and source art roles explicit. Large composed output can be a release/CI artifact when the repository workflow treats it as generated.
Licensing¶
Every imported sprite needs compatible licensing and attribution. “From an upstream tileset” is not sufficient provenance: record source repository/path, author where available, license, and transformation.