Documentation for CartoonSmart’s Pinball Games iOS and tvOS Starter Kit

Documentation for CartoonSmart’s Pinball Games iOS and tvOS Starter Kit

Here we go again. Time to get serious about documenting the in’s and out’s, why’s and how’s of another powerful CartoonSmart kit! As usual, I think it’s worth noting right away that this is a Starter Kit, not an app to “reskin”. We grimace hearing that word here at CartoonSmart. If you aren’t familiar with that term (good for you), it refers to the practice of buying the source files to a project and just changing the art. Why’s that term irk us?  Reskinning another developer’s previous project implies two things. First off, the app couldn’t have been that successful to begin with if the source files are being sold to reskin. And second, the app probably can’t be made that much better by simply changing the graphics. The code in an app sold for reskinning is rarely written for the lay-man, and it is even rarer that the original author added a user-friendly property list.

So while it might seem like our Starter Kit’s are in the same family as an app being sold for the purpose of reskinning, its quite the opposite. Our Kit’s are made to create completely different apps than the include demo projects or the apps we’ve submitted to the App Store using the kit. Our kits are essentially entire game engines in a single Xcode project. But on top of that engine, is a layer of property list-driven options that provide data to the engine, which gives non-programmers a very safe (usually crash-proof) buffer between themselves and the more complicated code in the engine. But more importantly, the property list a creative tool. Almost like a scripted outline for what your game does.

So for example in this kit, you can create an unlimited number of “goals”. These goals can be triggered by something happening once, like the ball rolling into a certain spot, or the goal might only be accomplished by an event occurring multiple times, for example a ramp being rolled over 10 times. Goals can be used to turn on table lights, play sounds, animations, score points, move or hide things, add extra balls, add to other goals, load an entirely different table, and much more.

Reading the documentation will not only give you some necessary working knowledge of the kit, but it should also get your creative juices flowing as you realize what’s possible beyond the included the demo project. In fact, you could create a table so unrecognizable we might not even realize it was made with our kit.  The Story Teller’s Kit has so many possible options it is basically like entire Property List version of Sprite Kit itself, making ANY thing possible. The Pinball Games kit has far fewer properties to learn (yes, breath a sigh of relief), but there’s enough to fuel dozens of different pinball games, and keep you busy (and hopefully wealthy) for years to come!

So the first tip: bookmark this page.


The Property List at a glance…

The documentation will be organized much like the property list itself. In the right column, you’ll see sections dedicated to each of the main dictionaries in the property list below…

The property list in the Pinball Games Starter Kit

You’ll notice Table1 is selected above. As you get started using the kit, you will probably want to keep things easy and not rename it. But once you are familiar with the kit, and the relatively few places in the property list that the name Table1 is referenced, you can rename it. You can also create as many other table dictionaries as you’d like.  Each one would define the data for a particular table, for example, UnderwaterTable, GolfTable, etc… Your app might include a dozen or more different tables. You could also include variations on a table as well. We did this in our Old West Pinball app, by including a main table dictionary , then an alternate version for tvOS that rotated the entire table 90 degrees. So if someone was crazy enough to turn their TV in portrait mode, they could play the table like so.

Pinball Starter Kit Loading Example

In the image above, arrows are pointing from two different buttons, one loads the Table1 dictionary data, the other loads another table, Table1Alternate.

For simplicity’s sake, the demo project only includes one table dictionary.


Continue Reading About the Property List… Read about Designing Your Table Scene Files…

Pro Tips using a Property List:

Property Lists are very simple files, as you can see above, rows and columns, each with a key and value.  Some values, like those for Table1 highlighted above, are defined as a Dictionary type which essentially means it is a group of even more data. You can unfold a dictionary to reveal the data within.  As you’ll discover tinkering with the Tables.plist file in the kit, you can delete, add, and copy and paste keys (which will copy the values as well).

You can unfold dictionaries and fold them back up again, using the hotkeys: Option – Arrow Left or Option – Arrow Right. If you click the Root of the Property List, you can fold up every unfolded dictionary. Click to unfold the Root, and each will stay folded back up.