New Contributor Guide Sprite

Adding a new sprite

A sprite is an image representing an entity or concept in the game. Some sprites are "overlays", meaning they are drawn on top of another sprite to represent a change in the underlying sprite. Worn clothing, wielded weapons, mutations, and status effects like being blinded or running use overlay sprites on top of a character sprite. The things that can have sprites are: monsters, monster corpses, items, vehicle parts, terrain or furniture, the player character and NPCs, wielded items and worn clothing, overlays for mutations and CBMs, overlays for effects on creatures, and special effects like weather, projectiles, explosions, etc. Some entities will have multiple sprites, such as an item's base sprite, the overlay sprite for wearing the item, and a different overlay sprite for wielding the item.

Most tilesets currently included with the game are managed by I-am_Erk's CDDA tileset repo. If you want to contribute one or several new sprites you will need to make a Pull Request there. If you don't want to deal with github, you can go to the Ultica Discord and upload your sprite there; someone will review it and include it in the tileset. BrownLikeBears, MShockXotto+,Neodays, Retrodays and Ultica are all hosted on I-am_Erk's CDDA tileset repo in their decomposed form, ie as a collection of individual sprite with their respective json files. Decomposed tilesets can't be used in the game until they are composed (see below), but they're easy to edit, update, and store.

Sprites need to be appropriately sized for their tileset. Each tileset has one or more preferred sprite sizes, ranging from as little as 20x20 pixels to as large as the tileset designer likes (UltiCa has some 128x64 pixel sprites, for instance). If you plan to submit sprites for an existing tileset, contact the tileset owner to get details on the sprite size.

To add a new sprite to a decomposed tileset you need the sprite as a .png and a .json file which is basically a text file containing the information about what the sprite is supposed to represent in game.

Example

BrownLikeBears uses 20x20 pixel sprites.

To add a new monster to BrownLikeBears, you would make a 20x20 sprite of your new monster with a name like new_monster.png (png names are arbitrary, just make it something easy to remember) and a JSON file with a name like new_monster.json containing some information about the sprite will be used to represent a game entity.

{
    "id": "mon_cat",      // the `id` of the game entity represented by this sprite
    "fg": "new_monster",  // the name of the sprite file that will be displayed at the foreground.  The .png is assumed
    "bg": "shadow_bg_1",  // (Optional) the name of the sprite file that will be displayed at the background.  The .png is assumed
    "rotates": false      // true for things that rotate like vehicle parts
}

For simplicity's sake, it is possible to skip making a json file and directly name the .png file with the id of the entity they represent. So in this example it would be mon_cat.png instead of new_monster.png. For more details on json syntax for sprites see tile_entry in TILESET.md

Adding a new tileset

To build an entirely new tileset you should use our python script compose.py to compose a tileset from a collection of individual sprites. The compose.py script reads the directories of sprite images and JSON metadata, condenses the sprites into tilesheets, and then writes a complicated JSON meta-data file for the entire tileset that the CDDA tileset loader can use. CDDA references sprites by linear offset within a tilesheet, and while it is possible to calculate the offsets by hand, it's difficult and tedious. The compose.py automates that process, so please use it.

A list of most game entities that can take sprites is at The UltiCa sprite progress spreadsheet. Make a copy of the spreadsheet and use it to track your progress. Be forewarned that CDDA has something more than 10,000 spriteable entities, UltiCa has had teams of multiple contributors working on it for a year and a half, and UltiCa is still noticeably missing sprites. Starting a new tileset from scratch is an extremely labor intensive task.

For more detailed information on making tilesets, see TILESET.md