diff options
Diffstat (limited to 'manuals/chickadee/The-Game-Loop.html')
| -rw-r--r-- | manuals/chickadee/The-Game-Loop.html | 420 |
1 files changed, 0 insertions, 420 deletions
diff --git a/manuals/chickadee/The-Game-Loop.html b/manuals/chickadee/The-Game-Loop.html deleted file mode 100644 index 45a4d42..0000000 --- a/manuals/chickadee/The-Game-Loop.html +++ /dev/null @@ -1,420 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<!-- Copyright (C) 2017-2023 David Thompson dthompson2@worcester.edu - -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.7, 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" rel="start" title="Top" /> -<link href="Index.html" rel="index" title="Index" /> -<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents" /> -<link href="Kernel.html" rel="up" title="Kernel" /> -<link href="Input-Devices.html" rel="next" title="Input Devices" /> -<link href="Kernel.html" 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" accesskey="n" rel="next">Input Devices</a>, Up: <a href="Kernel.html" accesskey="u" rel="up">Kernel</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> -<hr /> -<span id="The-Game-Loop-1"></span><h4 class="subsection">5.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> -<p>If you are using <code>chickadee play</code> to launch your game, then -calling <code>run-game</code> is already taken care of for you. -</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>] [#:window-resizable? <code>#f</code>] [#:update-hz 60] [#:clear-color] [#: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] [#:window-keyboard-enter] [#:window-keyboard-leave] [#:window-mouse-enter] [#:window-mouse-leave] [#:window-show] [#:window-hide] [#:window-minimize] [#:window-maximize] [#:window-move] [#:window-resize] [#: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>. If <var>window-resizable?</var> is <code>#t</code> then the window -can be resized by the user. The screen color will be set to -<var>clear-color</var>, or a pleasant light blue, by default. -</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 key that was pressed. For -example: <code>backspace</code>. - -</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 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>mouse-wheel</var>: Called with two arguments when the mouse wheel is -scrolled: - -<ol> -<li> <var>x</var>: The scroll amount along the X axis. - -</li><li> <var>y</var>: The scroll amount along the Y axis. - -</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>window-keyboard-enter</var>: Called with zero arguments when the -window gains keyboard focus. - -</li><li> <var>window-keyboard-leave</var>: Called with zero arguments when the -window loses keyboard focus. - -</li><li> <var>window-mouse-enter</var>: Called with zero arguments when the window -gains mouse focus. - -</li><li> <var>window-mouse-leave</var>: Called with zero arguments when the window -loses mouse focus. - -</li><li> <var>window-show</var>: Called with zero arguments when the window is -shown after having been hidden. - -</li><li> <var>window-hide</var>: Called with zero arguments when the window is -hidden. - -</li><li> <var>window-minimize</var>: Called with zero arguments when the window is -minimized. - -</li><li> <var>window-maximize</var>: Called with zero arguments when the window is -maximized. - -</li><li> <var>window-move</var>: Called with two arguments when the window is moved -within the desktop environment. - -<ol> -<li> <var>x</var>: The x coordinate of the top-left corner of the window, in -pixels. - -</li><li> <var>y</var>: The y coordinate of the top-left corner of the window, in -pixels. - -</li></ol> - -<p>Desktop environments use the top-left corner as the origin rather than -the bottom-left like Chickadee does, hence the discrepancy here. -</p> -</li><li> <var>window-resize</var>: Called with zero arguments when the window is -resized. - -<ol> -<li> <var>width</var>: The new width in pixels. - -</li><li> <var>height</var>: The new height in pixels. - -</li></ol> - -</li><li> <var>error</var>: Called with two arguments when an error occurs: - -<ol> -<li> <var>exception</var>: The exception object. - -</li><li> <var>stack</var>: The call stack at the point of the exception. - -</li></ol> - -<p>If no error handler is specified, exceptions will simply be re-raised. -</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>[#:init] [#: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>init</var>: Called just before game loop is started. Use it to -perform game initialization. -</li><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 seconds. 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 id="index-elapsed_002dtime">Procedure: <strong>elapsed-time</strong></dt> -<dd><p>Return the current value of the system timer in seconds. -</p></dd></dl> - -<hr /> -<div class="header"> -<p> -Next: <a href="Input-Devices.html" accesskey="n" rel="next">Input Devices</a>, Up: <a href="Kernel.html" accesskey="u" rel="up">Kernel</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> -</div> - - - -</body> -</html> |