Story Tellers iOS Starter Kit Documentation
I know from helping people debug the original Story Tellers Kit how important it is to let them make a typo safely. In other words, a misspelling in the Property List probably won’t crash the app. A typo, or misnamed property, obviously won’t do the thing you want though. So if something isn’t happening that you think should be happening, that’s usually the first thing to check. Code is very literal.
For example, these two properties are not the same.
If they were, they wouldn’t even be able to co-exist in the same dictionary (key names have to be unique).
In this kit, property names ALL start with a capital letter. If there’s more than one word in the property name, each word begins with a capital letter. For example…
Spaces are treated as something
If I accidentally wrote a space at the end of a property name, that invisible little character could cause a big headache, since spaces are recognized as “something”. So even though these two properties look identical, the only reason they can coexist is because the top entry actually has a space after “Hide”….
Things that don’t belong.
If a property isn’t recognized, it is usually ignored. You might get a message in the Output window that the kit didn’t match the property name to something it recognizes, for example, an event name. In some cases, the kit might try to run an action with a misplaced property if it can’t figure out what you were trying to do. So we do have some catches in place for errors. But because things are generally just ignored, you can use that to your advantage and turn on or off entire dictionaries by just giving them “unrecognized” names. For example, I add “ – OFF” to the EventTimers dictionary below…
When the code looks for any EventTimers, it won’t find it.
Which to use String, Boolean or Number?
All the property definitions in this guide will tell you to use a specific type for the value. For example, in the next image, you can see the only three value types (not including Dictionary and Array, which are group types)…
I could switch all of these to String and the kit should act the same…
Why so lenient? Under the hood, the kit does this…
It first checks if the value is not nil (it exists). Then it checks if it is the ideal type it should be, for example, Int (an integer number). If the type isn’t a number, it moves onto String. So the code is optimized for the ideal value, and yes, will run marginally faster with the right types. Using String instead of a Number is actually fine. I would just suggest making sure the Bool types (YES or NO) values are set up right. Otherwise the code has to do this…
Which as you can see, is quite a few checks just to determine if you wrote “YES” as a String. You could also have written “Yes”, “1”, “true”, “True” or “TRUE”. Depending on your background, you might think of a Bool as more of a true or false thing, vs. YES or NO.
But hey, most of these properties are only loaded once, and when the page first loads up, so if you want to slow it down marginally, the kit will accommodate your preference for values.
Usually if the kit REALLY does care about a specific value type, it will do so in grand fashion and crash. In which case, try setting the ideal values.
The Simulator Speed
The Simulator is a terrible test environment. It tries it’s best, but don’t think for a moment that it resembles the speed of an actual iOS device. Sorry, but when it comes to the Simulator, your MacBook Pro is outrun by your Phone. This is especially true when physics are involved. The Simulator might be running at 20fps, but your device will chew through those physics at 60fps. Every good developer knows this already…
Never Trust The Simulator Speed
Debugging High Strangeness
Occasionally a change you know you made in the Scene just isn’t showing up, so apparently some Simulator caching does occur. To rule this out, in Xcode go to the Product menu while holding down the Option key on the keyboard, Clean will turn into Clean Build Folder.
Also if you’ll be working with setting values (which are saved as NSUserDefaults) in the app, you can clear those out by deleting the test build of your app on either the Simulator or the device itself. Wiggle it to death. Or on the Simulator you can also go through the menu…
iOS Simulator -> Reset Content and Settings.
Crashing with error… [Element setFilter]
You will get an error to that effect, if you accidentally subclass the scene itself (the SKS file) as Element. So for example, if nothing was selected in your scene, then your scene’s properties will show in the File, Attributes and Custom Class inspector tabs. What you want to see when your scene is selected is in the Custom Class inspector is shown below…
You only want to enter Element as the Custom Class for Color Sprites (SKSpriteNodes).
If you stumbled onto this article, it is part of our documentation for the Story Tellers iOS Starter Kit 2. The kit enables you to make children’s book apps and games without writing any code! But it is Swift 2 based and compatible with iOS9 (or higher) and Xcode 7 (or higher), so kit buyers can even extend the functionality to fit their needs further. Some of what we cover in the kit documentation may apply to Xcode in general, so this article could be worth a read even if you aren’t a user. You can purchase Lifetime Updates the kit here, or subscribe Yearly to CartoonSmart and get the latest version, plus access to all of our other kits / tutorials.
We’ve also created an iBook to document the very latest properties in the kit, so be sure to download that as well.