diff options
| 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/Kernel.html | |
| parent | b660cbb5287f7cdcb6cebaba72afe8fc7d512616 (diff) | |
Add chickade 0.5.0 stuff.
Diffstat (limited to 'manuals/chickadee/Kernel.html')
| -rw-r--r-- | manuals/chickadee/Kernel.html | 331 |
1 files changed, 17 insertions, 314 deletions
diff --git a/manuals/chickadee/Kernel.html b/manuals/chickadee/Kernel.html index 01685d8..0faa3a6 100644 --- a/manuals/chickadee/Kernel.html +++ b/manuals/chickadee/Kernel.html @@ -1,6 +1,6 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> -<!-- Copyright (C) 2017, 2018, 2019 David Thompson davet@gnu.org +<!-- 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 @@ -18,7 +18,7 @@ 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.5, http://www.gnu.org/software/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>Kernel (The Chickadee Game Toolkit)</title> @@ -32,29 +32,20 @@ http://www.texinfo.org/ (GNU Texinfo). <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="Math.html#Math" rel="next" title="Math"> +<link href="The-Game-Loop.html#The-Game-Loop" rel="next" title="The Game Loop"> <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} @@ -89,315 +80,27 @@ ul.no-bullet {list-style: none} </head> <body lang="en"> -<a name="Kernel"></a> -<div class="header"> +<span id="Kernel"></span><div class="header"> <p> Next: <a href="Math.html#Math" accesskey="n" rel="next">Math</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> +<span id="Kernel-1"></span><h3 class="section">2.1 Kernel</h3> -<p>At the very core of Chickadee, in the <code>(chickadee game-loop)</code> -module, lies an event loop. This loop, or “kernel”, is responsible -for ensuring that the game is updated at the desired interval, -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 kernel. +<p>This section of the manual covers the foundation of Chickadee: The +game loop and desktop environment interaction. </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 render output, -the programmer must provide an engine. But don’t worry, you don’t -have to start from scratch! Chickadee comes with a simple engine that -uses SDL to create a graphical window and handle input devices, and -OpenGL to handle rendering. This default engine is enough for most -users to get started writing games quickly. More advanced users may -want to write a custom engine that uses a different I/O system. -Perhaps you are writing a text adventure or roguelike that reads from -and writes to a terminal instead of a graphical window. The game loop -kernel makes no assumptions. -</p> -<dl> -<dt><a name="index-run_002dgame_002a"></a>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> - -<dl> -<dt><a name="index-abort_002dgame"></a>Procedure: <strong>abort-game</strong></dt> -<dd><p>Stop the currently running Chickadee game loop. -</p></dd></dl> - -<p>Since most users will want to write 2D/3D games with hardware -accelerated graphics rendering, controlled via keyboard, mouse, or -game controller, Chickadee comes with an easy to use engine just for -this purpose in the <code>(chickadee)</code> module: <code>run-game</code>. -</p> -<dl> -<dt><a name="index-run_002dgame"></a>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 using the SDL engine in OpenGL mode. -</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. +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="The-Game-Loop.html#The-Game-Loop" accesskey="1">The Game Loop</a></td><td> </td><td align="left" valign="top">The core event loop. +</td></tr> +<tr><td align="left" valign="top">• <a href="Input-Devices.html#Input-Devices" accesskey="2">Input Devices</a></td><td> </td><td align="left" valign="top">Mouse, keyboard, controller input. +</td></tr> +<tr><td align="left" valign="top">• <a href="Window-Manipulation.html#Window-Manipulation" accesskey="3">Window Manipulation</a></td><td> </td><td align="left" valign="top">Inspect and modify the graphical window. +</td></tr> +<tr><td align="left" valign="top">• <a href="Live-Coding.html#Live-Coding" accesskey="4">Live Coding</a></td><td> </td><td align="left" valign="top">Tips for building games from the REPL. +</td></tr> +</table> -</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> - -<a name="Live-Coding"></a> -<h4 class="subsection">2.1.1 Live Coding</h4> - -<p>One of the biggest appeals of any Lisp dialect is the ability to use -the “read-eval-print loop” (REPL for short) to build programs -iteratively and interactively while the program is running. However, -programs that run in an event loop and respond to user input (such as -a video game) require special care for this workflow to be pleasant. -Chickadee provides no built-in support for live coding, but it’s -fairly easy to hook up a special kind of REPL yourself. -</p> -<p>First, create a cooperative REPL server (It’s important to use Guile’s -cooperative REPL server instead of the standard REPL server in -<code>(system repl server)</code> to avoid thread synchronization issues): -</p> -<div class="example"> -<pre class="example">(use-modules (system repl coop-server)) - -(define repl (spawn-coop-repl-server)) -</pre></div> - -<p>Then, in the game loop’s update procedure, add this: -</p> -<div class="example"> -<pre class="example">(poll-coop-repl-server repl) -</pre></div> - -<p>To use the REPL, connect to it via port 37146. Telnet will do the -trick, but using the <a href="https://www.nongnu.org/geiser/">Geiser</a> -extension for Emacs is by far the best way to develop at the REPL with -Guile. Use <code>M-x connect-to-guile</code> to connect to the REPL server. -</p> -<p>Happy hacking! -</p> -<hr> -<div class="header"> -<p> -Next: <a href="Math.html#Math" accesskey="n" rel="next">Math</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> |