The home / intro screen in the kit is created from the Home.sks file, and looks like what you see above. This example shows all the possible buttons you can include (at this time) to start the game, open Game Center or open another menu screen (which would be a separate .sks file, capable of showing other buttons).
Lets unfold the Home dictionary in the property list, and take a look at the data for this menu…
You can see we have a dictionary named Buttons, which contains other dictionaries, each with information about what that particular button does. The order you arrange these buttons does not matter.
We then have a SelectionOrder array, listing each of the buttons. Remember, arrays are ordered lists, so unlike dictionaries, the order you list these buttons matters. If you have two columns of buttons, list them in “reading order”, from left to right, then onto the next row. When selecting buttons this order is important, as you don’t want swiping up, down, left, right to select a button that the user wouldn’t expect.
The Columns property is a number defining how many columns your buttons are arranged into. If you have two columns, enter 2.
MP3Loop is a looping audio file to play in the background.
IntroSound can be a .caf or .mp3 file, which will play once when the screen opens.
How to Add a Button to the Scene
Adding a button is simple. Drag a Color Sprite to the scene, texture it, then give it a name. Notice in the image below, the name is ContinueButton which of course matches what is listed in the property list.
The next step is to switch to the Custom Class Inspector icon (circled below) and give the button a Custom Class of Button (seen below)
General Properties for All Buttons
All buttons can set the following three properties (and you can see how these look in an unfolded button in the image below)…
- SelectedImage – the image to change to when the button is swiped over to, thus indicating it has been selected (not chosen, just selected).
- SoundButtonSelect – the sound to play when the button has been selected. Include the sound file’s extension, such as .caf or .mp3, in the value. This is optional, and leaving it blank is harmless.
- SoundButtonPress – the sound to play when the button has been pressed. Include the sound file’s extension, such as .caf or .mp3, in the value. This is optional, and leaving it blank is harmless.
Game-Initiation Properties for Buttons
- Levels – An optional value to specify the array of levels in the property list to load for the game. If excluded, this value will default to “Levels” (for reference, that array is circled below in the Root of the property list). This property is mostly intended to be used when initiating two-player versus games, and as you can see in the image above, the property is set to “VersusLevels” in our TwoPlayerVersusButton. Since player-against-player levels are typically smaller arena-style levels, we thought it was useful to group versus levels separate from the main game’s “campaign” style levels. Note: it is possible to create an entirely unique array set of campaign style levels for example, “WaterLevels”, and load those instead of the main “Levels” array..
- LevelToLoad – The number, starting at 1, of the level to load within the levels array as specified in the property above. Most likely, you’ll want this value to be 1, but you could add buttons that jump to “sections” or “chapters” of your game.
- SinglePlayerGame – a YES or NO value for whether or not to include the second player in the game. A YES value would be set for solo, one player games.
- Player1PlaysAsPlayer2 – a YES or NO value for whether or not to switch whoever is normally playing as Player1 to use the Player2 character in the game (by default this is NO obviously). Add this property as a Bool value and set it to YES on any button that initiates any level of the game to have the switch occur. Players will be switched until a new game is started.
- SecondPlayerIsCPU – if the previous property is NO, you can decide whether or not the second player is played by the CPU (played automatically). How good is the CPU? Well, it can survive a while in boards without many pitfalls. The CPU will walk right off a cliff as its not that smart. If this value is NO, the game is expecting the second player to be played using whatever second controller is available. If another controller is not found, an image will be displayed prompting a second controller to get connected. You can see that image in the demo Level.sks file.
- PlayerVersusPlayer – a YES or NO for whether or not this is a versus style game. If YES, the players can obviously damage each other in the level. Also winning the level is determined by which player dies first. Each level sets it’s own properties for the images to show and sounds to play when a player wins the round. The next level is automatically advanced to when a player has lost all hearts / lives. If this value is YES, and the previous property is set to NO, the game is expecting the second player to be played using whatever second controller is available. If another controller is not found, an image will be displayed prompting a second controller to get connected. You can see that image in the demo Level.sks file.
- ContinueLastGame – A YES value will continue playing from the highest level reached in the last non-versus game. If this value is YES, you do not need to set any other properties, as the previous game settings will be used. So if the previous game was a one-player game, then continuing will be a one player game.
- DisableIfNotReached – if your button will jump to a level beyond 1, you can optionally include this property and set it to YES, which will disable the button if the player has not reached that level yet. This is useful for buttons that act as chapter or section markers.
Game Center and Loading Other Menus Properties
- ShowGameCenter – a YES or NO to open Game Center. All other game-initiation or scene loading properties are ignored if this is YES.
- LoadScene – enter the base name of another menu’s .sks file to load. Do not enter a game scene here. This scene will be loaded using the same Home class as the Home.sks file, so this is only intended for adding extra menu style screens. On iOS, you can include a base name such as AnotherMenu, but include an .sks file named AnotherMenuPhone.sks or AnotherMenuPad.sks, which is sized for that specific device. The kit will check to see if that alternate version exists, before falling back to simply looking for AnotherMenu.sks .
In-App Purchasing Properties
Enabling in-app purchasing to your game is as simple as adding a few properties to a button on your Home scene (or other non-game scene). Buttons that require a particular In-App Product ID to function are “Locked” until that product has been purchased. If a Locked button is pressed, it will prompt the user to purchase it’s corresponding In-App Product. Once the product is purchased, the button will become unlocked meaning it’s a standard button again, and it’s normal properties will now work (properties like LevelToLoad). You can also set different images for the button for it’s locked state. For example, you might display all buttons to Levels 5 through 20 with a Lock Icon and “Purchase” text on top of it to indicate to users they need to buy those levels. Purchasing a product will trigger the app to re-examine all buttons in a scene to see if they should be unlocked. So if you did have 15 buttons that were locked with the same ID, they would all be unlocked at once.
- RequiresProduct – the value will equal your Non-Consumable In-App Product ID in iTunes Connect. See the image below for an example. UNLOCKBOARD would be the name of the In-App Product ID. You can choose any ID name you want, it doesn’t need to be UNLOCKBOARD.
- UnboughtImage – the name of an image in the assets catalog to change to when the button is Locked.
- UnboughtSelectedImage – the name of an image in the assets catalog to change to when the button is selected (highlighted) but Locked.
- RestoreProducts – a YES value will make the button restore all past Non-Consumable purchases when pressed.
Note: When testing In-App Purchasing, but sure to sign out of your normal iTunes account, and sign in with your iTunes Connect Sandbox (Test User) Account. Testing will probably fail if you try to use your actual account.