Properties for Table Objects in the Pinball Games iOS and tvOS Starter Kit

Properties for Table Objects in the Pinball Games iOS and tvOS Starter Kit

Sprites with a Custom Class of either TableObject or Light  are your two main types of “set decoration” on your table. In this article, we’ll discuss all the properties for a TableObject, which shares many of the same properties as a Light, but with one key difference.

A TableObject is intended to collide with the main ball, or any extra balls, on the table. So in normal conditions, the TableObject sprite and Ball sprite won’t share the same physical space. Like in the real world, you and the wall next to you, can’t simply co-exist in the same space. A collision would occur if you tried to walk into the wall.

A TableObject can temporarily remove its physics body with certain properties, so for example, you might create a TableObject that appears to go ascend or descend into the table, and time an animation to play when the physics body turns on or off.  Normally though, your TableObject sprites will have a body that the ball collides with.  This includes, walls, bumpers, buttons, any other kind of obstacle or target to aim at.

The kit can listen for a contact between the Ball’s physics body and the TableObject’s physics body to potentially do something when that contact occurs.  That “something” could be to hold the ball, move it, give it a new impulse vector, play a sound, animation, advance a goal, etc. We’ll discuss all the possibilities in this article.

 

Need a quick reminder on how to setup a TableObject?

Setting up a TableObject is a 3-step process….

  1. Give the Color Sprite a name (in case you want to identify it in the Property List to add properties)…

Setting up a Table Object in Xcode 1

2. Set it’s physics body. This could be a rectangle shape, circle or Alpha Mask. Most likely you will also want to toggle off Dynamic, Allows Rotation and Affected by Gravity, but your TableObject could have any of these toggled on.

Setting up a Table Object in Xcode 2

3. Switch from the Attributes Inspector Tab to the Custom Class tab, and give the sprite a Custom Class of Light.

Setting up a Table Object in Xcode 3

 

Properties for TableObjects…

Property List in Xcode 7

Your TableObjects dictionary will contain sub-dictionaries, each matching the name of a TableObject sprite in your scene. TableObjects can have the following properties (none are required)….

Sounds

  • Sounds – this property allows you to play a sound (or sounds) when a ball comes in contact with the object. This value can be a String or Array of String values of sound file names (each name should match a sound file imported to the project). Names should include the file extension. If you include an Array of names the object will pick one at random to play. Using the property below, you can change the default behavior and play all sounds listed in the Array.
  • PlaySoundsInSequence –  (default is NO) If this Boolean property is set to YES, the object will play all sounds in the Array, in the order listed.
  • SoundKey – set this value to a unique name (anything you want) and the app will prevent the sound from playing again if it is already playing. Multiple objects could include the same SoundKey, to avoid overplaying a particular sound.
  • BallRollSounds –  this property allows you to play a secondary sound (or sounds) when a ball comes in contact with the object. Like the Sounds property, this can be a String value or Array of String values.
  • PlayMainBallRollSounds – (default is NO)  If this Boolean property is set to YES, the app will play one of the sound files as defined in the Sounds > BallRoll dictionary.

Array of String values


Adjusting the Object’s Physics Body

The Scene Editor in Xcode gives you three options for setting the shape of the physics body of your TableObject (Rectangle, Circle or a very exact Alpha-Mask body which outlines the artwork of the sprite). The kit gives you some extra options to adjust the Rectangle and Circle bodies.

  • BodyType set a value of either Circle or Rectangle (Square actually works too)
  • BodySize – If the BodyType is Rectangle, you can set this value to make the body exactly the width and height you prefer. The value will be in {width, height } format. Squiggly brackets, which enclose two numbers separated by a comma.  For example, {100, 200} would make the width 100, and height 200. This is a String type value.
  • BodyOffset – If the BodyType is either Circle or Rectangle, you can shift where the physics body is in relation to the sprite artwork. The value will be in {x, y} format. For example, a value of  { -100, 30 } would move the physics body -100 points on the x axis  and 30 points up on the y axis. This is a String type value.
  • RadiusDivider – If the BodyType is Circle, the RadiusDivider will make the circular physics body larger or smaller if it is greater than or less than 2. A value of 3 will make the body smaller.
  • Friction – a number between 0 and 1 to override the Scene Editor’s friction value. 0 is like glass or ice, 1 is more like sandpaper
  • Restitution – a number between 0 and 1 to override the Scene Editor’s restitution value. 0 is not bouncy at all. 1 is very bouncy. Also see the EnhanceImpact property to make objects even bouncier than 1. 
  • ZeroMaskAfterCollision (Default is NO) – Setting this Boolean property to YES will turn off the body after the ball collides with it. If ResetOnBallLoss is YES, the body will come back on after the ball is lost.
  • BodyOnFor – a value for the number of seconds the physics body will be on for. Meant to be used with the next property, to toggle the body on and off again in a loop.
  • BodyOffFor – a value for the number of seconds the physics body will be off for.

