Animated: UI Sprites

Section 7.I.3

Displaying animated sprites in various Pokemon UI's such as the Summary, Pokedex, or PC Storage can be quite a challenge, since it's difficult to tell how a sprite may clip with various UI elements as it moves around. Because of this, much attention has been put to optimizing how sprites will appear in these displays.

Below, I'll go over all of the mechanics and features related to displaying animated sprites in the default game UI's.

---

Sprite Auto-Positioner

The sprites contained in the sprite pack contain various fan-made sprites made by many different artists. Because of this, many of the image sizes and positioning used are very inconsistent, since there wasn't any uniform process in creating them. This causes a lot of headaches when it comes to implementing a universal way of displaying these sprites in UI's, as the coordinates used to display one sprite won't necessarily correlate to displaying another one optimally. This leads to many sprites being completely cut off or overlapping the UI in awkward ways.

To address this, I've implemented a feature in this plugin that will automatically calculate the ideal positioning for each sprite. This is done by calculating how much empty space there is above, below, and to both sides of a sprite; and then calculating where the approximate "center" of the actual sprite should be based on those values. Once the center is determined, it figures out where to plot the sprite on the UI from there.

This all happens automatically, so there's nothing you need to do on your end. However, you can still fine-tune how specific species may appear, which I'll go over below.

Fine-Tuning UI Positions

While the plugin's auto-positioner functions work well for 95% of sprites, there are a few exceptions where it's still not enough to ideally display a sprite in the UI.

For example, Lugia has a very tall sprite due to how its wings flag, despite its actual body being quite low in its sprite's animation. So when the auto-positioner code determines where the "center" of that sprite should be, it ends up selecting some point that's much higher than Lugia's actual body, so what ends up displaying in UI's is mostly Lugia's wings, with its body being shifted much lower on screen. This isn't ideal, as the majority of the sprite ends up being obscured or clipping with the UI.

To address this, I've added a method of manually fine-tuning the UI positions. In the plugin's Settings file, you will find a hash named POKEMON_UI_METRICS. In this hash, each key will correspond to the species ID of a particular Pokemon, and the value of those keys will be set to an array containing two numbers.

:LUGIA => [0, -26],

Here's the entry found in this hash for Lugia, as mentioned above. This is what's used to manually fine-tune how Lugia's sprite will be displayed in UI's in-game. The first number in the array here corresponds to how many pixels its sprite should be shifted along the X-axis, while the second number corresponds to how it should shift along the Y-axis. In this example, you can see that Lugia's sprite isn't shifted on the X-axis at all, but it is moved upwards quite a bit so that you can actually see its full body when viewed in various in-game UI's.

You can use this hash to manually edit how any species or form will appear when displayed in UI's. So feel free to add, remove, or edit any species you wish.

UI Constrictions

Because animated sprites move around, they're much harder to comfortably display in various UI's in a universal way, since many of them may often clip with certain UI elements in unintended ways that can make your UI's look messy. To address this, this plugin implements a method in which to constrict sprites so that they will be cut off if they exceed a certain bounds within the UI.

This effects all of the default Essentials UI's that display Pokemon sprites. This includes the Summary, PC Storage, and the Pokedex. If you overhauled these UI's in your game so that they use different layouts, you may have to edit the plugin scripts to set different boundaries for sprite constriction.

If there are other custom UI's you've added to your game that display Pokemon sprites where you'd want to implement sprite constricting, you may do so by setting the following attribute on that sprite:

sprite.display_values = [x, y, constrictX, constrictY]

This will determine how a sprite should be displayed and constricted in your UI. The X and Y values should simply be set to the X and Y coordinates that the sprite should normally be displayed at. The constrictX value should be set to how wide the boundaries of the constriction should be around the sprite, where constrictY should be set to how tall the boundary should be. Note that you may omit constrictY if you'd like, in which case the boundary for both width and height will just be set to the same value, making a perfect square.

Note that if you do not want this sprite constriction enabled in the UI's for your game, you can disable the entire feature by setting CONSTRICT_POKEMON_SPRITES to false in the plugin Settings.

Flipping Sprites in the Summary

In vanilla Essentials, pressing the ACTION (Z) key while viewing a Pokemon's Summary page will play the cry of that Pokemon. However, if the Modular UI Scenes plugin is installed, pressing this key will also "flip" the Pokemon's sprite, allowing you to view its back sprite in the Summary.

When combined with this plugin however, you will be able to view the full animated back sprite of the Pokemon without any scaling magnifying the sprite, or any battle UI elements obstructing your view. This is the only way to get a full unmodified view of a Pokemon's animated back sprite during normal gameplay, so I thought I'd mention it here even though it's not technically a feature of this plugin specifically.