2.1 Kernel

At the very core of Chickadee, in the (chickadee game-loop) module, lies an event loop. This loop, or “kernel”, is responsible for ensuring that the game is updated at the desired interval, rendering the current state of the game world, and handling errors if they occur. 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 game loop 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 render output, the programmer must provide an engine. But don’t worry, you don’t have to start from scratch! Chickadee comes with a simple engine that uses SDL to create a graphical window and handle input devices, and OpenGL to handle rendering. This default engine is enough for most users to get started writing games quickly. More advanced users may want to write a custom engine that uses a different I/O system. Perhaps you are writing a text adventure or roguelike that reads from and writes to a terminal instead of a graphical window. The game loop kernel makes no assumptions.

Procedure: run-game [#:update] [#:render] [#:time] [#:error] [#:update-hz 60]

Start the game loop. This procedure will not return until abort-game is called.

The core game loop is generic and requires four additional procedures to operate:

• update: Called update-hz times per second to advance the game simulation. This procedure is called with a single argument: The amount of time that has passed since the last update, in milliseconds.
• render: Called each iteration of the loop to render the game to the desired output device. This procedure is called with a single argument: 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.
• time: Called to get the current time in milliseconds. This procedure is called with no arguments.
• error: Called when an error from the update or render procedures reaches the game loop. This procedure is called with three arguments: The call stack, the error key, and the error arguments. If no error handler is provided, the default behavior is to simply re-throw the error.

Procedure: abort-game

Stop the currently running Chickadee game loop.

Since most users will want to write 2D/3D games with hardware accelerated graphics rendering, controlled via keyboard, mouse, or game controller, Chickadee comes with an easy to use engine just for this purpose in the (chickadee) module: run-game.

Procedure: run-game [#:window-title "Chickadee!"] [#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f] [#:update-hz 60] [#:load] [#:update] [#:draw] [#:quit] [#:key-press] [#:key-release] [#:text-input] [#:mouse-press] [#:mouse-release] [#:mouse-move] [#:controller-add] [#:controller-remove] [#:controller-press] [#:controller-release] [#:controller-move] [#:error]

Run the Chickadee game loop using the SDL engine in OpenGL mode.

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.

• load: Called with zero arguments when the game window has opened but before the game loop has started. Can be used to perform initialization that requires an open window and OpenGL context such as loading textures.
• update: Called update-hz times per second with one argument: The amount of time to advance the game simulation.
• draw: Called each time a frame should be rendered with a single argument known as the alpha value. See the documentation for run-game for an explanation of this value.
• quit: Called with zero arguments when the user tries to close the game window. The default behavior is to exit the game.
• key-press: Called with four arguments when a key is pressed on the keyboard:
  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 likes to bind 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.
• key-release: Called with three arguments when a key is released on the keyboard:
  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.
• text-input: Called with a single argument, a string of text, when printable text is typed on the keyboard.
• mouse-press: Called with four arguments when a mouse button is pressed:
  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.
• mouse-release: Called with three arguments when a mouse button is released:
  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.
• mouse-move: Called with five arguments when the mouse is moved:
  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.
• controller-add: Called with a single argument, an SDL game controller object, when a game controller is connected.
• controller-remove: Called with a single argument, an SDL game controller object, when a game controller is disconnected.
• controller-press: Called with two arguments when a button on a game controller is pressed:
  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
• controller-release: Called with two arguments when a button on a game controller is released:
  1. controller: The controller that triggered the event.
  2. button: The symbolic name of the button that was released.
• controller-move: Called with three arguments when an analog stick or trigger on a game controller is moved:
  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
• error: Called with three arguments when an error occurs:
  1. stack: The call stack at the point of error.
  2. key: The exception key.
  3. args: The arguments thrown with the exception.

  The default behavior is to re-throw the error.

2.1.1 Live Coding

One of the biggest appeals of any Lisp dialect is the ability to use the “read-eval-print loop” (REPL for short) to build programs iteratively and interactively while the program is running. However, programs that run in an event loop and respond to user input (such as a video game) require special care for this workflow to be pleasant. Chickadee provides no built-in support for live coding, but it’s fairly easy to hook up a special kind of REPL yourself.

First, create a cooperative REPL server (It’s important to use Guile’s cooperative REPL server instead of the standard REPL server in (system repl server) to avoid thread synchronization issues):

(use-modules (system repl coop-server))

(define repl (spawn-coop-repl-server))

Then, in the game loop’s update procedure, add this:

(poll-coop-repl-server repl)

To use the REPL, connect to it via port 37146. Telnet will do the trick, but using the Geiser extension for Emacs is by far the best way to develop at the REPL with Guile. Use M-x connect-to-guile to connect to the REPL server.

Happy hacking!