Add chickade 0.5.0 stuff.

author: David Thompson <dthompson@vistahigherlearning.com> 2020-04-08 17:10:29 -0400
committer: David Thompson <dthompson@vistahigherlearning.com> 2020-04-08 17:10:29 -0400
commit: e7d470e954d0a17ab1b2fe0065f46f78475272f9 (patch)
tree: ca4d9c00789f41dbbdbac33151824812dad879f7 /manuals/chickadee/The-Game-Loop.html
parent: b660cbb5287f7cdcb6cebaba72afe8fc7d512616 (diff)
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> &nbsp; [<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
+&ldquo;kernel&rdquo;, 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 &ldquo;fixed timestep&rdquo; 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 &quot;Chickadee!&quot;]        [#: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 &ldquo;virtual&rdquo; key that was pressed.
+For example: <code>backspace</code>.  It&rsquo;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 &ldquo;caps lock&rdquo; key
+to mean &ldquo;control&rdquo;.
+
+</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 &ldquo;virtual&rdquo; 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&rsquo;s true
+that there is a game loop at the center of Chickadee, but
+<code>run-game</code> is not it&rsquo;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&rsquo;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&rsquo;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 &ldquo;choppy&rdquo;.  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> &nbsp; [<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>
author	David Thompson <dthompson@vistahigherlearning.com>	2020-04-08 17:10:29 -0400
committer	David Thompson <dthompson@vistahigherlearning.com>	2020-04-08 17:10:29 -0400
commit	e7d470e954d0a17ab1b2fe0065f46f78475272f9 (patch)
tree	ca4d9c00789f41dbbdbac33151824812dad879f7 /manuals/chickadee/The-Game-Loop.html
parent	b660cbb5287f7cdcb6cebaba72afe8fc7d512616 (diff)