diff options
Diffstat (limited to 'manuals/chickadee/The-Game-Loop.html')
| -rw-r--r-- | manuals/chickadee/The-Game-Loop.html | 360 |
1 files changed, 360 insertions, 0 deletions
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 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 2017-2020 David Thompson davet@gnu.org + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled "GNU +Free Documentation License". + +A copy of the license is also available from the Free Software +Foundation Web site at http://www.gnu.org/licenses/fdl.html. + + +* Chickadee: (chickadee). Game programming toolkit for Guile. + +The document was typeset with +http://www.texinfo.org/ (GNU Texinfo). + --> +<!-- Created by GNU Texinfo 6.6, http://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<title>The Game Loop (The Chickadee Game Toolkit)</title> + +<meta name="description" content="The Game Loop (The Chickadee Game Toolkit)"> +<meta name="keywords" content="The Game Loop (The Chickadee Game Toolkit)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index.html#Index" rel="index" title="Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Kernel.html#Kernel" rel="up" title="Kernel"> +<link href="Input-Devices.html#Input-Devices" rel="next" title="Input Devices"> +<link href="Kernel.html#Kernel" rel="prev" title="Kernel"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.indentedblock {margin-right: 0em} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +kbd {font-style: oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +span.nolinebreak {white-space: nowrap} +span.roman {font-family: initial; font-weight: normal} +span.sansserif {font-family: sans-serif; font-weight: normal} +ul.no-bullet {list-style: none} +@media (min-width: 1140px) { + body { + margin-left: 14rem; + margin-right: 4rem; + max-width: 52rem; + } +} + +@media (min-width: 800px) and (max-width: 1140px) { + body { + margin-left: 6rem; + margin-right: 4rem; + max-width: 52rem; + } +} + +@media (max-width: 800px) { + body { + margin: 1rem; + } +} + +--> +</style> +<link rel="stylesheet" type="text/css" href="https://dthompson.us/css/dthompson.css"> + + +</head> + +<body lang="en"> +<span id="The-Game-Loop"></span><div class="header"> +<p> +Next: <a href="Input-Devices.html#Input-Devices" accesskey="n" rel="next">Input Devices</a>, Up: <a href="Kernel.html#Kernel" accesskey="u" rel="up">Kernel</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<span id="The-Game-Loop-1"></span><h4 class="subsection">2.1.1 The Game Loop</h4> + +<p>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 <code>run-game</code> and +<code>abort-game</code> procedures are the entry and exit points to the +Chickadee game loop. +</p> +<dl> +<dt id="index-run_002dgame">Procedure: <strong>run-game</strong> <em>[#:window-title "Chickadee!"] [#:window-width 640] [#:window-height 480] [#:window-fullscreen? <code>#f</code>] [#: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]</em></dt> +<dd> +<p>Run the Chickadee game loop. +</p> +<p>A new graphical window will be opened with <var>window-width</var> x +<var>window-height</var> as its dimensions, <var>window-title</var> as its +title, and in fullscreen mode if <var>window-fullscreen?</var> is +<code>#t</code>. +</p> +<ul> +<li> <var>load</var>: 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. + +</li><li> <var>update</var>: Called <var>update-hz</var> times per second with one +argument: The amount of time to advance the game simulation. + +</li><li> <var>draw</var>: Called each time a frame should be rendered with a single +argument known as the <code>alpha</code> value. See the documentation for +<code>run-game</code> for an explanation of this value. + +</li><li> <var>quit</var>: Called with zero arguments when the user tries to close +the game window. The default behavior is to exit the game. + +</li><li> <var>key-press</var>: Called with four arguments when a key is pressed on +the keyboard: + +<ol> +<li> <var>key</var>: The symbolic name of the “virtual” key that was pressed. +For example: <code>backspace</code>. 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”. + +</li><li> <var>scancode</var>: The symbolic name of the physical key that was +pressed. + +</li><li> <var>modifiers</var>: A list of the symbolic names of modifier keys that +were being held down when the key was pressed. Possible values +include <code>ctrl</code>, <code>alt</code>, and <code>shift</code>. + +</li><li> <var>repeat?</var>: <code>#t</code> if this is a repeated press of the same key. + +</li></ol> + +</li><li> <var>key-release</var>: Called with three arguments when a key is released +on the keyboard: + +<ol> +<li> <var>key</var>: The symbolic name of the “virtual” key that was released. + +</li><li> <var>scancode</var>: The symbolic name of the physical key that was +released. + +</li><li> <var>modifiers</var>: A list of the symbolic names of modifier keys that +were being held down when the key was released. + +</li></ol> + +</li><li> <var>text-input</var>: Called with a single argument, a string of text, +when printable text is typed on the keyboard. + +</li><li> <var>mouse-press</var>: Called with four arguments when a mouse button is +pressed: +<ol> +<li> <var>button</var>: The symbolic name of the button that was pressed, such +as <code>left</code>, <code>middle</code>, or <code>right</code>. + +</li><li> <var>clicks</var>: The number of times the button has been clicked in a row. + +</li><li> <var>x</var>: The x coordinate of the mouse cursor. + +</li><li> <var>y</var>: The y coordinate of the mouse cursor. + +</li></ol> + +</li><li> <var>mouse-release</var>: Called with three arguments when a mouse button +is released: + +<ol> +<li> <var>button</var>: The symbolic name of the button that was released. + +</li><li> <var>x</var>: The x coordinate of the mouse cursor. + +</li><li> <var>y</var>: The y coordinate of the mouse cursor. + +</li></ol> + +</li><li> <var>mouse-move</var>: Called with five arguments when the mouse is moved: + +<ol> +<li> <var>x</var>: The x coordinate of the mouse cursor. + +</li><li> <var>y</var>: The y coordinate of the mouse cursor. + +</li><li> <var>dx</var>: The amount the mouse has moved along the x axis since the +last mouse move event. + +</li><li> <var>dy</var>: The amount the mouse has moved along the y axis since the +last mouse move event. + +</li><li> <var>buttons</var>: A list of the buttons that were pressed down when the +mouse was moved. + +</li></ol> + +</li><li> <var>controller-add</var>: Called with a single argument, an SDL game +controller object, when a game controller is connected. + +</li><li> <var>controller-remove</var>: Called with a single argument, an SDL game +controller object, when a game controller is disconnected. + +</li><li> <var>controller-press</var>: Called with two arguments when a button on a +game controller is pressed: + +<ol> +<li> <var>controller</var>: The controller that triggered the event. + +</li><li> <var>button</var>: The symbolic name of the button that was pressed. +Possible buttons are: + +<ul> +<li> <code>a</code> +</li><li> <code>b</code> +</li><li> <code>x</code> +</li><li> <code>y</code> +</li><li> <code>back</code> +</li><li> <code>guide</code> +</li><li> <code>start</code> +</li><li> <code>left-stick</code> +</li><li> <code>right-stick</code> +</li><li> <code>left-shoulder</code> +</li><li> <code>right-shoulder</code> +</li><li> <code>dpad-up</code> +</li><li> <code>dpad-down</code> +</li><li> <code>dpad-left</code> +</li><li> <code>dpad-right</code> + +</li></ul> + +</li></ol> + +</li><li> <var>controller-release</var>: Called with two arguments when a button on a +game controller is released: + +<ol> +<li> <var>controller</var>: The controller that triggered the event. + +</li><li> <var>button</var>: The symbolic name of the button that was released. + +</li></ol> + +</li><li> <var>controller-move</var>: Called with three arguments when an analog +stick or trigger on a game controller is moved: + +<ol> +<li> <var>controller</var>: The controller that triggered the event. + +</li><li> <var>axis</var>: The symbolic name of the axis that was moved. Possible +values are: + +<ul> +<li> <code>left-x</code> +</li><li> <code>left-y</code> +</li><li> <code>right-x</code> +</li><li> <code>right-y</code> +</li><li> <code>trigger-left</code> +</li><li> <code>trigger-right</code> +</li></ul> + +</li></ol> + +</li><li> <var>error</var>: Called with three arguments when an error occurs: + +<ol> +<li> <var>stack</var>: The call stack at the point of error. + +</li><li> <var>key</var>: The exception key. + +</li><li> <var>args</var>: The arguments thrown with the exception. + +</li></ol> + +<p>The default behavior is to re-throw the error. +</p> +</li></ul> + +</dd></dl> + +<p>To stop the game loop, simply call <code>abort-game</code>. +</p> +<dl> +<dt id="index-abort_002dgame">Procedure: <strong>abort-game</strong></dt> +<dd><p>Stop the currently running Chickadee game loop. +</p></dd></dl> + +<p>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 +<code>run-game</code> is not it’s true entry point. There exists an even +lower level procedure, <code>run-game*</code>, in the <code>(chickadee +game-loop)</code> module that <code>run-game</code> uses under the hood. +</p> +<p>On its own, <code>run-game*</code> 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. <code>run-game</code> 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. +</p> +<dl> +<dt id="index-run_002dgame_002a">Procedure: <strong>run-game*</strong> <em>[#:update] [#:render] [#:time] [#:error] [#:update-hz 60]</em></dt> +<dd> +<p>Start the game loop. This procedure will not return until +<code>abort-game</code> is called. +</p> +<p>The core game loop is generic and requires four additional procedures +to operate: +</p> +<ul> +<li> <var>update</var>: Called <var>update-hz</var> 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. +</li><li> <var>render</var>: 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 +<var>alpha</var> 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. +</li><li> <var>time</var>: Called to get the current time in milliseconds. This +procedure is called with no arguments. +</li><li> <var>error</var>: Called when an error from the <var>update</var> or +<var>render</var> 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. +</li></ul> + +</dd></dl> + +<hr> +<div class="header"> +<p> +Next: <a href="Input-Devices.html#Input-Devices" accesskey="n" rel="next">Input Devices</a>, Up: <a href="Kernel.html#Kernel" accesskey="u" rel="up">Kernel</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |