---
description: And other useful bits and bobs.
---

# Assetbundles: How-To

Why assetbundles?\
Assetbundles allow us to "pre-build" things we can use in the game without having to create/generate them when the game is loaded. Converting embedded sprites into usable textures during runtime take a very small amount of time, but when you have over a thousand sprites and VERY large sprites, like bosscards, can add up \*very\* fast. \
Using Assetbundles also allows you to import custom shaders, use DFGUI features such as creating atlases for custom UI elements, and allows you to easily make certain visual effects like particle systems, that you can import into the game.\
\
Step 0: **Install Unity Version 2017.4.40**. From what I understand, Gungeon uses this version of Unity specifically and loading assetbundles from different versions of Unity doesn't work.\
\
Step 0.1: **Download this boilerplate Unity project**, which should have a lot of tools deemed useful for advanced things, like custom shaders. Download it [here](https://github.com/Some-Bunny/Template-Gungeon-Mod-Project). **Note, do NOT use this project for anything else. I WILL kill you otherwise (I'll get executed)**.\
\
Step 0.2: Open the Unity version you just installed, and select the "Open" option.

\
<img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FqPBgirjXyXnmXTzMsm19%2Fimage.png?alt=media&#x26;token=1cf989ab-fac5-4ea2-87b6-00adc828f00e" alt="" data-size="original">\
Navigate to the newly installed Unity project, and select "select Folder".\
\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FvPBDXQNkaKhSgdCAic6m%2Fimage.png?alt=media&#x26;token=0ef2ac94-6afc-47aa-99ff-0855aa61aeca" alt=""><figcaption></figcaption></figure>

If everything was done right, it should start processing it, and after a bit, open the project.

\
\
**Now, we need some extra code in your mod project. That's right, we're not done yet!**

Step 0.3: Add this class to your mod, either by just copypasting the code into a fresh class or whatever, and change things as needed. \
This is a simple class that will let you load your assetbundle by just sticking it in the same folder as your mods DLL.\
There are 2 versions you can download, the first is the default version thats simpler to work with, but the latter loads assetbundles based on different operatiing systems (mainly MacOS and Linux), but requires generating assetbundles for each OS.\


