Custom Sprites

Procedurline allows for modders to create so called custom sprites, by creating subclasses of CustomSprite. These sprites are used to implement static sprite processing, as they have the ability to register scopes for their sprite, and asynchronously process their own animation data when it gets used.

While CustomSprite represents a custom sprite, it only has the ability to override the copying mechanism and the scope registration (as it implements IScopedObject. CustomSpriteAnimation instances implement the actual data processing. While it's possible to use one without the other, doing so would strip you of the ability to either invalidate the processed animation data, or process any animation data at all.

Both CustomSprite and CustomSpriteAnimation also have callbacks for when SpriteHandlers start or stop to use a specific custom sprite (animation). This mechanism can be used to track if a sprite (animation) is currently actively used by a sprite in the scene, and as such prepare more expensive capabilities needed for the sprite to work properly.

As CustomSprites can be multi-threaded, the usual requirement of only updating animation data on the main thread would introduce a potentially large amount of latency which is only spent waiting for the next opportunity to perform such updates. This problem is addressed by the DynamicSpriteAnimation class, which is the parent class of CustomSpriteAnimation. It provides a separate set of properly lock-protected animation data variable, and methods to safely sync them from and to the regular animation data on the main thread. The SpriteUtils helper method GetAnimationData (which is used by all Procedurline code to access animation data) will check if an animation extends this class, and if it does, access the data in a thread safe way. In fact, Procedurline assumes that all sprite animations which do not extend from DynamicSpriteAnimation are static, and as such never change their animation data. This means that for all other animations, Procedurline will simply access their data without locking, no matter from what thread.

Procedurline ships with a few useful implementations of CustomSprite, like DerivedSprite and MixerSprite. These are more than sufficient for must use cases, and are documented here.