Events – Story Tellers iOS Starter Kit Documentation

Events are the foundation of interaction in the kit. Here’s a few ways you can trigger events…

  • By touching down or up on an Element.
  • By simply opening a new Page, events can be run automatically.
  • By using a timer, you can run events repeatedly or just once, at time intervals you choose.
  • By “listening” for certain values or other conditions. For example, if the iOS keyboard has a value (implying the reader typed their name). Or if a value does or does not equal something (for example, ApplesTouched is greater than 5). You can also listen for conditions like two objects intersecting (maybe for a puzzle type game). And you can setup event listeners in groups so some or ALL conditions have to be met before the events are run.
  • When any physics objects have collided with each other OR when specific physics objects collided.
  • When an Element is added to the scene, events can be run automatically.
  • And finally when certain gestures have occurred, for example, the user has tapped twice with two fingers. Or the user has rotated something.

How you setup an event is usually determined by how much data is needed to do something. For example, in the image below the CameraFollows event is relatively simple. You just need to define a new thing for the camera to follow. In this example, that’s Dog

Events in the Story Tellers iOS Starter Kit 1

Sometimes you’ll want to change the String type to an Array so you can set multiple values for the same event. Notice in the next image the String now says Array, and the ShowOrHide property will be run on multiple nodes.

Events in the Story Tellers iOS Starter Kit 2

Even though the ShowOrHide event is affecting many nodes (Village, Bar, and Jail), it’s requirements are simply “who” to affect. We don’t need to set a value for ShowOrHide because all it does is turn on or off the node’s visibility.  If an event can affect more than one node, you can switch the value from a String to Array and list multiple nodes.

Some events need to be defined as a Dictionary so you can set both a key and value. For example, in the image below, you can see that the event is MoveNodeToNode and the Person’s position will be set to that of the Bartool’s position.

Events in the Story Tellers iOS Starter Kit 3

Throughout this article you’ll see exactly how to set up each event.

Setting Up Events – Advanced notes

Key values in a property list must have unique names. So you can’t do the following….

Events in the Story Tellers iOS Starter Kit 4

But you can set your own Dictionary names, and enclose the action within that. The parent dictionary name is ignored.

Events in the Story Tellers iOS Starter Kit 5

Events (and really anything in a Dictionary) gets run as an unordered list. So you can’t choose what thing happens before another. Most likely you won’t need to, but the kit does prioritize a few events. SetValues, SetRandomValues, SetRandomNumberValues, SetValuesIfNil, SetValuesFromPool, SetValuesFromPoolReverse, Add, AddRandomElementFromFile all occur before every other event (when run at the same time).



Quick Look at Where To Add Events

Lets take a look at some of the most common places to add a dictionary of events….

Events in the Story Tellers iOS Starter Kit 6

  • At the highlight labeled “A”, notice the dictionary is named TouchEvent, unlike all the other dictionaries which have the name EventsTouchEvent is inside of an Element (Logo) so touching any Element in the scene with the name Logo, would trigger this event. Elements can trigger events in multiple ways, hence the more specific name of TouchEvent. Some of those other ways are also included in the image TouchUpEvent, EventWithAnyContact, and EventWithContact2 (the latter two are physics based contacts).
  • At the highlight labeled “B”, the Events dictionary is listed in the Cover page’s dictionary. These events are run immediately after the page loads (but after parsing the property list and setting up the scene). You could use this to run actions, set or reset values, add random images, etc.
  • At the highlight labeled “C”, the Events dictionary is listed inside of EventTimers > Timer1. The Timer1 dictionary can be started or stopped at anytime (the name you give your timer group is completely up to you). The Events listed within the dictionary here occur at time intervals specified by the other properties. They can run repeatedly or just once
  • At the highlight labeled “D”, the Events dictionary is listed inside of EventListenersListener1.  The Events dictionary is only run if the conditions are met that are specified within dictionaries like ListenerFor!=  (this dictionary makes sure a certain value does not equal something). Event Listeners can be setup in groups, where all conditions must be met within the group.

These are the 4 most common areas you’ll probably run Events.


Events vs Actions

Using a mix of touch events, physics events, timers, listeners and automatically-run actions you have an arsenal of ways to trigger interactivity in your book app.

Events in the kit are mainly focused on things that can’t be done by creating Actions in the Scene Editor, but the kit has many important events for running or stopping Actions.

Events vs Actions

As of Xcode 7, you can now create Actions (or groups of Actions) with timeline editing options. So for example, you might create actions to play sounds, move elements up and down, perform very specific things like fading in briefly and fading out over 20 seconds.

Play Sounds with SKActions

So for the creation of most simple or common “visual events” the kit relies on the way more convenient Scene editor for creating and editing those actions. Read more here about composing actions.

With that in mind, your event might simply be to RunAction with a key of MoveUpAndDown on one or more items in the scene (as seen highlighted in the first screenshot). Actions you create in the Scene editor do not have to be run automatically and can be triggered at anytime from an Events dictionary.

This image below shows the common Actions that Xcode 7 provides you with to drag and drop into either your main scene (or an .sks file which will save your own action combinations). When you start building your own Actions, they will show up as possible actions to drag into your main scene (listed by the name you give them). This same name is what you’ll refer to them by when running Events in the property list.

So imagine for a moment how many things you could do visually with just Xcode 7’s new features.

Lots of SKActions