2.1 Kernel

At the very core of Chickadee, in the (chickadee) module, lies an event loop. This loop, or “kernel”, is responsible for creating and managing the game window, dispatching input events, ensuring that the game is updated at the desired interval, and rendering graphics. The kernel implements what is known as a “fixed timestep” game loop, meaning that the game simulation will be advanced by a fixed interval of time and will never vary from frame to frame, unlike some other styles of game loops. The appropriately named run-game and abort-game procedures are the entry and exit points to the Chickadee kernel.

On its own, the kernel does not do very much at all. In order to actually respond to input events, update game state, or draw something to the game window, a hacker with a penchant for game development must latch onto extension points built into the kernel, called “hooks”, and specify what action ought to be taken for any given event. For example, the key-press-hook can be used to respond to the a key being pressed by swinging the player’s mighty sword. There are many hooks available, so read on to learn about all of them. For information about using Guile’s hook API, see See Hooks in GNU Guile Reference Manual.

Scheme Procedure: run-game [#:window-title "Chickadee!"]

[#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f] [#:update-hz 60] Start the event loop. This procedure will not return until abort-game is called.

The update-hook will be run update-hz times per second.

A new graphical window will be opened with window-width x window-height as its dimensions, window-title as its title, and in fullscreen mode if window-fullscreen? is #t.

Scheme Procedure: abort-game

Stop the currently running Chickadee event loop.

Scheme Procedure: time

Return the current game time in milliseconds.

Scheme Variable: load-hook

A hook that is run once when the event loop boots, before any other hook is run. This hook is run with zero arguments.

(add-hook! load-hook (lambda () (display "hello!\n")))

Scheme Variable: update-hook

A hook that is run every time the game simulation should be advanced. This hook is run with a single argument dt, the fixed timestep that was configured when the event loop was started, in milliseconds.

(add-hook! update-hook (lambda (dt) (display "tick!\n")))

Scheme Variable: before-draw-hook

A hook that is run before a frame is rendered. This hook is run with zero arguments.

(add-hook! before-draw-hook (lambda () (display "about to draw!\n")))

Scheme Variable: after-draw-hook

A hook that is run after a frame is rendered. This hook is run with zero arguments.

(add-hook! after-draw-hook (lambda () (display "done drawing!\n")))

Combined with before-draw-hook, one can perform a frames per second calculation to monitor game performance and stability.

Scheme Variable: draw-hook

A hook that is run each time a frame should be rendered. This hook is run with a single argument alpha, a value in the range [0, 1] which represents how much time has past since the last game state update relative to the upcoming game state update, as a percentage. Because the game state is updated independent of rendering, it is often the case that rendering is occuring between two updates. If the game is rendered as it was during the last update, a strange side-effect will occur that makes animation appear rough or “choppy”. To counter this, the alpha value can be used to perfrom a linear interpolation of a moving object between its current position and its previous position. This odd trick has the pleasing result of making the animation look smooth again, but requires keeping track of previous state.

(add-hook! draw-hook (lambda (alpha) (display "<(._.<) \n")))

Scheme Variable: quit-hook

A hook that is run when the user clicks the close button on the game window. This hook is run with zero arguments.

(add-hook! quit-hook (lambda () (display "bye!\n")))

Scheme Variable: key-press-hook

A hook that is run when a key is pressed on the keyboard. This hook is run with four arguments:

1. key: The symbolic name of the “virtual” key that was pressed. For example: backspace. It’s called a virtual key because the operating system may map a physical keyboard key to another key entirely, such as how the author binds the “caps lock” key to mean “control”.
2. scancode: The symbolic name of the physical key that was pressed.
3. modifiers: A list of the symbolic names of modifier keys that were being held down when the key was pressed. Possible values include ctrl, alt, and shift.
4. repeat?: #t if this is a repeated press of the same key.

(add-hook! key-press-hook
           (lambda (key scancode modifiers repeat?)
             (display "pressed key: ")
             (display key)
             (newline)))

Scheme Variable: key-release-hook

A hook that is run when a key is released on the keyboard. This hook is run with three arguments:

1. key: The symbolic name of the “virtual” key that was released.
2. scancode: The symbolic name of the physical key that was released.
3. modifiers: A list of the symbolic names of modifier keys that were being held down when the key was released.

Scheme Variable: text-input-hook

A hook that is run when printable text is typed on the keyboard. This hook is run with a single argument, text, a string containing the text that was entered.

Scheme Variable: mouse-press-hook

A hook that is run when a mouse button is pressed. This hook is run with four arguments:

1. button: The symbolic name of the button that was pressed, such as left, middle, or right.
2. clicks: The number of times the button has been clicked in a row.
3. x: The x coordinate of the mouse cursor.
4. y: The y coordinate of the mouse cursor.

Scheme Variable: mouse-release-hook

A hook that is run when a mouse button is released. This hook is run with three arguments:

1. button: The symbolic name of the button that was released.
2. x: The x coordinate of the mouse cursor.
3. y: The y coordinate of the mouse cursor.

Scheme Variable: mouse-move-hook

A hook that is run when the mouse is moved. This hook is run with five arguments:

1. x: The x coordinate of the mouse cursor.
2. y: The y coordinate of the mouse cursor.
3. dx: The amount the mouse has moved along the x axis since the last mouse move event.
4. dy: The amount the mouse has moved along the y axis since the last mouse move event.
5. buttons: A list of the buttons that were pressed down when the mouse was moved.

Scheme Variable: controller-add-hook

A hook that is run when a game controller is connected. This hook is run with a single argument, controller, the controller that was connected.

Scheme Variable: controller-remove-hook

A hook that is run when a game controller is disconnected. This hook is run with a single argument, controller, the controller that was disconnected.

Scheme Variable: controller-press-hook

A hook that is run when a button on a game controller is pressed. This hook is run with two arguments:

1. controller: The controller that triggered the event.
2. button: The symbolic name of the button that was pressed. Possible buttons are:
   • a
   • b
   • x
   • y
   • back
   • guide
   • start
   • left-stick
   • right-stick
   • left-shoulder
   • right-shoulder
   • dpad-up
   • dpad-down
   • dpad-left
   • dpad-right

Scheme Variable: controller-release-hook

A hook that is run when a button on a game controller is released.

This hook is run with two arguments:

1. controller: The controller that triggered the event.
2. button: The symbolic name of the button that was released.

Scheme Variable: controller-move-hook

A hook that is run when an analog stick or trigger on a game controller is moved. This hook is run with three arguments

1. controller: The controller that triggered the event.
2. axis: The symbolic name of the axis that was moved. Possible values are:
   • left-x
   • left-y
   • right-x
   • right-y
   • trigger-left
   • trigger-right