summaryrefslogtreecommitdiff
path: root/manuals/chickadee/Kernel.html
diff options
context:
space:
mode:
Diffstat (limited to 'manuals/chickadee/Kernel.html')
-rw-r--r--manuals/chickadee/Kernel.html416
1 files changed, 416 insertions, 0 deletions
diff --git a/manuals/chickadee/Kernel.html b/manuals/chickadee/Kernel.html
new file mode 100644
index 0000000..c9d635b
--- /dev/null
+++ b/manuals/chickadee/Kernel.html
@@ -0,0 +1,416 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Copyright (C) 2017 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.
+
+
+The document was typeset with
+http://www.texinfo.org/ (GNU Texinfo).
+ -->
+<!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
+<head>
+<title>The Chickadee Game Toolkit: Kernel</title>
+
+<meta name="description" content="The Chickadee Game Toolkit: Kernel">
+<meta name="keywords" content="The Chickadee Game Toolkit: Kernel">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<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="API-Reference.html#API-Reference" rel="up" title="API Reference">
+<link href="Input.html#Input" rel="next" title="Input">
+<link href="API-Reference.html#API-Reference" rel="prev" title="API Reference">
+<style type="text/css">
+<!--
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
+blockquote.smallquotation {font-size: smaller}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+div.lisp {margin-left: 3.2em}
+div.smalldisplay {margin-left: 3.2em}
+div.smallexample {margin-left: 3.2em}
+div.smalllisp {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}
+pre.smalldisplay {font-family: inherit; font-size: smaller}
+pre.smallexample {font-size: smaller}
+pre.smallformat {font-family: inherit; font-size: smaller}
+pre.smalllisp {font-size: smaller}
+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}
+-->
+</style>
+
+
+</head>
+
+<body lang="en">
+<a name="Kernel"></a>
+<div class="header">
+<p>
+Next: <a href="Input.html#Input" accesskey="n" rel="next">Input</a>, Up: <a href="API-Reference.html#API-Reference" accesskey="u" rel="up">API Reference</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>
+<a name="Kernel-1"></a>
+<h3 class="section">2.1 Kernel</h3>
+
+<p>At the very core of Chickadee, in the <code>(chickadee)</code> module, lies
+an event loop. This loop, or &ldquo;kernel&rdquo;, 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 &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 kernel.
+</p>
+<p>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 &ldquo;hooks&rdquo;,
+and specify what action ought to be taken for any given event. For
+example, the <code>key-press-hook</code> can be used to respond to the
+<code>a</code> key being pressed by swinging the player&rsquo;s mighty sword.
+There are many hooks available, so read on to learn about all of them.
+For information about using Guile&rsquo;s hook API, see See <a href="http://www.gnu.org/software/guile/manual/html_node/Hooks.html#Hooks">Hooks</a> in <cite>GNU Guile Reference Manual</cite>.
+</p>
+<dl>
+<dt><a name="index-run_002dgame"></a>Scheme Procedure: <strong>run-game</strong> <em>[#:window-title &quot;Chickadee!&quot;]</em></dt>
+<dd><p>[#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f]
+ [#:update-hz 60]
+Start the event loop. This procedure will not return until
+<code>abort-game</code> is called.
+</p>
+<p>The <code>update-hook</code> will be run <var>update-hz</var> times per second.
+</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></dd></dl>
+
+<dl>
+<dt><a name="index-abort_002dgame"></a>Scheme Procedure: <strong>abort-game</strong></dt>
+<dd><p>Stop the currently running Chickadee event loop.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-time"></a>Scheme Procedure: <strong>time</strong></dt>
+<dd><p>Return the current game time in milliseconds.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-load_002dhook"></a>Scheme Variable: <strong>load-hook</strong></dt>
+<dd><p>A hook that is run once when the event loop boots, before any other
+hook is run. This hook is run with zero arguments.
+</p>
+<div class="example">
+<pre class="example">(add-hook! load-hook (lambda () (display &quot;hello!\n&quot;)))
+</pre></div>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-update_002dhook"></a>Scheme Variable: <strong>update-hook</strong></dt>
+<dd><p>A hook that is run every time the game simulation should be advanced.
+This hook is run with a single argument <var>dt</var>, the fixed timestep
+that was configured when the event loop was started, in milliseconds.
+</p>
+<div class="example">
+<pre class="example">(add-hook! update-hook (lambda (dt) (display &quot;tick!\n&quot;)))
+</pre></div>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-before_002ddraw_002dhook"></a>Scheme Variable: <strong>before-draw-hook</strong></dt>
+<dd><p>A hook that is run before a frame is rendered. This hook is run with
+zero arguments.
+</p>
+<div class="example">
+<pre class="example">(add-hook! before-draw-hook (lambda () (display &quot;about to draw!\n&quot;)))
+</pre></div>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-after_002ddraw_002dhook"></a>Scheme Variable: <strong>after-draw-hook</strong></dt>
+<dd><p>A hook that is run after a frame is rendered. This hook is run with
+zero arguments.
+</p>
+<div class="example">
+<pre class="example">(add-hook! after-draw-hook (lambda () (display &quot;done drawing!\n&quot;)))
+</pre></div>
+
+<p>Combined with <code>before-draw-hook</code>, one can perform a frames per
+second calculation to monitor game performance and stability.
+</p>
+</dd></dl>
+
+<dl>
+<dt><a name="index-draw_002dhook"></a>Scheme Variable: <strong>draw-hook</strong></dt>
+<dd><p>A hook that is run each time a frame should be rendered. This hook is
+run with a single argument <var>alpha</var>, 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.
+</p>
+
+<div class="example">
+<pre class="example">(add-hook! draw-hook (lambda (alpha) (display &quot;&lt;(._.&lt;) \n&quot;)))
+</pre></div>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-quit_002dhook"></a>Scheme Variable: <strong>quit-hook</strong></dt>
+<dd><p>A hook that is run when the user clicks the close button on the game
+window. This hook is run with zero arguments.
+</p>
+<div class="example">
+<pre class="example">(add-hook! quit-hook (lambda () (display &quot;bye!\n&quot;)))
+</pre></div>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-key_002dpress_002dhook"></a>Scheme Variable: <strong>key-press-hook</strong></dt>
+<dd><p>A hook that is run when a key is pressed on the keyboard. This hook
+is run with four arguments:
+</p>
+<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 binds 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>
+
+<div class="example">
+<pre class="example">(add-hook! key-press-hook
+ (lambda (key scancode modifiers repeat?)
+ (display &quot;pressed key: &quot;)
+ (display key)
+ (newline)))
+</pre></div>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-key_002drelease_002dhook"></a>Scheme Variable: <strong>key-release-hook</strong></dt>
+<dd><p>A hook that is run when a key is released on the keyboard. This hook
+is run with three arguments:
+</p>
+<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>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-text_002dinput_002dhook"></a>Scheme Variable: <strong>text-input-hook</strong></dt>
+<dd><p>A hook that is run when printable text is typed on the keyboard. This
+hook is run with a single argument, <var>text</var>, a string containing
+the text that was entered.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-mouse_002dpress_002dhook"></a>Scheme Variable: <strong>mouse-press-hook</strong></dt>
+<dd><p>A hook that is run when a mouse button is pressed. This hook is run
+with four arguments:
+</p>
+<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>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-mouse_002drelease_002dhook"></a>Scheme Variable: <strong>mouse-release-hook</strong></dt>
+<dd><p>A hook that is run when a mouse button is released. This hook is run
+with three arguments:
+</p>
+<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>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-mouse_002dmove_002dhook"></a>Scheme Variable: <strong>mouse-move-hook</strong></dt>
+<dd><p>A hook that is run when the mouse is moved. This hook is run with
+five arguments:
+</p>
+<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>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-controller_002dadd_002dhook"></a>Scheme Variable: <strong>controller-add-hook</strong></dt>
+<dd><p>A hook that is run when a game controller is connected. This hook is
+run with a single argument, <var>controller</var>, the controller that was
+connected.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-controller_002dremove_002dhook"></a>Scheme Variable: <strong>controller-remove-hook</strong></dt>
+<dd><p>A hook that is run when a game controller is disconnected. This hook
+is run with a single argument, <var>controller</var>, the controller that
+was disconnected.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-controller_002dpress_002dhook"></a>Scheme Variable: <strong>controller-press-hook</strong></dt>
+<dd><p>A hook that is run when a button on a game controller is pressed.
+This hook is run with two arguments:
+</p>
+<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>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-controller_002drelease_002dhook"></a>Scheme Variable: <strong>controller-release-hook</strong></dt>
+<dd><p>A hook that is run when a button on a game controller is released.
+</p>
+<p>This hook is run with two arguments:
+</p>
+<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>
+
+</dd></dl>
+
+<dl>
+<dt><a name="index-controller_002dmove_002dhook"></a>Scheme Variable: <strong>controller-move-hook</strong></dt>
+<dd><p>A hook that is run when an analog stick or trigger on a game
+controller is moved. This hook is run with three arguments
+</p>
+<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>
+
+</dd></dl>
+
+<hr>
+<div class="header">
+<p>
+Next: <a href="Input.html#Input" accesskey="n" rel="next">Input</a>, Up: <a href="API-Reference.html#API-Reference" accesskey="u" rel="up">API Reference</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>