Table Scenes in the Pinball Games iOS and tvOS Starter Kit
Your Scene files (.sks) are where you will design your table for the iPhone, iPad and Apple TV. Each is a different file and could look vastly different between devices, but in most cases, you will probably just copy everything from one .sks file to another, and keep the look of your table identical between devices. Labels and buttons are probably the only thing that will need shifting.
Being able to design your table (or any game’s level) within Xcode’s Scene Editor is a relatively new feature, and one that’s gotten increasingly better in recent versions. In the “old days”, game developers using Xcode didn’t even have a built in 2D game engine (which is what Sprite Kit is), and much less a place to visually layout the components for the engine. You can see in the image below, the table on the left is a screen shot from Xcode’s Scene Editor, and the image on the right is how it looks in the finished app. Almost identical, aside from the physics boundaries showing (the blue outlines).
Point is, designing a game with our Starter Kits is 80% an “art job” done in the Scene Editor, and the other 20% is done working with the Property List, to simply specify this triggers this to happen on the table.
If you haven’t yet figured out where the Scene files are in the project, they are pointed out in green below. Your pinball tables and any menus you want to create (like the app’s opening menu scene) can all go in here…
And while we’re looking at the project navigator, you can see where the Tables.plist is and where most of the assets you’ll import to the kit will go.
Scene Editor Quick Reference Tips
We’ve recorded plenty of videos on how to design your tables, each of which covers the same steps to add sprites into the scene, texture them, name them, add a custom class, etc. So if you at least watch the first video, you’ll understand everything much better than reading instructions.Watch the first Initial Setup video and how to Add a Ball
If you want to stick to reading though, we’ve highlighted the Attribute Inspector tab (top green arrow), and the Object Library (bottom green arrow) in the image below.
As you can see from the notes in blue, you can drag a new Color Sprite from the Object Library into the scene. You can then texture the sprite, name it, position it, rotate it, etc, using the Attribute Inspector. The Attribute Inspector handles a lot of properties that the kit’s property list doesn’t, because they are available here. Likewise, our property list adds all the specific pinball related functionality that the Attributes Inspector obviously doesn’t have.
Most of your time working with the Scene Editor, will involve these two panels being open.
Got a feel for where you’ll be working? Great. Now we want to highlight of a few of the things you’ll be doing again and again, with Color Sprites. Try to lock these points into your brain now, so you don’t overlook them later and hopefully you will understand better the connection between your Scene files and the Property List (the Tables.plist file).
This kit is not actually magical. I know, I know. It seems that way but, it’s really not. Things don’t just happen for no reason. Or in other words, things happen for a very specific reason. Like giving your sprite a Name, which is how the property list knows who in the scene to look for. And setting it to a Custom Class, which is how the game engine knows to handle a certain sprite.
In the image below, you can see a juxtaposed image of a Color Sprite named Card1 with the Attributes Inspector open (the blue circle is highlighting this tab) and then below that, the Custom Class is set to Light with the Custom Class Inspector open (the orange circle is highlighting this tab)
99% of the sprites you use to layout your scene will probably need a Name and Custom Class set. Even if the sprite doesn’t have any special properties (and require an entry in the Property List), it will most likely still need the Custom Class setting, so the game engine knows how to treat the object. Under the hood, a lot happens just because of that Custom Class. For example, a setting of Light automatically makes it so the pinball will not collide with the sprite’s physics body. Conversely, a setting of TableObject makes it so the ball will collide with the sprite’s physics body.
Notice what I wrote above sounds a little counter intuitive. Why have a physics body at all if the ball doesn’t collide with it? This is because the engine uses a Light’s physics body to detect a “contact” between it and the ball, but that doesn’t mean the two have actually collided. For example, you can walk through a laser beam without it stopping you in your tracks.
So again, 99% of the sprites you use in your scene will need a physics body. Even lights. This is done in the Attributes Inspector, with the sprite selected, in the Physics Definition section.
The Body Type can be Bounding Rectangle, Bounding Circle or Alpha Mask….
The first two options create either a rectangular or circular body, and Alpha Mask uses the non-transparent pixel data of the texture to define the body. Which is very exact, and the best option in most cases. Any pixel data above 10% transparent will become part of the physics body. So very light shadowing around the art might not be part of the physics body. Also avoid adding images which have “islands” of pixel data. For example, using Alpha Mask on an image of two separate eggs would only outline one of the eggs.
Most likely you want to turn off Dynamic, Allows Rotation and Affected by Gravity. All three are toggled on by default when you set a physics body.
If you leave these on, you might not see your object when the app runs, because gravity has already pulled it down below the bottom of the visible area. If you want to get a bit experimental with your table, you might want to play with these settings, and if so, here’s a quick rundown on each.
- Dynamic – when on, this object is part of the physics simulation and moveable. If another object collides with it, an impact occurs between the two bodies. If gravity was turned off, but Dynamic was on, the affect would be similar to two asteroids bumping against each other in space.
- Allows Rotation – this is probably the only option you might consider toggling on. With Dynamic and Affected By Gravity off, but Allows Rotation On, the ball could collide with the object and spin it.
- Pinned – You could pin an object to the table which means it could have Dynamic and Affected by Gravity On, but still stay stuck to a particular spot. It could be used to create a pendulum or hanging type effect.
- Affected By Gravity – again, the danger with leaving this on is that the object can fall down the “drain” along with the balls, and just be gone.
In the screenshot above, you’ll also notice Friction and Restitution. The ranges for both are between o and 1. For Friction, a value of 0 treats the surface of the object like glass / ice and 1 makes it more like sandpaper. For Restitution, this is the bounciness of the surface, where 0 is not bouncy and 1 is very bouncy. The kit also has a property to enhance the bounciness too.
Every Scene should have a Camera
We recommend just copying in the camera from the demo table. But you can also just pull a new camera out of the Object Library. Be sure to give it a name of TheCamera.
Cameras are always the same size as the scene they are in. You could set the zoom of the camera by adjusting it’s Scale property in the Scene editor, but we recommend doing this through the Camera’s property list settings . We’ve already got some good preset properties anyway, which set both the regular zoom and multi-ball zoom.
Any sprite in your scene can be the parent of another sprite. Which means that wherever the parent goes, any child sprites within are also moved. For example, a ball sprite might contain a ball shadow sprite.
Your camera, named TheCamera, is usually your main culprit though for containing children. Those children will typically be Labels or sprites acting as buttons, because your app’s “viewport” is basically the camera, and any children of the camera move in relation to it. Meaning, statistical labels like the Score, remaining Ball Count, etc, will appear to stay in place onscreen while the table moves up and down to track the ball.
Another neat thing about children of the camera is they don’t scale up and down with the camera. So for example, if the game goes into multi-ball mode and the camera zooms out to show more of the table, the labels won’t be affected.
To make anything have a parent (other than it’s default parent, which is the scene itself), select the object, and in the Attributes Inspector, find Parent.