feat: add utility functions to set sprite order

[LordMidas]

To be looked at after we finish port to Modern Hooks.

[Enduriel]

Need to print a warning when there is a queue cycle

[LordMidas]

I think that the fact that our MSU.Sprite.addSprite function adds all the sprites that are found in InFrontOf and Behind of a sprite when that sprite is being added is problematic. Because this means it may add those sprites in an order which isn't meant for those sprites. We should only deal with ordering with respect to ONE other sprite.

So, the function should in fact be:

function setOrder( _script, _sprite, _behind )

This way whenever the _behind sprite is being added, we add _sprite immediately before that.

Alternatively we allow the _behind in this function to be an array, and whenever any sprite in _behind is being added, we add _sprite before that.

This ensures that we don't end up adding sprites to an entity in an order that wasn't meant for those sprites.

[Enduriel]

@LordMidas I actually agree, I think that simpler approach has all the utility of the more complex one without more strange edge cases

[TaroEld]

Do we have a use case for this?

[LordMidas]

Do we have a use case for this?

Yeah e.g. in Reforged we add cape sprites to some Ancient Dead leaders. That cape has to appear above the armor but behind the helmet, so it needs to be added to the entity behind the entity's helmet sprite. The only way to do that right now would be to hook the addSprite function in a switcheroo way inside the onInit function of that entity. But what if we want to add this new rf_cape sprite to a dozen entities, now you have to switcheroo the addSprite function in a dozen entities in an ugly way as below:

function onInit()
{
	local addSprite = this.addSprite;
	this.addSprite = function( _sprite )
	{
		if (_sprite == "armor")
		{
			local ret = addSprite(_sprite);
			this.addSprite("rf_cape");
			return ret;
		}
		return addSprite(_sprite);
	}
    this.skeleton.onInit();
    this.addSprite = addSprite;
}

WIth this new method you set the order of that sprite to be behind behind helmet so whenever helmet is being added it adds this sprite before that. The way Enduriel is suggesting is that you would still end up doing it individually for all the dozen entities, but at least it won't look like above. Instead you can do it centrally in a place somewhere.

I have so far found myself to be more open to the switcheroo method above, so probably we don't need this new spriteOrder functionality. I think we should postpone it to 1.4.0 at least for now.

[Enduriel]

I've had to do this in layered items as well, it does have use cases though they are admittedly uncommon. I'm okay with postponing this too