Semi Format: Sprite Collection

Each sprite collection is defined by one file. The recommended extension is .semi.coll. The sprite collection must have a master spritesheet, ideally a PNG file. Overloading the spritesheet for certain definitions is supported by the format, but not yet supported by the actual loader, and will therefore not be shown here.

To use these in your mods, you would put the relevant files in your mod's resources folder, and then use the LoadSpriteCollection(string path) method to load them.

Format

The sprite collection format is line based, that is, every line is a separate instruction. Whitespace in this case means spaces and tabs.

There are two types of "instructions", which you can learn about below.

Properties

Properties are instructions that start with a $ (dollar symbol), then are immediately followed by the name of the property, then by whitespace, then by arguments. In other words, the basic property line looks like this:

$name <arg...>

The available properties are as follows:

• id <id> e.g. $id @:my_id (will load as my_mod:my_id if the mod's ID is my_mod) Specifies the ID to load this collection as. You can use a context ID like above to use your mod's namespace automatically. Required.

• name <name> e.g. $name Some name with spaces in it This will set the name of the TK2D collection object. The name is separate from the ID, and can be any arbitrary string, even including spaces.

• unit <w>x<h> e.g. $unit 2x2 The positions and sizes of sprite definitions are scaled by the unit before being set. By default, the unit is 1x1, meaning that position 1,2 will mean X = 1 and Y = 2 and size 32x32 will mean W = 32 and H = 32. If set to for example 2x2, it would set those values to X = 2, Y = 4, W = 64 and H = 64. This property has very niche usage.

• size <w>x<h> e.g. $size 32x32 The size property allows you to save on typing by setting the default size of a definition. See the description of the definition instruction below if you are confused about what "default" means.

• spritesheet <path to file> e.g. $spritesheet test.png Tells the loader which texture to load and set on this collection. Always a path relative to the collection metadata file. Required.

• attachpoint <name> <alias> e.g. $attachpoint PrimaryHand p Tells the loader that the game expects attach points with the name name in this collection, and allows you to use p to refer to it in definitions.

Example

$id my_coll
$name My Collection
$size 32x32

Definitions

A definition can be described like this:

name <pos> [size] [attribs...]

The first element (name) is what the sprite definition will be named. Note that custom sprite collections like these are ID pooled in Semi (see: ID Pools), and all the definitions will automatically be prefixed with your mod's namespace (its ID). In other words, using name in the name field of a mod with an ID test will result in a collection containing a definition called test:name. Gungeon collections don't work like this, but there is fully transparent backwards compatibility for that.

The second element is the X and Y origin position (top left corner), according to the specified unit (default 1x1). These values are in pixels.

From this point onwards, everything else is optional. The third element is the size of the region to cut out of the texture, also scaled by the unit. The rest is a list of attributes, without a particular enforced order, a list of which you can see here:

• fliph - The sprite will be flipped horizontally when rendering.

• flipv - The sprite will be flipped vertically when rendering.

• at <attachpoint> <tx> <ty> Adds an attach point with the specified alias and position (Note: currently, the positions are specified in texels. This is because attachpoints are a recent addition to the format and will be changed soon).

Example

def_1 0,0 32x32
def_2 32,0 32x32 flipw fliph

Full Example

$id test_gun_coll
$name TestGun Collection
$unit 1x1
$size 32x32
$spritesheet test_gun.png
$attachpoint p PrimaryHand

fire_1 5,5 26x11 at p 0.125 0.25 at s 0.8125 0.25 at cl 0.625 0.125 at c 0.5625 0.375
fire_2 41,5 26x11 at p 0.125 0.25 at s 0.8125 0.25 at cl 0.625 0.125 at c 0.5625 0.375
fire_3 5,26 26x11 at p 0.125 0.25 at s 0.8125 0.25 at cl 0.625 0.125 at c 0.5625 0.375
fire_4 41,26 26x11 at p 0.125 0.25 at s 0.8125 0.25 at cl 0.625 0.125 at c 0.5625 0.375

test_1 64,64 32x32 fliph
test_2 96,64 32x32 fliph flipv
test_3 128,64