{% file src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FuISgr70zcBMHdu8ttE1X%2FAssetBundleLoader.cs?alt=media&token=02e40503-91a5-4db5-b17b-63f035af0c4a" %}

{% file src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FvFsLkgIxrircnUch2nkR%2FAssetBundleLoaderVersions.txt?alt=media&token=42e10485-8205-497a-bd9e-24f1fbffe2ce" %}

If you **don't** have a FilePathFolder, set this up in your module.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2F0EFEnaxpftL61rc1trz0%2Fimage.png?alt=media&#x26;token=c02306fe-b144-44b4-971b-2b02cf41ac89" alt=""><figcaption></figcaption></figure>



You should also create a static reference to your Assetbundle, so when you load it, you can load anything from it from anywhere. Make it a habit to load your assetbundle before anything else.

![](https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FwFDYOi3M9hHa18Gao1B1%2Fimage.png?alt=media\&token=2adb34dd-d173-4e05-9898-7855633fca56)\
\
Admittedly it's jumping ahead a little bit, but I will put this here as it is important.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FIwJkm8Dc4k0tMyrHC7I2%2Fimage.png?alt=media&#x26;token=11fa438b-82a3-4106-be3a-1aa61ed7aed9" alt=""><figcaption></figcaption></figure>

**Alternatively**, you can load your assetbundle directly through an embedded resource.\




```csharp
using (Stream s = Assembly.GetExecutingAssembly().GetManifestResourceStream("file path in your project to your bundle with . instead of /"))
{
     yourAssetbundleReference = AssetBundle.LoadFromStream(s);
}
```

If "Stream" shows up white and has an error, add " **using System.IO;** " to the top of your class.\
\
\
Now that we have set this up, we can now actually work inside of the Unity Editor.



## Assetbundles and nearly everything about them.

**This will go over how to actually make, add to, generate, and access things from your assetbundle.** \
\
With your template, it should be quite easy as you don't have to add anything yourself.

### Making a new bundle

Simply clicking on any object in your explorer tab will put an option in the **Inspector** window to put it in an assetbundle.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2Fy0bhMMCsQ0B5Ow4C308p%2Fimage.png?alt=media&#x26;token=0938e83d-6845-41d4-8fd7-349807f85d40" alt=""><figcaption></figcaption></figure>

**Note the highlighted area.** \


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FZaRQWTpxYaBk5Ax06Uih%2Fimage.png?alt=media&#x26;token=390c031e-9fee-41f9-be8a-b3e13e88b4ba" alt=""><figcaption></figcaption></figure>

Click on the dropdown tab and a few options should appear \
(**as part of this demonstration I already have an assetbundle called example\_bundle**)\
\
Click on **"New..."** and create a new assetbundle with whatever name you want. This will be the name you will use when **loading** the assetbundle.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FNXXYHXwrbyZpUTQeo4cD%2Fimage.png?alt=media&#x26;token=b7231090-b2dc-4251-8f7a-ee3f95afc60a" alt=""><figcaption><p><mark style="color:red;"><strong>When you select "New..." the box will turn like this and you can type in a name</strong></mark></p></figcaption></figure>

\
And voila, you now have a new assetbundle. \
You **can have multiple assetbundles** if you want to keep things organized.

### Adding Objects to your Bundle.

\
Selecting None will not put the object into the assetbundle when it's generated. By default, objects will not be in any assetbundle until assigned one, **so remember to assign things to assetbundles**.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2F11CF08eFtEUf8VEn2e5s%2Fimage.png?alt=media&#x26;token=edf6b1ff-81ac-483c-845d-3bee468c6370" alt=""><figcaption><p><mark style="color:red;background-color:blue;"><strong>Note how it says "None" for its assetbundle option.</strong></mark></p></figcaption></figure>

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FwBjWKl06Wjk2f8x3r0OK%2Fimage.png?alt=media&#x26;token=13d9bd0e-5ff7-444a-81bf-85995b5a470f" alt=""><figcaption><p><mark style="color:red;background-color:blue;"><strong>And now, its part of the "example_bundle" assetbundle.</strong></mark></p></figcaption></figure>

Once you did that, you've now added an object to your assetbundle. You can add as many objects and bundles as you like, **but do note it will take longer to generate** depending on how much stuff needs to be added to a bundle / bundles generated. Try do things in batches, but considering the asset sizes we will likely be using are small, it shouldn't be too bad.\


## Generating your Assetbundle.

Right click and select "Build Assetbundles". That's it.

![](https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FbfqzofAGAuNObOOkDgTz%2Fimage.png?alt=media\&token=4fcbf75c-e7fe-4ada-ad09-b61804cb3e93)

This will build all of your assetbundles, and package anything assigned to a bundle, into one.

Your generated bundles will appear in the appropriately named "**Assetbundles**" folder. \
Once they're generated, you can simply drag it out of there and into where-ever you want the file. **Note that your assetbundle will look like the file in the Green square.**

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2Fhcd69weBo50l5hI82gaJ%2Fimage.png?alt=media&#x26;token=7db9b558-9626-4ae5-b937-07d2af9e08c1" alt=""><figcaption></figcaption></figure>

\
\


## Accessing objects from your Assetbundle.

The **other generated file** with the same name as your bundle/s is a **manifest file**, while its not needed, it is a very good reference for loading things from the assetbundle. \
It will usually have some useless garbage data at the start but under "Assets" it shows you what assets are in your bundle.\
Heres a very short list as an example.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FicmXiJXDpcBCRvv3GjTF%2Fimage.png?alt=media&#x26;token=92e46b06-53f8-490c-a5e3-f001aeddd864" alt=""><figcaption></figcaption></figure>

Keep this in mind.\
\
To load an asset from your bundle, you simply run this line of code.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FT6hZb5oOZCIPspdLJWmR%2Fimage.png?alt=media&#x26;token=634afcbf-9660-4dfd-9492-a94e3a3d03c1" alt=""><figcaption></figcaption></figure>

Using the Modular mod as an example, here it loads a **GameObject** by the name of "**ModularGunClip\_Atlas**" from the assetbundle. \
Depending on the file ending, you put different things into the green part. For example:\
Assets that end with **.prefab** are loaded as **GameObjects**.\
Assets that end with **.mat** are loaded as **Materials**.\
Assets that end with **.shader** are loaded as **Shaders**.\
And simple image files, like **.pngs** as loaded as **Texture2Ds** or just **Textures**.\
\
As for the red part, its just simply the name of your asset.



## The Tools at your disposal.

The template unity project has a few but useful tools at your disposal, with the main version being a similar version of the sprite building assets that Gungeon uses.\
The main tools are:

1. Sprite Collection and Sprite Animation tools.
2. DFGUI, mainly used for building DFAtlases for custom UIs.
3. Shader Forge, a tool used for making completely custom shaders.
4. Other pre-packaged Unity features such as Particle Systems.\


This guide will only go over using the Sprite Collection and Animation tools. DFGUI stuff is nearly the same as the Sprite Collection stuff and Shader Forge is its own beast you'll have to explore by yourself.\
\


## Creating a sprite collection.

You can create a new sprite collection from your **Project** window in the Editor (**it will have all of your folders visible**), by right clicking, then following:\
**Create > tk2d > Sprite Collection**\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FPEI1kN2zlj9KNYX7kxIh%2Fimage.png?alt=media&#x26;token=c52aa780-7016-434c-8981-fbc1c2635857" alt=""><figcaption></figcaption></figure>

This will create a new Sprite Collection asset in the folder you created it. You can rename the Collection by clicking on the name.\
\
To actually add sprites to your image, you click on your Sprite Collection asset and press the "Open Editor" button.\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2F71sukk5A0wEKzO1CRywv%2Fimage.png?alt=media&#x26;token=96887ea0-0c89-483e-a9e7-e4e1b076fb8d" alt=""><figcaption></figcaption></figure>

This will open a new window, and to add sprites to it you can simply just drag them in, as long as you have added the sprites to the Unity project. (**Remember, for good organization, create new folders for your sprites in the Unity Editor, don't just have 700 sprites in a random folder for your own sanity**) The order doesn't really matter.\
\
**However, there are a few important steps to follow before you can commit your Collection, or it will generate not to Gungeon specifications.**&#x20;

1.  **When adding sprites, their Anchor MUST\* be set to "Lower Left".**\
    This anchor is used by just about all sprites in Gungeon so not using it where its usually used (Like items and guns) will make it look VERY offset. \
    **You can select multiple sprites by holding shift and selecting the first and last sprite in the collection to modify them in batches.**\
    \
    **\* Sprites do not necessarily need to have a Lower Left anchor point, however the vast majority of things, such as items, guns, enemies, etc use Lower Left. Experiment if you want/need to with anchor points, it can save you a lot of headache if used right.**\
    \


    <figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FaUSRHHaBdpcAHmdWSnQV%2Fimage.png?alt=media&#x26;token=80ac924c-06be-4f5d-adc1-a12431db9f61" alt=""><figcaption></figcaption></figure>

    **1.5: Set "Pad method" to "Black Zero Alpha".**\
    Although very minor, in Gungeon if this is not set to "**Black Zero Alpha**", if these sprites are outlined, they will look weird / wrong. Make sure to set this for all of your sprites.\
    \


    <figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FJUAhHjixXD9Fc2v9uUUj%2Fimage.png?alt=media&#x26;token=6793a73c-7387-407e-a942-844a23f651aa" alt=""><figcaption></figcaption></figure>
2.  **Under Settings, Set "Pixels Per Meter" to 16.** \
    Gungeon uses the same P.P.M so if you don't set this your sprites will look VERY small ingame.\


    <figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FRdai2prDml7slzQhVYRa%2Fimage.png?alt=media&#x26;token=56d358af-bd26-4e99-809b-2bea88d20257" alt=""><figcaption></figcaption></figure>
3.  **Tick "Disable Trimming" and set Pad amount to at least 2.**\
    If your sprites utilize empty space, Disabling the trimming will keep said empty space. The padding is to prevent weird overlapping.\


    <figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2Fz3PCoMYYxkaI4iDizXEB%2Fimage.png?alt=media&#x26;token=3d03f1da-ca24-4fbd-b1d1-39c04afcc2c0" alt=""><figcaption></figcaption></figure>
4. **Under Texture Settings, set "Filter Mode" to "Point", and Compression to "Uncompressed".**\
   This makes your collection generate its sprite sheet with no compression, keeping your sprites crisp and clean.\
   ![](https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FfxOHqAWbF3XumjOHTx8I%2Fimage.png?alt=media\&token=3e989643-ff68-48e6-97eb-9f8db81cfaa8)\


**You will only have to repeat point 1, as your settings will save once you Commit the Collection.**\






Once you have commited your collection, a new folder with the same name as your Sprite Collection will appear. This folder will have 3 things, all 3 which are important in some way. \


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2Fa3lpxq9cVthyXI7Eky6D%2Fimage.png?alt=media&#x26;token=74bdedff-2b73-4efa-9044-d5b1da4d3ab3" alt=""><figcaption></figcaption></figure>

The item in the **Green Square** is the material of your Sprite Collection. You can rename this as you please. \
In your new generated Collection (marked below in blue), add your new material to the "Material" tab in your Collection. (Marked below in green)\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FbjCH2TDhZn3tQyJ5UIzj%2Fimage.png?alt=media&#x26;token=a5828022-ffe1-49e7-a873-20c6304946d6" alt=""><figcaption></figcaption></figure>

\
\
The item in the **Blue Square** is your **Sprite Collection Data**. This item is **required to go into your Assetbundle.**\
\
The file in the **Red Square** is the sprite atlas. When generated, it will look slightly weird, but to get it to good condition, click on it and:

1\. Set its "**Texture Type**" to "**Sprite (2D and UI)**"\
2\. Set its **Pixels Per Unit** to **16**.\
3\. Tick the "**Alpha Is Transparency**".\
\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FPQp8BeoGt1qFEhoODeip%2Fimage.png?alt=media&#x26;token=f184e016-46ab-4ea5-b4f3-a48f0a05593c" alt=""><figcaption></figcaption></figure>

Once you did that, click "Apply". Once you have done this, every time you Commit your sprite collection you will not have to do this, **except for Ticking** "**Alpha Is Transparency**", though not much changes if you don't.\
\
Once you have finished up, you can build your Assetbundle and load it into the game.\
\
**To Note: You can add as many sprites to your collection as you want, though it will take longer and longer to generate. You can also go back into the Collection and add new sprites / remove sprites if you've commited a Collection, as long as you Commit it again, and follow the required steps.**\
\
\
To be able to actually use it in the game, you'll first have to run a tiny bit of code.\
Run this method to load your Sprite Collection.

```csharp
YourCollectionReference = YourBundle.LoadAsset<GameObject>("YourSpriteCollection").GetComponent<tk2dSpriteCollectionData>();

```

This will load, process and return a usable sprite collection that you can access from anywhere.\
\
It is VERY advised to create a class from where you initialise all of your sprite collection datas, for cleanliness.&#x20;

\
\
How do you actually use it?\
\
The most common use will likely be items, as they only require one sprite (**unless they use VFX**), and ItemAPI already has a method for using pre-built sprite collections.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2F7NLOdBdamqTvPQRxoJQX%2Fimage.png?alt=media&#x26;token=0f265351-8c51-4b71-a130-fa09d02335bd" alt=""><figcaption></figcaption></figure>

Using Planetside as an example, it accesses a pre-defined sprite collection, and feeds the sprite collection and the sprite ID from the collection.&#x20;

You can get the ID of the sprite you want by using multiple ways, but running **GetSpriteIdByName** is a favourite of mine as you just need to insert the sprites name into it and nothing else. You can also use GetSpriteById(), if you know the ID of the sprite. You can find the ID of your sprite by opening your sprite collection and clicking on the sprite.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FnMCYnLXHUUwK75A8p5y9%2Fimage.png?alt=media&#x26;token=6b418ecb-6986-41ae-96da-c6bd1d0c1611" alt=""><figcaption></figcaption></figure>

For uses outside ItemAPI, here is an example:\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FA3j56k6f7RLSIq9Ve56U%2Fimage.png?alt=media&#x26;token=6363cd54-155f-4b26-ac77-bc2dc63c36e3" alt=""><figcaption></figcaption></figure>

Simply getting the sprite component in your object is more than enough to be able to use bundled sprites., as long as you set the sprite collection to the correct one and use the pre-existing **SetSprite** method to set a sprite to your one.

##

## Creating a Sprite Animation

Tired of assigning hundreds of sprite numbers in a row to create _**one goddamn animation?**_ This is the perfect thing for you then!

You can create a new sprite collection from anywhere in the Unity Editor, by right clicking, then following:\
**Create > tk2d > Sprite Animation**



<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FtAvfGG55ev2jKxiqj9lb%2Fimage.png?alt=media&#x26;token=b01b322f-0948-449b-9b96-0550cd9da04f" alt=""><figcaption></figcaption></figure>

This will create a new Sprite Animation component. You can rename this to whatever you please.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FPPHC7AQxvT7tN67Fx6lJ%2Fimage.png?alt=media&#x26;token=ea6477eb-2e44-4900-a053-1cb38cf6c0f4" alt=""><figcaption></figcaption></figure>

Click on it, and press the "**Open Editor**" button.\
This will open up a somewhat complicated looking UI, but once you get used to it, its very helpful.

![](https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2F0ULNV6k4yYtXa8rvGUEh%2Fimage.png?alt=media\&token=cfff9316-5f72-4544-a2ee-132ccb254fbc)\
Here you can choose to **create a completely new clip** with default presets, or **Copy an existing one you've made**.\
\
Lets start with the top half on the right side.\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FwLLk0I2FpYEU3DMCxJwZ%2Fimage.png?alt=media&#x26;token=5b67d5a3-0c3d-4e07-87ab-57145cb2245a" alt=""><figcaption></figcaption></figure>

Here is an overview of every thing in here, that I know of.

**Name**: The name of your animation clip. **VERY important.**\
**Frames**: Non-changable, shows how many frames long your animation is.\
**Frame Rate**: Self explanatory, the amount of frames per second your animation plays at.\
**Wrap Mode**: the way in which your animation plays.

* **Loop**: Loops your animation once it reaches its end. Example: idle animations.
* **Loop Section**: Plays your animation normally, but once it finishes, it loops again **starting from the frame where you set the Loop Start option**. This option only appears with **Loop Section** selected. Example: Charge animations for guns.
* **Once**: Plays your animation once. Example: Firing animations in guns.
* **Ping Pong**: Once it finishes playing your animation, plays the animation again but with the frames reversed. Repeats forever.
* **Random Frame**: Genuinely no idea. Probably just picks a random frame from your clip to set its sprite to.
* **Random Loop**: Same as **Loop**, but instead of playing from the start of the clip, starts the animation from a random point in the animation clip.

The rest I dont know about or dont really care about.\
\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FKQ4MBm9cfyBEKFjseQip%2Fimage.png?alt=media&#x26;token=3a951c88-4799-4a3b-ace8-cee041830603" alt=""><figcaption></figcaption></figure>

The Reverse Button here reverses all the frames currently in your clip.\
\
The Trigger button allows you to add a trigger to a frame. This is only really used in code. Remind me to show it off sometime.



<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FZfZVVtSA1lsS8MYgdcR2%2Fimage.png?alt=media&#x26;token=812822f5-3abe-469f-a90f-9745db0442e2" alt=""><figcaption></figcaption></figure>

These 2 buttons are fairly self-explanatory. \
**Play** plays the current animation in the clip while active.\
**Repeat, while active,** repeats the animation regardless if its a looping animation or not. If the animation doesn't loop by default, it will pause for a second before playing it again.



<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FC9SRO2SplNdE9dBaOmdQ%2Fimage.png?alt=media&#x26;token=e9a4fa50-a713-45ba-8fbc-c358be1f39aa" alt=""><figcaption></figcaption></figure>

This is your frame timeline. You can add frames by pressing the \[+] button. I will mention it a few times during the next section.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2Fv2vYyNJI8etuGCdr9p4h%2Fimage.png?alt=media&#x26;token=6abfbfa6-b50b-47a7-8d9f-a1235b6e8520" alt=""><figcaption></figcaption></figure>

\
\
&#xNAN;_**Time for the fun stuff.**_

\
**Collection** makes you select a pre-existing sprite collection in your Unity Project to use sprites from. In other words, you'll need to make a sprite collection to be able to use this tool.\
**Sprite** lets you change the current sprite of the selected frame on the timeline. This can be either from a dropdown menu or a large menu with every sprite visible. You likely won't be using this much.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FygJvjCiisQmE5o4SYCzL%2Fimage.png?alt=media&#x26;token=b7c73085-561a-4608-8bd6-64a495b53ac2" alt=""><figcaption></figcaption></figure>

**Frames** lets you stretch how how many frames in the animation a sprite is. For example:

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FG8MLNavyurnIQuux4i8b%2Fimage.png?alt=media&#x26;token=2f1e2bac-bd1d-479b-b7a4-b618048e3e8c" alt=""><figcaption></figcaption></figure>

**Autofill \[1...9]** _will automatically place all sprites into your clip in numerical order_, as long as the sprites names are identical. Very practical for making simple animations quickly.\


**Autofill \[9...1]** likely does the same as above but in reverse numerical order, I don't really know. \
\
**Insert >** adds a sprite in front of the selected sprite into the clip with the same sprite as the currently selected frame.

**Insert <** adds a sprite behind the selected sprite into the clip with the same sprite as the currently selected frame.\
\
**Delete** deletes the currently selected sprite.

**Delete >** removes all frames that are in front of the currently selected frame.

**Delete <** removes all frames that are behind the currently selected frame.

<mark style="color:red;">**To Note: You can have as many unique clips in the Sprite Animator as you want, as long as every animation clip has unique names.**</mark>\
\
Once you are done, press "**Commit**", and it'll save your clips into the component.\


To actually use it in your code, add the component to your Assetbundle, and build your bundle to put it in. As mentioned above, you can do something similar to this to create an animation library accessible anywhere.\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FzH2MW6G0ZkM3fNR9CXuw%2Fimage.png?alt=media&#x26;token=09b66778-fed7-4c73-af79-00cd27a58292" alt=""><figcaption></figcaption></figure>

Then, whereever you use a SpriteAnimator component, set the Library variable to your new Tk2dSpriteAnimation, like this:

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FC1Q623GLqUGVttTOf3aK%2Fimage.png?alt=media&#x26;token=395b140f-1abe-4c2d-8330-88a287e405b7" alt=""><figcaption></figcaption></figure>

Then, as long as the animation is in the Library, you can play it through code.\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FJMOClT0BeGXJZdkWcJTL%2Fimage.png?alt=media&#x26;token=f4302c7c-d0f2-43d9-884c-a6e52c2dc559" alt=""><figcaption></figcaption></figure>

\
And for example: setting up an enemy that uses bundled sprites:

[https://github.com/Some-Bunny/Modular/blob/master/Code/Enemies/BigDrone.cs](https://github.com/Some-Bunny/Modular/blob/master/Code/Enemies/BigDrone.cs)\


## USING ATTACH POINTS

Attach points can be used to define positions on sprites that you can access through code. Their most common use is in Guns, with guns using multiple attach points to place where things like casings fall out of your gun or where at any point the player is currently holding the gun.\
\
This example will be for use in guns, but you can use attachpoints for whatever you may need.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2F2krkTEHK8IF6tp0MZQ1w%2Fimage.png?alt=media&#x26;token=af529d05-109c-4464-b6a7-b2531bac9561" alt=""><figcaption></figcaption></figure>

Inside your sprite collection editor, there is an AttachPoint button. Press it to toggle AttachPoint mode.\


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FmqbM6ZXGAdLzCrwORygZ%2Fimage.png?alt=media&#x26;token=9e475259-3ec5-454b-9bc3-960f30711932" alt=""><figcaption></figcaption></figure>

Use the "Add AttachPoint" button and add these 4 attachpoints with SPECIFICALLY these names:\
&#xNAN;**- PrimaryHand**\
**- SecondaryHand**\
**- Clip**\
**- Casing**\
**(You will only need to repeat this specific step once per Sprite Collection, after that you can simply just add these Attach Points by pressing "Add AttachPoint" or by using the dropdown menu in attach points.)**\
**(If you want to assign sprites to one handed weapons, you can simply not assign a SecondaryHand AttachPoint on whatever weapon sprites you need.)**\
\
**To actually assign positions in your sprite, simply just drag the positions to where you want them to be on the sprite.** \


<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2Fjyzqsd3QUp8svd4hH2bl%2Fimage.png?alt=media&#x26;token=f1c32bb8-3266-4d03-afdd-8b981a829eaf" alt=""><figcaption></figcaption></figure>

And that's it! Your attach points will save when you rebuild the collection and should run right out of the box for hands positions.

## ADDITIONAL TOOLS

Not everything we have is built for assetbundle usage, so heres some replacements to older things that use the new assetbundle stuff. \
\
**NOTE: If you are using the Alexandria dependancy mod (which most mods do as it's part of the template mod), you will not need to add these, as they are already a part of Alexandria.**

{% file src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FnS5hpsHge7gwuY0s4bCq%2FProjectileToolbox.cs?alt=media&token=5bd99ce4-5db2-44e2-9bff-9304a62fb5cd" %}

ProjectileToolbox adds 3 new methods:\
**SetProjectileCollisionRight(),**\
**AnimateProjectileBundle(),**\
and **AddTrailToProjectileBundle().**\
The arguments required for these should be self explanatory.\
\


{% file src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FxbnkWXeQUXSg5SFkgpM7%2FBeamToolbox.cs?alt=media&token=d6736441-ce37-4cb2-af3b-bfecaaaff1d6" %}

Mainly just a re-used BeamToolbox from Alexandria with some changes, the main difference being the new method:\
**GenerateBeamPrefabBundle()**\
\


{% file src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2F7LmRUa0IKY0oz8WexQNM%2FGunInt.cs?alt=media&token=cc195797-387c-4945-aebd-8e7e6e17b88f" %}

A replacement to **GunExt** used for custom guns, its slightly modified to allow for all the **GunExt** features to work with assetbundled sprites. The **SetupSprite()** is nearly the same, save for the sprite collection data you have to feed it now.\
\


{% file src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2FTQrIEoO3NckTnF9qwmFf%2FGunJsonEmbedder.cs?alt=media&token=2734dd28-884c-41d9-9ecf-b4ea63229eec" %}

Very important for bundled guns. This allows you to embed all of your Gun Jsons into your DLL directly, as the old method will NOT work for bundled gun sprites.

<figure><img src="https://1229800202-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQAkTlyeVttU3CJdmYk%2Fuploads%2F3vRYKNL1piciMh8cGklt%2Fimage.png?alt=media&#x26;token=7a87b9d1-e28f-478c-a82f-b22f72333fcc" alt=""><figcaption></figcaption></figure>

Using the Modular mod as an example, this uses your current Assembly, the sprite collection in which all of your gun sprites are stored, and a file path to all of your embedded gun jsons.
