It’s been a while since the last update, a business trip and various other detractions grabbed enough of my time and attention to have too little left to finish this post. I did make some progress on the code front though, mostly related to input handling.
With planet setup and minimal rendering in place, the next thing I wanted to get sorted out was input handling. This may sound strange, with so many other things left to implement, why would I need input handling already? There is hardly anything in the way of gameplay, no game logic or graphics, almost nothing to control. My reasoning was as follows: many of the things that still need to be implemented and tested depend on specific in-game conditions. Turrets should fire when they can see the player, for instance. Collisions have to be triggered by actual entities hitting each other, or the planet surface. The camera should track the player ship while it moves. And so on… To hard-code all these conditions, either temporarily during development or permanently in a test case, would be messy, cumbersome and inconvenient. It would be much easier to be able to easily ‘replay’ certain in-game scenario’s, starting from some initial condition, as if someone was actually playing it. What better way than to simulate input events using the same input handling interface we will use later on when real touch and accelerometer (I’m planning to use the accelerometer to control player ship rotation) processing is implemented?
Input handling basics
The first design decision to take was how to communicate controller inputs to
the game loop. A typical MVC-like pattern in iOS games is to have a view
controller (UIViewController) that implements the relevant touch event
callbacks it inherits from UIResponder. Inside the callbacks the view
controller can do some filtering or interpretation of the touch events, for
example to recognize gestures, translate low-level touch events (‘touch
began/ended at coordinate x,y’) to higher-level semantic actions (‘user swiped
left’ or ‘user touched button B’), and eventually it will trigger some kind of
state change by calling some selector on some class representing the game state
(the ‘model’ class of the MVC pattern). For accelerometer events the idea is very
similar, with the following additions: the view controller has to register for
accelerometer events using a CoreMotion UIMotionManager, and it
will almost always have to perform some non-trivial filtering and
interpretation of the raw accelerometer data. I will probably go into
accelerometer handling details in a later post, for now just let’s assume we
have a view controller that can reliably convert accelerometer readings into a
simple, single-axis tilt angle.
One side node before we continue: the pattern described above, where input
handling is implemented in the view controller, is not the only way to do it,
and also not always the best way. For applications with complex view
hierarchies composed of many custom views that can be re-used or composited in
various screens, it may be beneficial to implement input handling inside custom
UIView classes, or in case of a view controlled by multiple, layered view
controllers, inside controllers below the root view controller. This makes
perfect sense for certain applications, but in case of games, where you usually
have a single UIView representing the ‘canvas’ to draw on, and a single
(root) view controller, I believe the approach I described in the previous
paragraph makes the most sense.
For this game, I wanted turn up the level of abstraction in the input handling
by one notch, by creating an intermediate object representing higher-level
input state and input events that can occur in the game. So instead of directly
actualizing input events by calling selectors on the class holding game state,
the view controller will register the event in a class named K14Events,
which will be inspected in the next game update (ie: the next step call).
Translating the input state into game state changes is up to the model classes.
This approach has a few advantages:
-
Easy coalescing of inputs
Multiple conflicting or canceling inputs between 2 time steps don’t result in jittery movement or unnecessary calculations to update game state that will be reverted or overridden by the very next input event.
-
Separation of detection and processing of input events
This allows performing game state updates that may be computationally expensive (such as updating certain aspects of the physics simulation) on a background thread, instead of doing everything on the application main thread that drives input events on iOS.
-
Run-time control scheme extensibility
In the future, it could be interesting to be able to dynamically add buttons or control zones dynamically using scripting, for example two control zones for left and right thrust, instead of a single one. The added abstraction layer could setup touch zones instead of having to hard-code them in the view controller.
-
Easier to simulate and re-play
When all inputs events are passed to an intermediate ‘input event abstraction class’, simulating user inputs or replaying a set of pre-cooked input events does not depend on the view controller class, and don’t require emitting low-level input events such as accelerometer readings or x,y touch coordinates. Instead, simulating or replaying an input event will boil down to ‘set tilt to -10 degrees’, or ‘set thrust on’ by calling some selector or setting some property of the input handling class.
At this stage, the last of the advantages listed above is the most relevant one. Implementing simulated input events and replay functionality simplifies testing of new game features, and adding an intermediate input handling class makes it very easy to implement these things. The other advantages will prove their usefulness later on in the development process.
Implementation details
Implementation-wise the input handling class is pretty straightforward, so
considering the length this post has grown to already, I won’t elaborate on it
too much. The class provides functionality to get and set the active state of
inputs labeled using non-predefined integer identifiers, which is another
way of saying it wraps a dictionary mapping from integers to booleans.
Additionally, it declares a floating-point scalar property tilt, which can be
set according to filtered, processed accelerometer data. The class is called
K14Inputs and its interface is declared like this:
@interface K14Inputs : NSObject
/** Device accelerometer tilt */
@property(atomic) float tilt;
// Getting and setting input active state
-(void) setInputActive: (int) input active: (bool) active;
-(bool) isInputActive: (int) input;
@endAs explained in the previous section, the basic idea is to have the root view
controller for the main view handle the UIKit events emitted by iOS, and
modify a singleton instance of the K14Inputs class associated with the
current game accordingly. Input state is then queried in the step functions
of K14Planet and the K14Entity subclasses, which react to it by modifying
game and actor state, such as rotating the player ship on tilt, or applying
force to it when the thrust input is active.
Putting all of this together revealed another oversight in the data model for
game and entity state. If the view controller needs to write input state to a
singleton instance of K14Inputs, where should it get this instance from? The
topmost data model class for game state has been K14Planet up to now, but
associating the input handling class directly with the active K14Planet
instance didn’t seem right. There could be input events that result in
modification of game state unrelated to the planet itself, for example.
Speaking of which, where would game state like that be defined anyway? Stuff
like fuel level, number of ships left, time elapsed, etc, it doesn’t make sense
to define these things on K14Planet. The most obvious place for these would
be in a parent-class that creates and manages K14Planet, in addition to
holding game state unrelated to the planet itself. For this purpose I
introduced a class K14Game, which at this point in time is not much more than
an attachment point for the K14Inputs singleton and the active K14Planet
instance. In due time, it will be extended with global game state properties
and functionality to control the game loop (pausing, resuming, etc), handling
game termination conditions, etc. Here’s a quick class diagram for the new
situation:
Replay functionality
Using the K14Inputs class as an actuator, I hacked together some really
simple action replay classes to assist in simulating and reproducing various
game scenario’s during development, without having to write actual
touch/accelerometer event handling code, and without having to ‘play’ the game
on actual hardware to test it.
The K14ActionReplay class can be described as a simple list of input events,
sorted by the timestamps at which they should be activated, and with a single
method replayEvents which will ‘actuate’ every event up to the game time
elapsed at the time of the call, then remove it from the list of events. To
eliminate frame time variance resulting in run-to-run replay differences, a
fixed timestep is passed on construction of the K14ActionReplay instance,
which will then be used for K14Game step updates, instead of the frame time
coming from the simulator.
Actuating an input event simply modifies the K14Inputs instance of the
K14Game passed on construction of the action replay class to reflect the
event. To separate advancing the replay from actuating the events on the
K14Inputs instance, defined an interface K14Replayable with a single
selector actuate that takes a K14Inputs instance to modify. Any object that
implements this interface can be added to an action replay, for now, I
implemented two: K14ActivateEvent and K14TiltEvent. The action replay can
be associated with a game by passing it as an optional argument to the
K14Game constructor, and will be advanced using its replayEvents selector
on every invocation of K14Game step.
To round up this rather long post, here’s a code snippet that illustrates how to set up an action replay, with a screen recording of the replay running inside the current ‘game engine’:
NSArray *action_replay = @[
[[K14ActivateEvent alloc] initWithTimestamp:2.75f input:K14_INPUT_THRUST active:YES],
[[K14ActivateEvent alloc] initWithTimestamp:4.0f input:K14_INPUT_THRUST active:NO],
[[K14TiltEvent alloc] initWithTimestamp:3.5f angle:-11.0f],
[[K14TiltEvent alloc] initWithTimestamp:4.0f angle:0.0f],
[[K14TiltEvent alloc] initWithTimestamp:5.0f angle:11.0f],
[[K14TiltEvent alloc] initWithTimestamp:6.0f angle:0.0f],
[[K14ActivateEvent alloc] initWithTimestamp:5.25f input:K14_INPUT_THRUST active:YES],
[[K14ActivateEvent alloc] initWithTimestamp:6.0f input:K14_INPUT_THRUST active:NO],
[[K14TiltEvent alloc] initWithTimestamp:6.25f angle:-11.0f],
[[K14TiltEvent alloc] initWithTimestamp:7.5f angle:0.0f],
[[K14ActivateEvent alloc] initWithTimestamp:6.5f input:K14_INPUT_THRUST active:YES],
[[K14ActivateEvent alloc] initWithTimestamp:8.25f input:K14_INPUT_THRUST active:NO],
[[K14TiltEvent alloc] initWithTimestamp:9.5f angle:11.0f],
[[K14TiltEvent alloc] initWithTimestamp:10.25f angle:0.0f],
[[K14ActivateEvent alloc] initWithTimestamp:9.5f input:K14_INPUT_THRUST active:YES],
[[K14ActivateEvent alloc] initWithTimestamp:11.0f input:K14_INPUT_THRUST active:NO],
];
// Create game instance
K14Game *game = [[K14Game alloc] initWithInputEvents:action_replay];Obviously, a single-shot non-repeating list of events of only 2 different types is a little limited, but it will do for now. I can foresee building up the action replay class though, maybe not just for debugging, but also to make gameplay recordings, for example for funky replay effects like the ones in Super Meat Boy :-)
Development scoreboard
Refactoring the data model classes to add the K14Game class and writing
the action-replay classes took a little more time than I had expected,
about 4 hours of my flight to San Francisco, and another 3 more afterwards.
This brings the total amount of development time to about 19 hours. The
current SLOC count is now 539, an increase of 200 since the last post, most
of which is in the replay handling.