Layer Ordering: API? Implementation?

To support layer ordering, we’ll need to do one of two things:

• Change Project.sprites from an object (which has no explicit order) to an Array, and add a getSprite or sprite method to access a sprite by name.
• Give each sprite a layerOrder property, and use some complex logic like Scratch does to keep them in order in the renderer. Some of this logic (e.g. sorting sprites by layer order) would have to be done each frame, as we don’t maintain a “draw list”, instead just drawing whatever Project.sprites contains.

_Originally posted by @adroitwhiz in https://github.com/PullJosh/scratch-js/issues/23#issuecomment-569812205_

[adroitwhiz]

IMO any non-contiguous layering system is asking for trouble. Floating-point z-index in particular trades apparent simplicity for a bunch of complicated issues under the surface.

For instance, moving a sprite forward n layers means enumerating the first n sprites with a higher z-index, then swapping the nth sprite’s z-index with the current one. Moving a sprite backwards means a similar process.

If you want to insert a new layer between two other layers, you’d have to increment the z-indices of every layer above the new layer. Note that it’s not enough to make the new layer’s z-index the average of the layers above and below it–if you inserted enough layers in the same spot (see: any sprite which creates a couple hundred clones), the z-indices would be packed closer and closer and you’d quickly run out of floating-point precision.

Sprites’ z-indices probably wouldn’t be directly interactible anyways–that would allow too much room for annoying bugs, especially if the runtime wants to modify z-indices when, as I mentioned earlier, you perform any layering operations. If you allowed API consumers to modify z-indices, you’d open the door to them doing things like giving two layers the same z-index, or trying to move sprites forward one layer by incrementing the z-index (remember, this is a floating-point z-index so there can be an arbitrary number of sprites between successive integer z-indices!)

You’d have to sort sprites by z-index in the renderer anyway-- OpenGL’s z-buffer doesn’t work with transparent textures.

[adroitwhiz]

I think this leads into a wider question about Project.sprites. Currently, you can add sprites just by assigning a new property to Project.sprites, and delete sprites by using the delete operator on one of its properties, but this doesn’t give scratch-js any way to control what happens when you add or delete sprites.

It feels more like it was designed around an Object of sprites being passed once when Project is initialized, with no sprites being added or removed at runtime.

I think that using Objects for static sets and Maps or Arrays for dynamic ones is more idiomatic in JS, so it comes down to whether the API should support the dynamic addition or removal of sprites in a running Project.

If dynamic sprite addition/removal isn’t supported, the API becomes easy: just give each sprite in the object passed to the Project constructor a layerOrder property, and inside the Project constructor, create an Array of the passed sprites sorted by that property. You could also Object.freeze the project’s sprites to prevent unexpected tomfoolery.

If you do want to support adding/removing sprites, I think it makes much more sense to store them as an array (as is already done for another dynamic set: sprites’ clones). There would be Project.addSprite to add a sprite, Project.removeSprite to remove one, and Project.sprite or Project.getSprite to get a sprite by its name. This would mean that sprites would be accessed by their name property as opposed to the object key they’re instantiated with, but for simplicity’s sake I think that’s a good thing. You could also keep the object-based Project constructor and automatically set a sprite’s name based on the corresponding object key.