ball stopper pinball app

The ball stopper above has a physics body of a custom size and offset. Notice how the rectangular shape is not centered or the same size of the source art.


 

Adjust the Object’s Location After a Collision

  • CollisionOffset – Using this property, you can change the TableObject’s position after the ball collides with it. The value will be in {x, y} format. For example, a value of  { -50, 0 } would move the physics body -50 points on the x axis  and 0 points on the y axis. This is a String type value.  If ResetOnBallLoss is YES, the initial position will be set again after the ball is lost.

 

Score and Achievements

  • Score – a number value for the amount of score to add when the ball contacts the object.
  • IncreaseScoreWhileHold – A number value. If the object holds the ball, the score will be incremented this amount every frame the ball is held.
  • AchievementText – text to display in the AchievementLabel when the object is contacted.
  • AchievementText2 – text to display in the AchievementLabel2 when the object is contacted.

Changing Textures on Contact

  • CollisionTexture – the name of a texture to change to when the object is contacted. Normally the original texture is reverted to when contact ends.
  • KeepTextureAfterContact – (default is NO) a Boolean value, setting this to YES will keep the object from reverting to it’s original texture after contact has ended.

Impacting the Ball

  • EnhanceImpact – (default is none) a Number value to enhance how much a ball will “bounce” off the object. The Scene Editor provides a Restitution option (essentially the bounciness of it) but the top range might be lower than needed. Try setting this value to 2 or higher, to see it’s effect.
  • CollisionVector – A String value, in { vector x, vector y} format to set a specific vector for the ball after it contacts the object. For example, a value of  {200, -300} would apply an impulse to the ball with a vector of 200 on the x axis and -300 on the y axis.

 

Holding / Moving the Ball

  • HoldsBallForDuration – (default is none) a number value for the seconds to hold the ball when it contacts the object.
  • HideBallOnHold – (default is NO) a Boolean value, setting this to YES will hide the ball when it is being held.
  • CenterBallOnHold – (default is NO) a Boolean value, setting this to YES will move the ball to the center of the object.
  • MovesBallToNode – (default is off) a String value matching the name of another node (even an Empty Node) to move the ball to when it contacts the object.
  • MovesBallToNodeWithHoldTime –  (default is off) a String value matching the name of another node (even an Empty Node) to move the ball to when it contacts the object. When combined with the HoldsBallForDuration property, this will move the ball with the same duration it is being held for.

 


 

Playing an Animation on Contact

  • Atlas – the texture atlas containing a sequence of frames for the animation. Do not include .atlas in the value
  • CollisionAnimation – an Array containing the frames listed in order. Do not include .png in the value
  • CollisionFPS – (default is 30) a number value for the frame rate of the animation.
  • CollisionAnimationLimit – (default is unlimited) a number value for the max number of times the animation can be played.
  • LoopAnimation – (default is NO) setting this Boolean property to YES will loop the animation once it has begun

Screen Shot 2016-02-26 at 3.21.57 AM


 

Resetting

  • ResetOnBallLoss – (default is NO) Setting this Boolean property to YES will reset the object to it’s original look and location when the ball is lost. This will reset not only the original look of the object, but also reset any goals it contributed to.

 

