diff options
Diffstat (limited to 'manuals/chickadee/Kernel.html')
| -rw-r--r-- | manuals/chickadee/Kernel.html | 416 |
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> [<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 “kernel”, 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 “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 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 “hooks”, +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’s mighty sword. +There are many hooks available, so read on to learn about all of them. +For information about using Guile’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 "Chickadee!"]</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 "hello!\n"))) +</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 "tick!\n"))) +</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 "about to draw!\n"))) +</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 "done drawing!\n"))) +</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 +“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. +</p> + +<div class="example"> +<pre class="example">(add-hook! draw-hook (lambda (alpha) (display "<(._.<) \n"))) +</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 "bye!\n"))) +</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 “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 binds 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> + +<div class="example"> +<pre class="example">(add-hook! key-press-hook + (lambda (key scancode modifiers repeat?) + (display "pressed key: ") + (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 “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> + +</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> [<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> |