THIS PAGE IS UNDER CONSTRUCTION.

How to write a game with the game framework

The game framework provides a game template so you don't have to write all the code from scratch. the game framework also provides some utility modules and classes so that you can make a game in shorter time. See Mini Game Tutorial for more detail about making a game with the game framework.

Game Template

The game framework provides the game template. This template is a skeleton code for a game that does nothing but shows a text message.

Mechanisms behind the template

State transition

When a game is selected at the main title, the main title will change the state into the initial state defined in a subclass of Game (in this case NewGamePlayingState that is defined in NewGame). The framework invokes NewGamePlayingState.enter() .

Event handling

Events in this framework are different from the ones in the original Cocoa framework as I want to simplify the event handling mechanisms. Moreover, this framework saves you from writing many similar code as it already implements such common code.

Initialization - Event handling configuration

First, this method initializes its relevant model (already stored in instance variable @model) by invoking @model.init(). Second, it configures the event handling by invoking EventContext.setContexts and/or XXXEvent.addListener. EventContext is one of the main differences from the original Cocoa's event handling. EventContext connects an event with a designated method more actively. Unlike XXXEvent.addListener (which is well-known in Java), you can designate any method as an event receiver. Moreover, you can receive different key events at different methods. For example, you can receive "space key" event with select() method and "Ctrl-Q" key with quit() method. With this mechanism, you don't have to write switch-case statements so the code can become simpler.

In the NewGamePlaying state, it invokes EventContext.setContexts to receive timer events (whose id is NEWGAME_TIMER) and KeyDown event (Ctrl-Q) via tick() and quit() respectively.

For compatibility, you can also use keyDown(), keyUp() methods like other Cocoa applications. The enter method in State class (super class) automatically invokes XXXEvent.addListener if you define these methods (other than timer receiver).

In NewGamePlayingState.enter() method, it registers event contexts as:

contexts = [[NSKeyDown, [KeyEvent::KEY_Q, KeyEvent::WITH_CONTROL], proc{|event| quit() }],
                [TimerEvent::Fired, NEWGAME_TIMER, proc {|id| tick() }]]
EventContext.setContexts(contexts)

The first two lines define the contexts with an Array and the last line registers it. Each context includes:

• event type (e.g. NSKeyDown, TimerEvent::Fired)
• content (e.g. KeyEvent::KEY_Q, KeyEvent::WITH_CONTROL)
• event receiver (e.g. quit(), tick())

Timer Event

Timer event is a little different from the one in Cocoa. As NSTimer doesn't use NSEvent, TimerEvent in this framework make TimerEvent look like other Event classes. it has addListener and removeListener methods like KeyEvent and MouseEvent. It also provides EventContext based event delivering mechanisms.

In addition, it provides some workarounds to avoid some problems in using NSTimer. for example, when you call NSTimer.invalidate() from the timer callback routine, it may crash your application. With this game framework, however, this problem doesn't occur because TimerEvent provides some trick to go around to this problem.

Another difference between TimerEvent and NSTimer is that the former requires a timer ID simply because the framework enables you to register timer receiver before creating a timer.

Anyway, the NewGameState registers an event context like:

[TimerEvent::Fired, NEWGAME_TIMER, proc {|id| tick() }]

This means when TimerEvent (ID = NEWGAME_TIMER) fires, NewGameState.tick() method will be called.