Setting Sprites

Sprites in Enter the Gungeon are not stored loosely. Instead, they are contained within groups called collections, with the class tk2dSpriteCollectionData. All Vanilla sprites are already pre-sorted into collections based on how they are used, and knowing how to search those collections for the sprites you need is a useful skill when wanting to re-use vanilla sprites.

tk2dSprite Component

GameObjects that have a sprite ingame have a tk2dSprite component (which actually renders the texture). Each tk2dSprite is set to a specific sprite collection. It can only be set to one collection at a time, and can only display sprites from the collection it is set to. Fortunately changing the collection a sprite is set to is fairly simple, and will be explained later.

Getting a reference to an objects attached sprite component is as simple as using the GetComponent method, as shown below.

tk2dSprite thingy_sprite = thingy.GetComponent<tk2dSprite>();

If the gameObject does not have a tk2dSprite component, perhaps because you have created it yourself, you will need to add the tk2dSprite component first using the AddComponent method.

tk2dSprite thingy_sprite = thingy.AddComponent<tk2dSprite>();

Once you have a reference to the sprite of a gameObject, you can alter the sprite it's actually displaying using the method SetSprite. There are two primary versions of the SetSprite method, as shown below.

//If the texture you desire to switch to is in the sprite collection the tk2dSprite is already set to
thingy_sprite.SetSprite(newSpriteId);

//If the texture you desire to switch to is in a different sprite collection
//If the tk2dSprite is not yet set to a collection, then you must use this method
thingy_sprite.SetSprite(newCollection, newSpriteId);

As you can see, knowing what collection the sprite you want to load is stored in is important.

Getting a reference to the tk2dSpriteCollectionData of a vanilla gameObject is as simple as getting a reference to it's sprite using GetComponent and checking the Collection variable. The SpriteBuilder class in Alexandria's ItemAPI also contains static references to the vanilla game item sprite collection and Ammonomicon sprite collection.

//Gets the tk2dSpriteCollectionData associated with the sprite of any gameobject
tk2dSpriteCollectionData arbitraryCollection = exampleGameobject.GetComponent<tk2dSprite>();

//or...

//...just use the Item collection already defined in Alexandria's SpriteBuilder
tk2dSpriteCollectionData itemSpriteCollection = SpriteBuilder.itemCollection;
//Don't forget to put using Alexandria.ItemAPI; at the top of your code!

If you're looking for a more specific collection, like (for example) the Blobulon sprite collection, you will need to get a reference to the Blobulon gameobject prefab in order to call GetComponent and fetch it's sprite.

Now that we know how to get a reference to the sprite collection, getting a reference to the ID of a sprite is simple. Sprite IDs are int (integer) values, meaning they are whole numbers and are, innately, hard to sort through and remember. Luckily for us, the GetSpriteIdByName method exists, which returns the numerical ID of the sprite using its string name.

//The GetSpriteIdByName method exists on the tk2dSpriteCollectionData, so we have to have a reference to the correct sprite collection FIRST. 
//The sprite name won't include file extensions like .png, so be sure not to include them. 
int spriteID = arbitraryCollection.GetSpriteIdByName("the_name_of_the_sprite_i_want");

Applying a Sprite Change

With all that explained, let's put it all together with some example code showing us cleanly changing the sprite of a gameObject from one texture to another. Here we use the item sprite collection, easily accessed through the SpriteBuilder in Alexandria's ItemAPI, and the texture blood_brooch_001, which is the sprite of the Blood Brooch item.

//Get the tk2dSprite component of the gameobject we wish to change the sprite of
tk2dSprite thingy_sprite = thingy.GetComponent<tk2dSprite>();

//We ge the target sprite collection
tk2dSpriteCollectionData itemSpriteCollection = SpriteBuilder.itemCollection;

//We get the ID of the blood brooch sprite from the target sprite collection
int newSpriteId = itemSpriteCollection.GetSpriteIdByName("blood_brooch_001");

//We put it all together, calling SetSprite on the tk2dSprite component with both the target sprite collection and the target sprite ID as arguments
thingy_sprite.SetSprite(itemSpriteCollection, newSpriteId);

This code will correctly change an objects sprite to the sprite of the Blood Brooch, and can be easily adapted to any sprite collection or sprite definition in the vanilla game. This code, however, can be further simplified and compacted onto a single line, as seen below.

//The above code, consolidated onto a single line
thingy.GetComponent<tk2dSprite>().SetSprite(SpriteBuilder.itemCollection, SpriteBuilder.itemCollection.GetSpriteIdByName("blood_brooch_001"));

Applications

Being able to set and change the sprite of a gameObject has a great many applications in more complex modded additions, such as special item effects or custom room objects. Potential uses could include;

• An active item that sets its own sprite depending on whether it is toggled on or off

• A passive item that changes its sprite depending on some external criteria

• A spawned gameobject take takes the sprite of the players current gun

Important Notes

• Perhaps the most important thing to keep in mind is that setting the sprite of a gameobject is NOT how animations are made. Animated sprites utilise an entirely different set of tools. The code outlined above should be used for setting a sprite once, or for swapping between static sprites, not in an attempt to create full animations.