Players in the Platform Games tvOS and iOS Starter Kit

Players in the Platform Games tvOS and iOS Starter Kit

The Player dictionaries obviously have A LOT of properties you can set as they are one of the most important aspects for your game. Below you’ll find the properties used for a player in the demo of the kit (in no particular order). What you see below is not every property so be sure to read this entire page to make sure you don’t miss something useful in your game.

Property List driven players in the Platform Games tvOS Starter Kit

Note: you’ll notice some properties have “-OFF” written in them. Writing anything in the property key other than an exact match of what the code is looking for will exclude the property. This is a useful way to exclude properties you might experiment with, while keeping them in the list for reference. 

Where to Add a Players Dictionary

You do not need to add a Players dictionary on every level, but you can. So notice in the example below, there are two circled Players dictionaries. One is within Item 1 inside the Levels dictionary, and the other is in the Root of the property list….

Where to define player dictionaries

In this example the second level of the game (which is Item 1) will find the Players dictionary for this particular level and use that information to define the player’s data (which is everything about the player: their bullets, physics, sounds, animation, etc). If the level does not find the Players dictionary here, it will revert to looking for one in the Root of the property list.

So you could change the players every level if you wanted. Or you could define the players once and be done with it.


Physics Properties

You should not setup a physics body for your players in the scene file. By default players have a circular physics body setup by the code in the Player.swift class.  In the property list, you can change this to a rectangular physics body. You can see the physics of your players (and every other object in your game) by finding the GameViewController.swift file and changing showsPhysics from false to true.

Showing physics for Players in the Sprite Kit Swift file

Here are all the physics properties for the players…

  • BodyType – This should be a value of either Circle or Rectangle
  • BodySize – This property only affects bodies with a Rectangle type.  The property should be written in this format…   {width, height} … for example {50,120} meaning the rectangular shape is 50 points wide by 120 points tall.
  • RadiusDivider – This property only affects bodies with a Circle type. This value divides the width of the image to determine the radius of the circle defining the body. Sound complicated? Experiment with decimal values from 2 to 3 and you’ll probably find the exact size you want. The higher the number the smaller the physics body gets. To the point that you might notice the character’s legs are lower than the platform they are standing on. Which brings us to the next property.
  • BodyOffset – The property can be used with both Circle and Rectangle bodies, to offset where the body is in relation to the image of the character. This value is written in the following format… {x, y} … for example, {0,-5}  would not move the body at all on the x axis, and nudge it down 5 points on the y axis. Either number can be positive or negative.

Screen Shot 2015-12-09 at 4.25.17 PM

The image above shows the default physics bodies using Circle and Rectangle. Notice both could be considered a little large. You can tweak the physics shapes to make the perfect sized body regardless of the size of your source images for the player.


Animation Properties

Animation is completely optional with the kit. If you want to include animated frames for the player idling, walking, running, shooting, jumping, dying or climbing, you’ll do so by creating an atlas folder with all the animated frames, then importing that to the kit. You can make an atlas folder, by simply creating a folder on your desktop or anywhere else on your Mac, then adding “.atlas” to the end of the folder name. Add your frames to this folder now. You can then drag and drop it into Xcode. Anytime you add something to the kit, be sure the following options are toggled on…

Import options to Xcode

You always want Copy items if needed toggled on, and Add to Targets should always be checked (if not, your art won’t be added to the app binary). The middle option doesn’t really matter.

Atlases are convenient way to import sequences of images for a couple reasons. They are optimized by Xcode at runtime into a sprite sheet. And organizationally the .atlas folder is consider a single imported resources. So you can add or delete anything to the .atlas folder after importing it, and Xcode will recognize that files were modified. Which is easier than adding,  removing or changing large numbers of sequential images in the Game.xcassets catalog (which is traditionally where imported images go).

Adding an atlas folder to the xcode project

So all your images will be added to the .atlas folder. If you add more images than Xcode can optimize into a single sprite sheet, Xcode will tell you the files have been split into 2 or more sheets (if so, just ignore that warning).

Important: All frames should be Right-Facing, meaning the character is facing the right. 

