Properties for Lights in the Pinball Games iOS and tvOS Starter Kit
Sprites with a Custom Class of either Light or TableObject are your two main types of “set decoration” on your table. In this article, we’ll discuss all the properties for a Light, which shares many of the same properties as a TableObject, but with one key difference.
A Light will never collide with the ball, meaning they won’t bump off eachother. The kit listens for a contact between the Ball’s physics body and the Light’s physics body to potentially do something when that contact occurs. That “something” could be to play a sound, animation, advance a goal, and everything else we’ll discuss in this article.
Below are examples of Lights we’ve used in our tables….
It’s important to remember the bodies of a Ball and Light can occupy the same space. So a ball can roll over or under anything of the Light class, depending on it’s zPosition (visual depth). The sprite does NOT necessarily have to look like a light. It could be a metal gate the ball rolls through, a giant animated hand it rolls under, a tunnel, and so on. A Light could also be as simple as a hidden Color Sprite used to only trigger a sound. You might do that to trigger a ball rolling sound when it goes over a certain area of the table.
Setting up a Light is a 3-step process….
- Give the Color Sprite a name…
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.
3. Switch from the Attributes Inspector Tab to the Custom Class tab, and give the sprite a Custom Class of Light.
Properties for Lights…
Your Lights dictionary will contain sub-dictionaries, each matching the name of a Light sprite in your table scene. Lights can have the following properties (none are required)….
- Sounds – this property allows you to play a sound (or sounds) when a ball comes in contact with the light. 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 light will pick one at random to play. Using the property below, you can change the default behavior and play all sounds.
- PlaySoundsInSequence – (default is NO) If this property is set to YES, the light will play all sounds listed 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 lights could include the same SoundKey, to avoid overplaying a particular sound.
- PlayMainBallRollSounds – (default is NO) If this is set to YES, the app will play one of the sound files as defined in the Sounds > BallRoll dictionary.
Score and Achievements
- Score – the amount of score to add when contacting the light.
- AchievementText – text to display in the AchievementLabel when the light is contacted
- AchievementText2 – text to display in the AchievementLabel2 when the light is contacted
Changing Textures on Contact
- CollisionTexture – the name of a texture to change to when the light is contacted.
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 to YES will loop the animation once it has begun
Resetting, Hiding, Disabling
- ResetOnBallLoss – (default is NO) Setting this to YES will reset the light when the ball is lost. This will reset not only the original look of the light, but also reset any goals it contributed to.
- ResetOnEndContact – (default is NO) like the property above, but this will reset the light as soon as the ball is no longer contacting the light
- ResetTextureOnEndContact – (default is NO) setting this to YES will reset the light to the original look when the ball is no longer contacting the light. If an animation is playing, the light will return to it’s original texture. If the light was initially hidden, it will go back to being hidden.
- Hidden – (default is NO) setting this to YES will hide the light.
- ContactTurnsOnOff – (default is NO) setting this to YES will toggle the light on or off anytime it is contacted. If the Light adds to a Goal, when it is toggled off, the Goal will be subtracted from.
- DisableContact – (default is NO) setting this to YES will optimize some code under the hood. If YES the light will only be used for scoring, playing sounds, or setting achievement labels.
- AddsToGoals (or AddsToGoal) – a String or Array of Strings listing Goal names to increment when the light is contacted.
- MaxToAddToGoal (default is unlimited) – a Number value for the max number of times contacting the light can add to the goals listed.
The example above shows a Light named Card1, which turns on and off when contacted by the ball. Card2, Card3, Card4, Card5 have identical properties. Each one adds to a Goal named FullHouse. When the FullHouse goal has been added to 5 times, the goal is achieved. All 5 card lights would need to be on at once for the goal to be achieved.
You can include up to 8 stored / saved animations per light.
- 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.
- BallMustBeOnRails – (default is NO). Setting this to YES will make it so the light can only be contacted when the ball is currently on a rail.
- Parallax – (default is disabled) Setting this to a small number, somewhere between 0.05 to 0.3, will move the light relative to the camera. This is a great setting if you want to include a highlight or reflection type effect, as if the table has a piece of glass over it.