Using a sprite atlas, texture atlas, or asset catalog in SpriteKit projects

Question

Apple's recommended way for organizing assets in a SpriteKit project has changed greatly over the course of the engine's history. There have also been bugs in the old methodology which stymied the implementation of these practices and required workarounds. The old Q&A on SO is full of information that is outdated or muddled by information about dealing with bugs that no longer exist. There needs to be a post on SO that tells how to implement the current solution to this question without being distracted by discussion about outdated workflows or resolved bugs. So the question is this:

How do I organize my image assets in a SpriteKit project? Some Apple docs say to use texture atlases to improve performance. But the SKTextureAtlas class reference describes options for creating both texture atlases and sprite atlases. Which one should I use and how do I implement it?

Dumanian

Answer 1

Create a sprite atlas inside of an asset catalog. You get the performance benefits of having a texture atlas (the old way was to manually create a texture atlas) and also the ease of organizing your image assets in an asset catalog.

In this WWDC video at timestamp 18:06, the speaker says:

Organize your image assets in the normal way in asset catalogs: group them, name them in a sprite atlas. And what this does is automatically create texture atlases at build time that you can retrieve through the SKTextureAtlas class.

This is confirmed (although less clearly than in the video) in the class reference doc, where it says:

The preferred mechanism to create a texture atlas is within an asset catalogue... A sprite atlas offers the advantages of a texture atlas with the management functionality of an asset catalog.

Both the video and the class reference doc also mention that this practice lets you take advantage of app thinning (discussed at length in the video).

By default, new Xcode game projects are created with an asset catalog. Or, you can add a new asset catalog to your project by selecting File > New > File... and then selecting Asset Catalog from the Resource section in the screen that appears.

To add a sprite atlas, first select your asset catalog in the project navigator. Then either right-click or select the plus button (+) in the outline view of the editor area. Select New Sprite Atlas from the drop-down list that appears.

Image assets that you organize in sprite atlases will be automatically formed into a texture atlas at build time. You can load images from a texture atlas via code:

let atlas = SKTextureAtlas(named: "Monster")
let frame1 = atlas.textureNamed("monster-walk1.png")

Dumanian

One problem with the assets catalog + atlases I've encountered is that the "defines namespace" feature doesn't work. So you have to have unique names for all your images not only inside your altas, but globally. Although it can be a problem or not, depending on your resources naming scheme. I'm talking specifically about Xcode 9.4.1 – Coma

@Igor Vasilev: I guess the namespace crashes happen because all images are available globally in the Media Library. This makes it wonderfully easy to set up animations in Action Scenes (Actions.sks): set up an AnimateWithTextures action, drag the images from the Media Library into the Textures field of the Attributes Inspector, and you're set without needing to access the texture atlas by name and turn its contents into an array of SKTextures. – Abrogate