1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
|
<!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}
@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">
<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!"] [#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f] [#:update-hz 60]</em></dt>
<dd>
<p>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>
|
