The Game Loop (The Chickadee Game Toolkit)

From e7d470e954d0a17ab1b2fe0065f46f78475272f9 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Wed, 8 Apr 2020 17:10:29 -0400 Subject: Add chickade 0.5.0 stuff. --- manuals/chickadee/The-Game-Loop.html | 360 +++++++++++++++++++++++++++++++++++ 1 file changed, 360 insertions(+) create mode 100644 manuals/chickadee/The-Game-Loop.html (limited to 'manuals/chickadee/The-Game-Loop.html') diff --git a/manuals/chickadee/The-Game-Loop.html b/manuals/chickadee/The-Game-Loop.html new file mode 100644 index 0000000..138dca3 --- /dev/null +++ b/manuals/chickadee/The-Game-Loop.html @@ -0,0 +1,360 @@ + + + + + + +The Game Loop (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + + +

2.1.1 The Game Loop

+ +

At the very core of Chickadee there is an event loop. This loop, or +“kernel”, is responsible for ensuring that the game is updated at +the desired interval, handling input devices, 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. +

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. +

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. +
+

+ +

To stop the game loop, simply call abort-game. +

Procedure: abort-game: Stop the currently running Chickadee game loop. +

+ +

The above explanation of the game loop was partially a lie. It’s true +that there is a game loop at the center of Chickadee, but +run-game is not it’s true entry point. There exists an even +lower level procedure, run-game*, in the (chickadee +game-loop) module that run-game uses under the hood. +

On its own, run-game* does not do very much at all. In order +to actually respond to input events, update game state, or render +output, the developer must provide an engine. run-game is such +an engine, and it’s likely all a developer will need. However, what +if a developer wanted to use all of the useful Chickadee features to +make a terminal roguelike game instead? Chickadee doesn’t come with a +terminal rendering engine, but the developer could write one without +having to write their own core game loop. +

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. +

+ +

+ + + + + + -- cgit v1.2.3