Here are the properties for defining animations after your frames have been imported….

  • Atlasthe name of the atlas folder minus the .atlas extension.
  • IdleFrames – an array containing all the frame names for idling. Do not include @2x or .png.
  • DeadFrames – an array containing all the frame names for dying. Do not include @2x or .png.
  • ShootFrames – an array containing all the frame names for shooting. Do not include @2x or .png.
  • JumpFrames – an array containing all the frame names for jumping. Do not include @2x or .png.
  • ClimbFrames – an array containing all the frame names for climbing. Do not include @2x or .png.
  • WalkFrames – an array containing all the frame names for walking. Do not include @2x or .png.
  • RunFrames –  an array containing all the frame names for running. Do not include @2x or .png. You could simply reuse your walking frames here and changing the frames per second using the properties below. Running is triggered by holding down the shooting button and leaving it pressed down (think Super Mario Bros).
  • IdleFPS – the frame rate for idling. By default this is 10. Raise or lower to your liking.
  • DeadFPS –  the frame rate for dying. By default this is 10. Raise or lower to your liking.
  • ShootFPS – the frame rate for shooting. By default this is 10. Raise or lower to your liking.
  • JumpFPS –  the frame rate for jumping. By default this is 10. Raise or lower to your liking.
  • ClimbFPS – the frame rate for climbing. By default this is 10. Raise or lower to your liking.
  • WalkFPS – the frame rate for walking. By default this is 30. Raise or lower to your liking.
  • RunFPS – the frame rate for dying. By default this is 60. Raise or lower to your liking.

Control Properties

  • Speed – this is base speed of the player. The default is 4 if this value is excluded.
  • SpeedBoast – this amount is added to the player when they run (if the firing button is held down after firing). The default is 0 if this value is excluded.
  • ClimbSpeed – this is how fast the player climbs. The default is 2 if this value is excluded.
  • JumpAmount – this determines how high the player jumps. The default is 500 if this value is excluded. A range from about 500 to 900 is normal.
  • DoubleJumpAmount – this determines how high the player double jumps. The default is 0 if this value is excluded, which means double jumping is disabled. Experiment with a value of 500, and raise or lower to your liking.
  • ReviveTime – a number value for how long it takes for the character to respawn after losing a heart (life).

Weapon Properties

Players define the look and properties for their weapons. You can think of weapons as any kind of projectile: small axes, throwing stars, lasers, hamburgers, etc.

  • WeaponImagethe name of the image to use as a projectile. Do not include the file extension.
  • WeaponSpeed – a number determining how fast the weapon travels. The default is 10.
  • WeaponRotationSpeed – a number determining how long it takes for the projectile to rotate 360 degrees. The default is 0, which means the projectile will not rotate at all. If the value was 1, then the projectile would take 1 second to do a full rotation.
  • WeaponDelay – a number value for the time to wait before the projectile is release from the player. The default is 0. You might want to set this to a small decimal, if the player’s shooting animation frames display the weapon in hand initially. For example, if the player’s animation pulls back an axe prior to throwing it.
  • WeaponOffset – a value in {x, y} format to offset where the projectile initially appears in relation to the player. The default is {0, 0} but most likely you will want to reposition where the weapon appears some. For example, a value of {100, -10} would start the projectile 100 points to the right of the player (if they were facing right) and 10 points lower than the player’s y location. If the player were facing left, the kit knows to start the project 100 points to the left.
  • TimeBetweenFiring – a number value for how long to wait before the player can fire again. The default is 0.2, or 1/5 of a second.

Sound Properties

Players define their own sounds using the following properties.

  • SoundJump – the sound when the player jumps, including the file extension.
  • SoundLand – the sound when the player lands on a platform, including the file extension.
  • SoundLoseHeart – the sound when the player loses a heart (life), including the file extension.
  • SoundDead – the sound when the player dies, including the file extension.
  • SoundBounce – the sound when the player bounces on another player or enemy, including the file extension.
  • SoundShoot – the sound when the player shoots, including the file extension.
  • SoundBulletImpact – the sound when the player’s weapon impacts something, including the file extension.
  • SoundNoAmmo – the sound when the player has no ammo, including the file extension.