How to Import Art, Animation and Sound Assets to Xcode

How to Import Art, Animation or Other Assets to Xcode

Importing any kind of file to Xcode 7 (or higher) is a cinch. You can simply drag and drop the file(s) into the Project Navigator (the left column seen in the image below).  There’s an important step you don’t want to miss, notice in the animation below a pop up box appears after the sound file is dropped into the project. I need to toggle on both PinballTV and PinballiOS in the Add to Targets section. I always have Copy items if needed toggled on. Remember to double check these settings every time you import something. Adding the correct targets, essentially means the asset is actually going to be included in the final build of the app. So if you forget to do this, you’ll eventually run into a problem.

Generally speaking, when developing your pinball apps, you’ll most likely import assets for both the TV and iOS devices. I think it’s very rare you won’t. The only time we did with our Old West Pinball app was for app icons, which get added slightly differently (to a dedicated spot for icons). But for images of the table, animations, sounds, you will most likely want those assets to exist for both targets.

Importing Assets to Xcode 7

 

Importing PNG files to the Game.xcassets folder (or Assets Catalog)

Static images (those that won’t be part of animation sequence) will most likely be imported to the Game.xcassets folder, which is located inside the PinballTV group. Even though this asset catalog is inside the PinballTV group of the project navigator, this catalog is shared between both iOS and tvOS Targets.

Importing images to Xcode asset catalog

Again, you can simply drag and drop the image into the asset catalog. When importing files this way, you will not get a pop-up prompt regarding which Targets to add to. This is because the entire catalog has already been set to be included in both iOS and tvOS builds.

1x Images? What?! Why!?!

You’ll notice in the image above, we’re importing an image named BumperRight2.png, which automatically falls into the 1x image slot. If the image was named BumperRight2@2x.png or BumperRight2@3x.png it would have automatically gone into the 2x or 3x slots. This would also assume you created your image at a 2x or 3x resolution (basically making it 2 or 3 times larger than it’s normal size).

So how come our images in the Pinball Games Starter Kit, are all 1x? This is a little technical, but a neat aspect, so hang in there for the answer. Take the iPhone 6 Plus for example. It sports a crisp 1080 by 1920 display (rendered pixels are a little higher, that number is physical pixels). Determining locations in your game or app on the phone isn’t done by pixels though, it is measured in abstract points. So the points of the phone are actually much lower 414 by 736 on the iPhone 6 Plus, 375 by 667 on the iPhone 6, 320 by 568 on the iPhone 5, and you get it: the smaller the phone, the less abstract point sizes. These sizes are all equal ratios of each other (until you get down to the iPhone 4s), so things scale down perfectly on each phone.  Many developers will make their Sprite Kit scene sizes as big as the largest point size, for example 414 by 736.

What we’ve done is make the Sprite Kit scene size 1080 by 1920 on the iPhone, about 3 times larger than normal. Which means graphics designed at that resolution (as yours should be) are already 2 times or 3 times larger, and will simply get scaled down when Sprite Kit scales the entire scene. The 1x images then become a crisper resolution when scaled down (no, they do not lose resolution when scaled down).

What Size to Design Your Scene At?

The size of the Scene (your .sks) file for the iPhone is 1080 by 1920, which is oriented in Portrait mode. So when creating your table art, whether thats in Adobe Photoshop, Illustrator, Animate/Flash, your table should be around that same width and the height can vary. Our Old West Pinball table was designed at 1080 wide, but the upper ramps ended up making the height around 2300 (about 400 points taller than the 1920 scene height).

So does that 1080 by 1920 size sound familiar? Maybe the term “1080p” rings a bell from shopping for TV’s? Your normal TV these days has 1080 horizontal lines running across it (and 1,920 vertically). tvOS apps are locked in at a 1920 by 1080 size and permanently in Landscape mode. Whereas a pinball game on the iPhone or iPad is best played in portrait mode to see as much of the height of the table as possible.  But either way, we’re dealing with a Scene size at either 1920 by 1080 or 1080 by 1920. Which means assets we copy back and forth between the iOS scenes and tvOS scenes don’t need any scale adjustments. So you could copy an entire table’s worth of sprites from the iPhone Scene, into the iPad Scene, then into the TV Scene without needing to scale them (you might need to move them up or down / left or right to center them). Which is what the image below is illustrating….

universal Sprite Kit Scenes for iOS and tvOS

In each Scene the table art exceeds the Scene size (the yellow box), and much more so on the TV, but the kit accounts for that by making the Scene’s camera track the ball vertically. So the height of the table can be whatever you want.  You can also adjust the zoom of the camera to exclude any extra negative space on the sides of the table. We did this for the iPad, but on the TV you probably do not want to zoom in much further (otherwise, the user can’t really get a sense of where to aim on the table).

So long story, short: You can simply copy and paste Sprites that use 1x images between your device-specific Scene files. They  will scale down to crisper images on the iOS devices, and in the case of the TV, 1x is the max resolution anyway.

Adding Texture Atlases for Animation

For anything on your table that will be animated, you’ll want to export the image sequences to a folder named [something].atlas . And yes, it will feel odd adding a period to a folder name, but that’s all you have to do to create a texture atlas folder. Notice in the image below, we are exporting an image sequence from Adobe Animate (ahem, Adobe Flash). Prior to exporting them, we create a new folder named “BumperAnimation.atlas” . 

Texture Atlases for Xcode

This folder can then be imported to Xcode using the first method described above (just drop it anywhere into the Project Navigator), and be sure you toggle on both Targets for TV and iOS.

Like other images imported to the kit, your animated sequences should be PNG files at 1x resolution. So whatever size they are in your design files, just export at 72dpi.

Pro Tips:

 

When Texture Atlases are included in an Xcode project, the entire .atlas folder, including whatever images are currently inside, is what gets added to the final build. Keyword “currently”. So you can add or remove images from the folder, without having to re-import them or the .atlas folder. For animators this can be convenient if you find yourself testing different animations of the same object repeatedly. You can simply overwrite what is currently inside the .atlas folder. You can do this via the Finder window, and to find the .atlas folder after it has been imported, simply select the folder in the Project Navigator and right click, then find Show in Finder.

Under the hood, Xcode combines the atlas sequences into a Spritesheet at runtime to optimize them. If you include a lot of images in a single texture atlas, you might see a warning about them being split into multiple atlases, but that’s a safe warning.

You can import as many texture atlas folders to the project as needed.

Feeling lucky punk? Lets add those App Icons

There’s a superstition among iOS developers, that you don’t add your app icons until the app is finished. Personally, I wait until the day I submit my app to Apple before adding App Icons. Folklore has it, if you add your icons early on in development, the project will never get finished. You’ll be cursed with what looks like a completed app on your iPhone or iPad, and reminded forever of yet another failure to finish something in life.

But hey, maybe that’s just me.

So anyhow. Adding your app icons is yet another case of simple dragging and dropping. For both iOS and tvOS these images go into a catalog named Assets.xcassets, but this same folder appears twice in the project. The image below points out both occurrences.

Where to find App Icons and Dashboard Image for tvOS or iOS apps

For tvOS apps, you will also need to include a Dashboard Image (1920 by 720), LaunchImage (1920 by 1080), and if you enable high score boards, a Leaderboard image.