Goals

  • AddsToGoals (or AddsToGoal)  – a String or Array of Strings listing Goal names to increment when the object is contacted.
  • MaxToAddToGoal (default is unlimited) –  a Number value for the max number of times contacting the object can add to the goals listed.

Multiplier goals

In the screenshot above, the MultiplierButton uses an Array for AddsToGoal with 4 goals listed:  SetMultiplierTo2, SetMultiplierTo4, SetMultiplierTo6, SetMultiplierTo8. Each of these goals is achieved at a different threshold: 1, 2, 3, and 4 respectively. So contacting the MultiplierButton once would unlock the SetMultiplierTo2 goal. Contacting it a second time would unlock the SetMultiplierTo4 goal. Achieving goals can trigger a variety of other events. When the ball is lost all of these goals are reset, because the ResetOnBallLoss property is set to YES. 

Screen Shot 2016-02-26 at 3.51.37 AM


 

Stored Animations

You can include up to 8 stored / saved animations per TableObject.

  • Animation1Atlas –  the texture atlas containing a sequence of frames for animation 1. Do not include .atlas in the value
  • Animation1Frames – an Array containing the frames for animation 1 listed in order. Do not include .png in the value
  • Animation1FPS –  (default is 30) a number value for the frame rate of animation 1
  • LoopAnimation1 – (default is NO) setting this to YES will loop the animation once it has begun
  • Animation1Sound – the filename of a sound to play for animation 1. This sound is preloaded.
  • Animation1Delay – (default is 0) a value for the number of seconds to delay playing the animation.

To create animations 2 through 8, change the property names above with a different number, for example, Animation2Atlas, Animation2Frames, and so on.


Automatically Playing Stored Animations

  • AutoPlayAnimation – (default is none) a number value of a saved animation to play. For example, setting this to 3, would automatically play the properties setup for Animation 3
  • AutoPlayAnimationDelay – (default is 0) a value for the number of seconds to delay automatically playing the animation.

Timing the Depth and Animation when the Physics Body Toggles On or Off

These properties are mostly intended to be used with the BodyOnFor and BodyOffFor properties mentioned earlier.

  • PlayAnimationWhenBodyOff – A number value for a stored animation to be played when the physics body is turned off. For example, setting this to 1, would play Animation 1.
  • PlayAnimationWhenBodyOn – A number value for a stored animation to be played when the physics body is turned on
  • ZDepth – A number value for the normal depth of the object. This can be set in the Scene Editor, but also via the property list. If the physics body is toggled on and off, the object will go to this depth when the body is on.
  • ZDepthBodyOff – A number value for the depth of the object when the physics body is off.

 

Misc

  • DynamicDepth – (default is NO) setting this Boolean value to YES, will make the object’s z depth (layering) change depending on the main ball’s location. If the main ball is above the object, it’s z depth will be higher than the ball, and vice versa. This can make it so the ball appears in front of or in back of the object depending on it’s y location.

 

Playing Another Object’s Animation

Contacting a TableObject can trigger a different Light or TableObject to play their animation (this could also be done by achieving a Goal), but as a convenience we’ve added the following properties…

  • PlayAnimation1 – a String value or Array of String listing other Lights or TableObjects to play their stored Animation 1.
  • PlayAnimation2 – a String value or Array of String listing other Lights or TableObjects to play their stored Animation 2.
  • PlayAnimation3 – a String value or Array of String listing other Lights or TableObjects to play their stored Animation 3.
  • PlayAnimation4 – a String value or Array of String listing other Lights or TableObjects to play their stored Animation 4.
  • PlayAnimation5 – a String value or Array of String listing other Lights or TableObjects to play their stored Animation 5.
  • PlayAnimation6 – a String value or Array of String listing other Lights or TableObjects to play their stored Animation 6.
  • PlayAnimation7 – a String value or Array of String listing other Lights or TableObjects to play their stored Animation 7.
  • PlayAnimation8 – a String value or Array of String listing other Lights or TableObjects to play their stored Animation 8.