Buttons in the Pinball Games iOS and tvOS Starter Kit

Buttons in the Pinball Games iOS and tvOS Starter Kit

(and the SelectionOrder and Columns properties)

Adding Buttons to your SKScene in Xcode 7 and the Pinball Starter Kit

Setting up buttons in your table scene, or starting menu scene, involves three entries in the property list. Briefly, here’s what each is for.

  • Buttons –  a dictionary containing sub-dictionaries each with the name of a button in your scene.
  • SelectionOrder – an array listing the selection order of the buttons. This order is important for tvOS apps since the user can’t simply touch the screen to choose a button. So you need to define which button should be selected first, second, third, etc when using the Apple TV remote or an external controller. This is also used on iOS apps that have external game controllers connected.
  • Columns – the number of columns your buttons are arranged in.

 

Buttons

 

Screen Shot 2016-02-28 at 9.29.47 PM

The Buttons dictionary lists all buttons in your scene. Each dictionary name should match a button in the scene. Buttons are nothing more than a sprite with the Name property set….

Buttons in the Pinball Games iOS and tvOS Starter Kit

…and the Custom Class property set to Button (as seen below)….

Screen Shot 2016-02-28 at 9.34.17 PM

Be sure to switch from the Attribute inspector to the Custom Class inspector.

 

SelectionOrder

Screen Shot 2016-02-28 at 9.45.20 PM

The SelectionOrder array defines the order your buttons should be selected in if the app is run on the Apple TV or played with an external game controller on iOS. Your button names should be listed in the order they visually appear in the app, from top to bottom (if arranged in a single column), or from left to right (if arranged in multiple columns, as seen in the image below ).

Screen Shot 2016-02-28 at 9.57.06 PM

Columns

Screen Shot 2016-02-28 at 10.04.09 PM

The Columns property lists the number of columns your buttons are arranged in. By default this property is set to 1.

Different strokes for different folks…

Since your pinball app’s orientation will most likely different between tvOS and iOS, you might need to define your Buttons, SelectionOrder, or Columns values depending on the device.

Screen Shot 2016-02-28 at 10.09.21 PM

With this in mind, you can add the following extensions to any of those property names…

  • TV
  • Pad
  • Phone

For example…

Screen Shot 2016-02-28 at 10.17.29 PM

So in the example above, if the app was run on the Apple TV, only the ButtonsTV, SelectionOrderTV, and ColumnsTV properties would be used.

 

 

Button Properties

Screen Shot 2016-02-28 at 10.22.31 PM

Without any further adieu, let’s look at the properties each of your buttons can potentially include. Some properties, like AbandonBall make no sense to include if the button appears in your menu scene.  In parenthesis we will note whether the button property can be used in your table scene, menu scene or both.

  • IsPauseButton – (table scene only) a YES value will make the button toggle whether the scene is paused or not. If the scene, is currently paused, it will be un-paused. If un-paused, the scene will be paused.
  • HiddenWhenNotPaused – (table scene only) a YES value will hide the button if the scene is not paused. Or in other words, shown when the scene is paused. Any button with this property set to YES automatically hides or unhides each time the scene’s pause property is toggled.
  • SelectedImage – (both) the name of an image in the assets catalog to change to when the button is selected. This helps users viewing your app on tvOS to clearly see which button is currently highlighted before possibly selecting it.
  • SoundButtonSelect – (both) the sound filename the app will play when the button is selected (highlighted). Be sure to include the file extension, for example, button_select.caf 
  • SoundButtonPress – (both) the sound filename the app will play when the button is pressed (actually chosen). Be sure to include the file extension,  for example, button_choice.caf
  • MoveToNode – (table scene only) the name of a node to move the button to when the scene is loaded. When creating your table scene, this is a convenient way to keep your button sprites out of the way of your main design.
  • LoadMenu – (both) the name of a menu dictionary in your Table.plist to load.  For example, in the demo app, we have a dictionary named Home which defines the look of the opening menu screen. You can define as many menus as needed.
  • TableToLoad – (both) the name of a table dictionary in your Table.plist to load. For example, in the demo app, we have a dictionary named Table1 which defines all the properties for that table. You can define as many tables as needed.
  • TwoPlayerGame – (both) if the button defines a TableToLoad, and if this property is set to YES, the table loaded will be set to a two player game.
  • TogglesHUD – (table scene only) a YES value will make any nodes inside the camera invisible, except a button named “PauseButton”. This is intended to give users an option to hide stats, such as the score, remaining ball count, etc, for a more purist mode of play.
  • AbandonBall – (table scene only) a YES value will make the button abandon the current ball when pressed. The remaining ball count will be unchanged.
  • ShowGameCenter – (menu scene only) a YES value will make the button open Game Center when pressed
  • ReportHighScore – (menu scene only) a YES value will force the app to report the most recent high score. This option isn’t really necessary as it reports high scores regularly anyway.
  • OpensURL – (both) the name of a URL to open. Be sure to include the correct App Transport Security settings in the Info.plist file if your app needs to open a URL.
  • RequiresProduct – (menu scene only) the value will equal your Non-Consumable In-App Product ID in iTunes Connect. See the image below for an example of the value in the property list with that in iTunes Connect.
  • UnboughtImage – (menu scene only) the name of an image in the assets catalog to change to when the button is Locked, meaning the In-App Product ID for RequiresProduct has not been purchased*.
  • UnboughtSelectedImage – (menu scene only) the name of an image in the assets catalog to change to when the button is selected (highlighted) but Locked, meaning the In-App Product ID for RequiresProduct has not been purchased.
  • RestoreProducts –  (menu scene only) a YES value will make the button restore all past Non-Consumable purchases when pressed.

*A button used for purchasing should by default (in the Scene Editor) display the unlocked or normal image to show assuming the product was bought. At runtime the kit will switch this button to use the UnboughtImage as it’s Locked version (if the product has not been purchased).

In App Purchasing Example in Pinball Games iOS and tvOS Starter Kit