The Chickadee Game Toolkit: API Reference

From f16fed3d50fd3d56deb46a3d4641a81460e389de Mon Sep 17 00:00:00 2001 From: David Thompson Date: Wed, 12 Dec 2018 09:20:10 -0500 Subject: Update Chickadee manual and home page for 0.3.0. Better late than never! --- manuals/chickadee/API-Reference.html | 18 +- manuals/chickadee/Agendas.html | 221 +++++++++++++++ manuals/chickadee/Audio.html | 177 ------------ manuals/chickadee/Basics.html | 121 +++++++++ manuals/chickadee/Bezier-Curves.html | 174 ++++++++++++ manuals/chickadee/Blending-and-Depth-Testing.html | 12 +- manuals/chickadee/Channels.html | 146 ++++++++++ manuals/chickadee/Copying-This-Manual.html | 12 +- manuals/chickadee/Easings.html | 171 ++++++++++++ manuals/chickadee/Fonts.html | 38 +-- manuals/chickadee/Framebuffers.html | 55 +++- .../chickadee/GNU-Free-Documentation-License.html | 14 +- manuals/chickadee/Graphics.html | 30 ++- manuals/chickadee/Grid.html | 223 +++++++++++++++ manuals/chickadee/Index.html | 266 +++++++++++++++--- manuals/chickadee/Input.html | 103 ------- manuals/chickadee/Installation.html | 10 +- manuals/chickadee/Kernel.html | 300 ++++++++------------- manuals/chickadee/Lines-and-Shapes.html | 44 ++- manuals/chickadee/Math.html | 34 ++- manuals/chickadee/Matrices.html | 175 +++++++++++- manuals/chickadee/Path-Finding.html | 180 +++++++++++++ manuals/chickadee/Quaternions.html | 146 ++++++++++ manuals/chickadee/Rectangles.html | 253 ++++++++++++++++- manuals/chickadee/Rendering-Engine.html | 71 +++-- manuals/chickadee/Requirements.html | 10 +- manuals/chickadee/Scripting.html | 127 +++++++++ manuals/chickadee/Scripts.html | 209 ++++++++++++++ manuals/chickadee/Shaders.html | 12 +- manuals/chickadee/Sprites.html | 43 ++- manuals/chickadee/Textures.html | 14 +- manuals/chickadee/Tile-Maps.html | 126 +++++++++ manuals/chickadee/Tweening.html | 132 +++++++++ manuals/chickadee/Vectors.html | 261 +++++++++++++++++- manuals/chickadee/Vertex-Arrays.html | 12 +- manuals/chickadee/Viewports.html | 14 +- manuals/chickadee/index.html | 65 +++-- 37 files changed, 3290 insertions(+), 729 deletions(-) create mode 100644 manuals/chickadee/Agendas.html delete mode 100644 manuals/chickadee/Audio.html create mode 100644 manuals/chickadee/Basics.html create mode 100644 manuals/chickadee/Bezier-Curves.html create mode 100644 manuals/chickadee/Channels.html create mode 100644 manuals/chickadee/Easings.html create mode 100644 manuals/chickadee/Grid.html delete mode 100644 manuals/chickadee/Input.html create mode 100644 manuals/chickadee/Path-Finding.html create mode 100644 manuals/chickadee/Quaternions.html create mode 100644 manuals/chickadee/Scripting.html create mode 100644 manuals/chickadee/Scripts.html create mode 100644 manuals/chickadee/Tile-Maps.html create mode 100644 manuals/chickadee/Tweening.html (limited to 'manuals') diff --git a/manuals/chickadee/API-Reference.html b/manuals/chickadee/API-Reference.html index 0dcd1de..d5fdbbe 100644 --- a/manuals/chickadee/API-Reference.html +++ b/manuals/chickadee/API-Reference.html @@ -16,16 +16,16 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: API Reference + +API Reference (The Chickadee Game Toolkit) - - + + - @@ -99,13 +99,11 @@ Next: • Kernel: The fundamental components. -• Input: Keyboard, mouse, and controller input. - -• Math: Linear algebra and more. +• Math: Linear algebra, spatial partitioning, and more. -• Graphics: Eye candy. +• Graphics: Eye candy. -• Audio: Sound effects and music. +• Scripting: Bringing the game world to life. diff --git a/manuals/chickadee/Agendas.html b/manuals/chickadee/Agendas.html new file mode 100644 index 0000000..eced92c --- /dev/null +++ b/manuals/chickadee/Agendas.html @@ -0,0 +1,221 @@ + + + + + + +Agendas (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + + + +

+ +

2.4.1 Agendas

+ +

To schedule a task to be performed later, an “agenda” is used. +There is a default, global agenda that is ready to be used, or +additional agendas may be created for different purposes. The +following example prints the text “hello” when the agenda has +advanced to time unit 10. +

(at 10 (display "hello\n"))
+

+ +

Most of the time it is more convenient to schedule tasks relative to +the current time. This is where after comes in handy: +

(after 10 (display "hello\n"))
+

+ +

Time units in the agenda are in no way connected to real time. It’s +up to the programmer to decide what agenda time means. A simple and +effective approach is to map each call of the update hook +(see Kernel) to 1 unit of agenda time, like so: +

(add-hook! update-hook (lambda (dt) (update-agenda 1)))
+

+ +

It is important to call update-agenda periodically, otherwise +no tasks will ever be run! +

In addition to using the global agenda, it is useful to have multiple +agendas for different purposes. For example, the game world can use a +different agenda than the user interface, so that pausing the game is +a simple matter of not updating the world’s agenda while continuing to +update the user interface’s agenda. The current agenda is dynamically +scoped and can be changed using the with-agenda special form: +

(define game-world-agenda (make-agenda))
+
+(with-agenda game-world-agenda
+  (at 60 (spawn-goblin))
+  (at 120 (spawn-goblin))
+  (at 240 (spawn-goblin-king)))
+

+ +

Procedure: make-agenda: Return a new task scheduler. +

+ +

Procedure: agenda? obj: Return #t if obj is an agenda. +

+ +

Procedure: current-agenda
Procedure: current-agenda agenda: When called with no arguments, return the current agenda. When called +with one argument, set the current agenda to agenda. +

+ +

Syntax: with-agenda agenda body …: Evaluate body with the current agenda set to agenda. +

+ +

Procedure: agenda-time: Return the current agenda time. +

+ +

Procedure: update-agenda dt: Advance the current agenda by dt. +

+ +

Procedure: schedule-at time thunk: Schedule thunk, a procedure of zero arguments, to be run at +time. +

+ +

Procedure: schedule-after delay thunk: Schedule thunk, a procedure of zero arguments, to be run after +delay. +

+ +

Procedure: schedule-every interval thunk [n]: Schedule thunk, a procedure of zero arguments, to be run every +interval amount of time. Repeat this n times, or +indefinitely if not specified. +

+ +

Syntax: at time body …: Schedule body to be evaluated at time. +

+ +

Syntax: after delay body …: Schedule body to be evaluated after delay. +

+ +

Syntax: every interval body …
Syntax: every (interval n) body …: Schedule body to be evaluated every interval amount of +time. Repeat this n times, or indefinitely if not specified. +

+ +

+ + + + + + diff --git a/manuals/chickadee/Audio.html b/manuals/chickadee/Audio.html deleted file mode 100644 index 755efb9..0000000 --- a/manuals/chickadee/Audio.html +++ /dev/null @@ -1,177 +0,0 @@ - - - - - -The Chickadee Game Toolkit: Audio - - - - - - - - - - - - - - - - - - - - - - -

- -

2.5 Audio

- -

Chickadee has two data types for audio: samples and music. Samples -are for short sound effects like explosions. Music is for, well, -uh…, music. -

Supported file formats include WAV and OGG. -

Scheme Procedure: load-sample file: Load audio sample from file. -

- -

Scheme Procedure: set-sample-volume! volume: Set the volume that all samples are played at to volume, an -integer value between 0 and 128. -

- -

Scheme Procedure: play-sample sample: Play sample. Pretty straightforward! -

- -

Scheme Procedure: load-music file: Load music from file. -

- -

Scheme Procedure: music-volume: Return the volume level for music, an integer value between 0 and 128. -

- -

Scheme Procedure: set-music-volume! volume: Set the volume that music is played at to volume, an integer -value between 0 and 128. -

- -

Scheme Procedure: play-music music [loop?]: Play music. If loop?, play it over and over and over and -over and… -

- -

Scheme Procedure: pause-music: Pause the current music track. -

- -

Scheme Procedure: resume-music: Resume the current music track. -

- -

Scheme Procedure: rewind-music: estart the current music track from the beginning. -

- -

Scheme Procedure: stop-music: Stop playing the current music track. -

- -

Scheme Procedure: music-playing?: Return #t if music is currently playing. -

- -

Scheme Procedure: music-paused?: Return #t if music is currently paused. -

- - - - - - diff --git a/manuals/chickadee/Basics.html b/manuals/chickadee/Basics.html new file mode 100644 index 0000000..dd3898c --- /dev/null +++ b/manuals/chickadee/Basics.html @@ -0,0 +1,121 @@ + + + + + + +Basics (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + + + +

+ +

2.2.1 Basics

+ +

Variable: pi: An essential constant for all trigonometry. π is the ratio +of a circle’s circumferences to its diameter. Since π is an +irrational number, the pi in Chickadee is a mere floating point +approximation that is “good enough.” +

+ +

Variable: pi/2: Half of pi. +

+ +

Procedure: cotan z: Return the cotangent of z. +

+ + + + + + diff --git a/manuals/chickadee/Bezier-Curves.html b/manuals/chickadee/Bezier-Curves.html new file mode 100644 index 0000000..6a49b59 --- /dev/null +++ b/manuals/chickadee/Bezier-Curves.html @@ -0,0 +1,174 @@ + + + + + + +Bezier Curves (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + + + +

+ +

2.2.8 Bezier Curves

+ +

The (chickadee math bezier) module provides an API for +describing cubic Bezier curves in 2D space. These curves are notably +used in font description, vector graphics programs, and when it comes +to games: path building. With Bezier curves, it’s somewhat easy to +create a smooth looking path for an enemy to move along, for example. +Bezier curves become particularly interesting when they are chained +together to form a Bezier “path”, where the end point of one curve +becomes the starting point of the next. +

Currently, the rendering of Bezier curves is rather crude and provided +mostly for visualizing and debugging curves that would be unseen in +the final game. See See Lines and Shapes for more information. +

Procedure: make-bezier-curve p0 p1 p2 p3: Return a new Bezier curve object whose starting point is p0, +ending point is p3, and control points are p1 and +p2. All points are 2D vectors. +

+ +

Procedure: bezier-curve? obj: Return #t if obj is a Bezier curve. +

+ +

Procedure: bezier-curve-p0 bezier: Return the starting point of bezier. +

+ +

Procedure: bezier-curve-p1 bezier: Return the first control point of bezier. +

+ +

Procedure: bezier-curve-p2 bezier: Return the second control point of bezier. +

+ +

Procedure: bezier-curve-p3 bezier: Return the end point of bezier. +

+ +

Procedure: bezier-path . control-points: Return a list of connected bezier curves defined by +control-points. The first curve is defined by the first 4 +arguments and every additional curve thereafter requires 3 additional +arguments. +

+ +

Procedure: bezier-curve-point-at bezier t: Return the coordinates for bezier at t (a value in the +range [0, 1] representing how far from the start of the curve to +check) as a 2D vector. +

+ +

Procedure: bezier-curve-point-at! dest bezier t: Modify the 2D vector dest in-place to contain the coordinates +for bezier at t. +

+ +

+ + + + + + diff --git a/manuals/chickadee/Blending-and-Depth-Testing.html b/manuals/chickadee/Blending-and-Depth-Testing.html index 72b6140..2591a95 100644 --- a/manuals/chickadee/Blending-and-Depth-Testing.html +++ b/manuals/chickadee/Blending-and-Depth-Testing.html @@ -16,16 +16,16 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Blending and Depth Testing + +Blending and Depth Testing (The Chickadee Game Toolkit) - - + + - @@ -94,7 +94,7 @@ Next: Vertex

2.4.6 Blending and Depth Testing

2.3.7 Blending and Depth Testing

diff --git a/manuals/chickadee/Channels.html b/manuals/chickadee/Channels.html new file mode 100644 index 0000000..f313c4f --- /dev/null +++ b/manuals/chickadee/Channels.html @@ -0,0 +1,146 @@ + + + + + + +Channels (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + + + +

+ +

2.4.4 Channels

+ +

Channels are a tool for communicating amongst different scripts. One +script can write a value to the channel and another can read from it. +Reading or writing to a channel suspends that script until there is +someone on the other end of the line to complete the transaction. +

Here’s a simplistic example: +

(define c (make-channel))
+
+(script
+ (forever
+  (let ((item (channel-get c)))
+    (pk 'got item))))
+
+(script
+ (channel-put c 'sword)
+ (channel-put c 'shield)
+ (channel-put c 'potion))
+

+ +

Procedure: make-channel: Return a new channel +

+ +

Procedure: channel? obj: Return #t if obj is a channel. +

+ +

Procedure: channel-get channel: Retrieve a value from channel. The current script suspends +until a value is available. +

+ +

Procedure: channel-put channel data: Send data to channel. The current script suspends until +another script is available to retrieve the value. +

+ + + + + + diff --git a/manuals/chickadee/Copying-This-Manual.html b/manuals/chickadee/Copying-This-Manual.html index 493541d..f9a7c77 100644 --- a/manuals/chickadee/Copying-This-Manual.html +++ b/manuals/chickadee/Copying-This-Manual.html @@ -16,22 +16,22 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Copying This Manual + +Copying This Manual (The Chickadee Game Toolkit) - - + + - - + + + + + + + + + +

+ +

2.2.7 Easings

+ +

Procedure: linear t

+ +

Procedure: smoothstep t

+ +

Procedure: ease-in-quad t

+ +

Procedure: ease-out-quad t

+ +

Procedure: ease-in-out-quad t

+ +

Procedure: ease-in-cubic t

+ +

Procedure: ease-out-cubic t

+ +

Procedure: ease-in-out-cubic t

+ +

Procedure: ease-in-quart t

+ +

Procedure: ease-out-quart t

+ +

Procedure: ease-in-out-quart t

+ +

Procedure: ease-in-quint t

+ +

Procedure: ease-out-quint t

+ +

Procedure: ease-in-out-quint t

+ +

Procedure: ease-in-sine t

+ +

Procedure: ease-out-sine t

+ +

Procedure: ease-in-out-sine t

+ + + + + + diff --git a/manuals/chickadee/Fonts.html b/manuals/chickadee/Fonts.html index 198bddb..a4ed5c6 100644 --- a/manuals/chickadee/Fonts.html +++ b/manuals/chickadee/Fonts.html @@ -16,16 +16,16 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Fonts + +Fonts (The Chickadee Game Toolkit) - - + + - @@ -94,7 +94,7 @@ Next:

2.4.5 Fonts

2.3.6 Fonts

Unlike the traditional TrueType font format that many are accustomed to, Chickadee loads and renders bitmap fonts in the @@ -122,9 +122,7 @@ each font size needed. This is where the “signed distance field” rendering technique comes in. Introduced by Valve in 2007, signed distance field fonts can be efficiently stored in a bitmap and be rendered at arbitrary scale factors with good -results. Chickadee can render both traditional bitmap fonts and -signed distance field fonts. Signed distance field font -rendering is not yet available, so be patient. +results.

While Chickadee does not yet offer a tool for converting TTF fonts into FNT fonts, tools such as @@ -135,44 +133,45 @@ in the meantime. font) module.

Scheme Procedure: load-font file
Procedure: load-font file: Load the Angel Code formatted XML document in file and return a new font object.

Scheme Procedure: font? obj
Procedure: font? obj: Return #t if obj is a font object.

Scheme Procedure: font-face font
Procedure: font-face font: Return the name of font.

Scheme Procedure: font-line-height font
Procedure: font-line-height font: Return the line height of font.

Scheme Procedure: font-line-height font
Procedure: font-line-height font: Return the line height of font.

Scheme Procedure: font-bold? font
Procedure: font-bold? font: Return #t if font is a bold font.

Scheme Procedure: font-italic? font
Procedure: font-italic? font: Return #t if font is an italicized font.

Scheme Procedure: draw-text font text position

[#:scale] [#:rotation] [#:blend-mode] +

Procedure: draw-text font text position

[#:origin] [#:scale] [#:rotation] [#:blend-mode] + [#:start 0] [#:end (string-length text)]

Draw the string text with the first character starting at position using font. @@ -181,6 +180,9 @@ new font object.

(draw-text font "Hello, world!" (vec2 128.0 128.0))

To render a substring of text, use the start and end +arguments. +

Refer to draw-sprite (see Sprites) for information about the other arguments.

diff --git a/manuals/chickadee/Framebuffers.html b/manuals/chickadee/Framebuffers.html index c57a82a..d7bedc4 100644 --- a/manuals/chickadee/Framebuffers.html +++ b/manuals/chickadee/Framebuffers.html @@ -16,16 +16,16 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Framebuffers + +Framebuffers (The Chickadee Game Toolkit) - - + + - @@ -94,7 +94,50 @@ Next: Viewports,

2.4.9 Framebuffers

2.3.10 Framebuffers

+ +

A framebuffer is a chunk of memory that the GPU can render things +onto. By default, the framebuffer that is used for rendering is the +one belonging to the game window, but custom framebuffers can be used +as well. A common use-case for custom framebuffers is applying +post-processing effects: The entire scene is rendered to a +framebuffer, and then the contents of that framebuffer are applied to +a post-processing shader and rendered to the game window. The +post-processing shader could do any number of things: scaling, +antialiasing, motion blur, etc. +

Procedure: make-framebuffer width height [#:min-filter 'linear] [#:mag-filter 'linear] [#:wrap-s 'repeat] [#:wrap-t 'repeat]

Create a new framebuffer that is width pixels wide and height pixels high. +

min-filter and mag-filter determine the scaling algorithm +applied to the framebuffer when rendering. By default, linear scaling +is used in both cases. To perform no smoothing at all, use +nearest for simple nearest neighbor scaling. This is typically +the best choice for pixel art games. +

+ +

Procedure: framebuffer? obj: Return #t if obj is a framebuffer. +

+ +

Procedure: framebuffer-texture fb: Return the texture backing the framebuffer fb. +

+ +

Procedure: framebuffer-viewport fb: Return the default viewport (see Viewports) used by the +framebuffer fb. +

+ +

Procedure: null-framebuffer: The default framebuffer. +

diff --git a/manuals/chickadee/GNU-Free-Documentation-License.html b/manuals/chickadee/GNU-Free-Documentation-License.html index 62ad23f..3c9e2c5 100644 --- a/manuals/chickadee/GNU-Free-Documentation-License.html +++ b/manuals/chickadee/GNU-Free-Documentation-License.html @@ -16,16 +16,16 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: GNU Free Documentation License + +GNU Free Documentation License (The Chickadee Game Toolkit) - - + + - @@ -106,7 +106,7 @@ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. -

PREAMBLE

The purpose of this License is to make a manual, textbook, or other @@ -282,7 +282,7 @@ Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section diff --git a/manuals/chickadee/Graphics.html b/manuals/chickadee/Graphics.html index 0afe5bc..f10cc89 100644 --- a/manuals/chickadee/Graphics.html +++ b/manuals/chickadee/Graphics.html @@ -16,22 +16,22 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Graphics + +Graphics (The Chickadee Game Toolkit) - - + + - - + + + + + + + + + +

+ +

2.2.4 Grid

+ +

The (chickadee math grid) module provides a simple spatial +partitioning system for axis-aligned bounding boxes +(see Rectangles) in 2D space. The grid divides the world into +tiles and keeps track of which rectangles occupy which tiles. When +there are lots of moving objects in the game world that need collision +detection, the grid greatly speeds up the process. Instead of +checking collisions of each object against every other object (an +O(n^2) operation), the grid quickly narrows down which objects could +possibly be colliding and only performs collision testing against a +small set of objects. +

In addition to checking for collisions, the grid also handles the +resolution of collisions. Exactly how each collision is resolved is +user-defined. A player bumping into a wall may slide against it. An +enemy colliding with a projectile shot by the player may get pushed +back in the opposite direction. Two players colliding may not need +resolution at all and will just pass through each other. The way this +works is that each time an object (A) is moved within the grid, the +grid looks for an object (B) that may possibly be colliding with A. A +user-defined procedure known as a “filter” is then called with both +A and B. If the filter returns #f, it means that even if A and +B are colliding, no collision resolution is needed. In this case the +grid won’t waste time checking if they really do collide because it +doesn’t matter. If A and B are collidable, then the filter returns a +procedure that implements the resolution technique. The grid will +then perform a collision test. If A and B are colliding, the resolver +procedure is called. It’s the resolvers job to adjust the objects +such that they are no longer colliding. The grid module comes with a +very simple resolution procedure, slide, that adjusts object A +by the smallest amount so that it no longer overlaps with B. By using +this filtering technique, a game can resolve collisions between +different objects in different ways. +

Procedure: make-grid [cell-size 64]: Return a new grid partitioned into cell-size tiles. +

+ +

Procedure: grid? obj: Return #t if obj is a grid. +

+ +

Procedure: cell? obj: Return #t if obj is a grid cell. +

+ +

Procedure: cell-count cell: Return the number of items in cell. +

+ +

Procedure: grid-cell-size grid: Return the cell size of grid. +

+ +

Procedure: grid-cell-count grid: Return the number of cells currently in grid. +

+ +

Procedure: grid-item-count grid: Return the number of items in grid. +

+ +

Procedure: grid-add grid item x y width height: +
Add item to grid represented by the axis-aligned bounding +box whose lower-left corner is at (x, y) and is +width x height in size. +

+ +

Procedure: grid-remove grid item: Return item from grid. +

+ +

Procedure: grid-clear grid: Remove all items from grid. +

+ +

Procedure: grid-move grid item position filter: Attempt to move item in grid to position (a 2D +vector) and check for collisions. For each collision, filter +will be called with two arguments: item and the item it collided +with. If a collision occurs, position may be modified to +resolve the colliding objects. +

+ +

Procedure: for-each-cell proc grid [rect]: Call proc with each cell in grid that intersects +rect, or every cell if rect is #f. +

+ +

Procedure: for-each-item proc grid: Call proc for each item in grid. +

+ +

Procedure: slide item item-rect other other-rect goal: +
Resolve the collision that occurs between item and other +when moving item-rect to goal by sliding item-rect +the minimum amount needed to make it no longer overlap +other-rect. +

+ +

+ + + + + + diff --git a/manuals/chickadee/Index.html b/manuals/chickadee/Index.html index 3c1df5e..b5168e5 100644 --- a/manuals/chickadee/Index.html +++ b/manuals/chickadee/Index.html @@ -16,16 +16,16 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Index + +Index (The Chickadee Game Toolkit) - - + + - @@ -103,16 +103,20 @@ Previous: D +E + F G -K - L M +N + +O + P Q @@ -125,25 +129,45 @@ Previous: U +V + W +Y + + - + + + + - + + + + + + + + - - - - - + + + + + + + + + + @@ -152,11 +176,32 @@ Previous: - + + + + + + + + + + + + + + + + + + + + + + @@ -165,56 +210,182 @@ Previous: + + + + + + - - - - + + + + + + + + + - - - + - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + + + - + + + + + + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + + + + + + + + + + + + + + + + + + + + - - + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -223,6 +394,9 @@ Previous: + + +

	Index Entry	Section

A
	`a*`:	Path Finding
	`abort-game`:	Kernel
	`after-draw-hook`:	Kernel
	`after`:	Agendas
	`agenda-time`:	Agendas
	`agenda?`:	Agendas
	`at`:	Agendas

B
	`before-draw-hook`:	Kernel
	`bezier-curve-p0`:	Bezier Curves
	`bezier-curve-p1`:	Bezier Curves
	`bezier-curve-p2`:	Bezier Curves
	`bezier-curve-p3`:	Bezier Curves
	`bezier-curve-point-at`:	Bezier Curves
	`bezier-curve-point-at!`:	Bezier Curves
	`bezier-curve?`:	Bezier Curves
	`bezier-path`:	Bezier Curves

C
	`controller-add-hook`:	Kernel
	`controller-move-hook`:	Kernel
	`controller-press-hook`:	Kernel
	`controller-release-hook`:	Kernel
	`controller-remove-hook`:	Kernel
	`cancel-script`:	Scripts
	`cell-count`:	Grid
	`cell?`:	Grid
	`channel-get`:	Scripts
	`channel-get`:	Channels
	`channel-put`:	Channels
	`channel?`:	Channels
	`cotan`:	Basics
	`current-agenda`:	Agendas
	`current-agenda`:	Agendas
	`current-blend-mode`:	Rendering Engine
	`current-depth-test`:	Rendering Engine
	`current-framebuffer`:	Rendering Engine
	`current-viewport`:	Rendering Engine

D
	`draw-hook`:	Kernel
	`draw-bezier-curve`:	Lines and Shapes
	`draw-bezier-path`:	Lines and Shapes
	`draw-line`:	Lines and Shapes
	`draw-nine-patch`:	Sprites
	`draw-sprite`:	Sprites
	`draw-text`:	Fonts
	`draw-tile-map`:	Tile Maps

E
	`ease-in-cubic`:	Easings
	`ease-in-out-cubic`:	Easings
	`ease-in-out-quad`:	Easings
	`ease-in-out-quart`:	Easings
	`ease-in-out-quint`:	Easings
	`ease-in-out-sine`:	Easings
	`ease-in-quad`:	Easings
	`ease-in-quart`:	Easings
	`ease-in-quint`:	Easings
	`ease-in-sine`:	Easings
	`ease-out-cubic`:	Easings
	`ease-out-quad`:	Easings
	`ease-out-quart`:	Easings
	`ease-out-quint`:	Easings
	`ease-out-sine`:	Easings
	`every`:	Agendas
	`every`:	Agendas

F
	`font-bold?`:	Fonts
	`font-line-height`:	Fonts
	`font-line-height`:	Fonts
	`font?`:	Fonts
	`for-each-cell`:	Grid
	`for-each-item`:	Grid
	`forever`:	Scripts
	`framebuffer-texture`:	Framebuffers
	`framebuffer-viewport`:	Framebuffers
	`framebuffer?`:	Framebuffers

G
	`gpu-apply`:	Rendering Engine
	`gpu-apply*`:	Rendering Engine

K
	`key-press-hook`:	Kernel
	`key-release-hook`:	Kernel
	`grid-add`:	Grid
	`grid-cell-count`:	Grid
	`grid-cell-size`:	Grid
	`grid-clear`:	Grid
	`grid-item-count`:	Grid
	`grid-move`:	Grid
	`grid-remove`:	Grid
	`grid?`:	Grid

L
	`linear`:	Easings
	`load-font`:	Fonts
	`load-hook`:	Kernel
	`load-image`:	Textures
	`load-music`:	Audio
	`load-sample`:	Audio
	`load-tile-map`:	Tile Maps

M
	`mouse-move-hook`:	Kernel
	`mouse-press-hook`:	Kernel
	`mouse-release-hook`:	Kernel
	`music-paused?`:	Audio
	`music-playing?`:	Audio
	`music-volume`:	Audio
	`make-agenda`:	Agendas
	`make-bezier-curve`:	Bezier Curves
	`make-channel`:	Channels
	`make-framebuffer`:	Framebuffers
	`make-grid`:	Grid
	`make-identity-matrix4`:	Matrices
	`make-identity-quaternion`:	Quaternions
	`make-matrix4`:	Matrices
	`make-null-matrix4`:	Matrices
	`make-path-finder`:	Path Finding
	`make-rect`:	Rectangles
	`matrix4*`:	Matrices
	`matrix4-2d-transform!`:	Matrices
	`matrix4-identity!`:	Matrices
	`matrix4-mult!`:	Matrices
	`matrix4-rotate`:	Matrices
	`matrix4-rotate!`:	Matrices
	`matrix4-rotate-z`:	Matrices
	`matrix4-rotate-z!`:	Matrices
	`matrix4-scale`:	Matrices
	`matrix4-scale!`:	Matrices
	`matrix4-translate`:	Matrices
	`matrix4-translate!`:	Matrices
	`matrix4?`:	Matrices

N
	`null-framebuffer`:	Framebuffers

O
	`orthographic-projection`:	Matrices

P
	`pause-music`:	Audio
	`play-music`:	Audio
	`play-sample`:	Audio
	`path-finder?`:	Path Finding
	`perspective-projection`:	Matrices
	`pi`:	Basics
	`pi/2`:	Basics

Q
	`quit-hook`:	Kernel
	`quaternion`:	Quaternions
	`quaternion-w`:	Quaternions
	`quaternion-x`:	Quaternions
	`quaternion-y`:	Quaternions
	`quaternion-z`:	Quaternions
	`quaternion?`:	Quaternions

R
	`resume-music`:	Audio
	`rewind-music`:	Audio
	`rect-area`:	Rectangles
	`rect-bottom`:	Rectangles
	`rect-center-x`:	Rectangles
	`rect-center-y`:	Rectangles
	`rect-clamp`:	Rectangles
	`rect-clamp!`:	Rectangles
	`rect-clamp-x`:	Rectangles
	`rect-clamp-y`:	Rectangles
	`rect-clip`:	Rectangles
	`rect-clip!`:	Rectangles
	`rect-contains-vec2?`:	Rectangles
	`rect-contains?`:	Rectangles
	`rect-height`:	Rectangles
	`rect-inflate`:	Rectangles
	`rect-inflate!`:	Rectangles
	`rect-intersects?`:	Rectangles
	`rect-left`:	Rectangles
	`rect-move`:	Rectangles
	`rect-move!`:	Rectangles
	`rect-move-by`:	Rectangles
	`rect-move-by!`:	Rectangles
	`rect-move-by-vec2`:	Rectangles
	`rect-move-by-vec2!`:	Rectangles
	`rect-move-vec2`:	Rectangles
	`rect-move-vec2!`:	Rectangles
	`rect-right`:	Rectangles
	`rect-top`:	Rectangles
	`rect-union`:	Rectangles
	`rect-union!`:	Rectangles
	`rect-width`:	Rectangles
	`rect-within?`:	Rectangles
	`rect-x`:	Rectangles
	`rect-y`:	Rectangles
	`rect?`:	Rectangles
	`run-game`:	Kernel
	`run-game/sdl`:	Kernel

S
	`set-music-volume!`:	Audio
	`set-sample-volume!`:	Audio
	`stop-music`:	Audio
	`schedule-after`:	Agendas
	`schedule-at`:	Agendas
	`schedule-every`:	Agendas
	`script`:	Scripts
	`script-cancelled?`:	Scripts
	`script-complete?`:	Scripts
	`script-running?`:	Scripts
	`script?`:	Scripts
	`set-rect-height!`:	Rectangles
	`set-rect-width!`:	Rectangles
	`set-rect-x!`:	Rectangles
	`set-rect-y!`:	Rectangles
	`set-vec2-x!`:	Vectors
	`set-vec2-y!`:	Vectors
	`set-vec3-x!`:	Vectors
	`set-vec3-y!`:	Vectors
	`set-vec3-z!`:	Vectors
	`sleep`:	Scripts
	`slide`:	Grid
	`smoothstep`:	Easings
	`spawn-script`:	Scripts

T
	`text-input-hook`:	Kernel
	`time`:	Kernel
	`transform!`:	Matrices
	`tween`:	Tweening

U
	`update-hook`:	Kernel
	`update-agenda`:	Agendas

V
	`vec2`:	Vectors
	`vec2*`:	Vectors
	`vec2+`:	Vectors
	`vec2-`:	Vectors
	`vec2-add!`:	Vectors
	`vec2-clamp-to-rect!`:	Rectangles
	`vec2-copy`:	Vectors
	`vec2-copy!`:	Vectors
	`vec2-dot-product`:	Vectors
	`vec2-magnitude`:	Vectors
	`vec2-mult!`:	Vectors
	`vec2-normalize`:	Vectors
	`vec2-sub!`:	Vectors
	`vec2-x`:	Vectors
	`vec2-y`:	Vectors
	`vec2/polar`:	Vectors
	`vec2?`:	Vectors
	`vec3`:	Vectors
	`vec3*`:	Vectors
	`vec3+`:	Vectors
	`vec3-`:	Vectors
	`vec3-add!`:	Vectors
	`vec3-copy`:	Vectors
	`vec3-copy!`:	Vectors
	`vec3-dot-product`:	Vectors
	`vec3-magnitude`:	Vectors
	`vec3-mult!`:	Vectors
	`vec3-normalize`:	Vectors
	`vec3-sub!`:	Vectors
	`vec3-x`:	Vectors
	`vec3-y`:	Vectors
	`vec3-z`:	Vectors
	`vec3?`:	Vectors

W
	`with-agenda`:	Agendas
	`with-batched-sprites`:	Sprites
	`with-blend-mode`:	Rendering Engine
	`with-depth-test`:	Rendering Engine
	`with-texture`:	Rendering Engine
	`with-viewport`:	Rendering Engine

Y
	`yield`:	Scripts

Jump to:	A @@ -232,16 +406,20 @@ Previous: D +E + F G -K - L M +N + +O + P Q @@ -254,8 +432,12 @@ Previous: U +V + W +Y +

diff --git a/manuals/chickadee/Input.html b/manuals/chickadee/Input.html deleted file mode 100644 index d559126..0000000 --- a/manuals/chickadee/Input.html +++ /dev/null @@ -1,103 +0,0 @@ - - - - - -The Chickadee Game Toolkit: Input - - - - - - - - - - - - - - - - - - - - - - -

- -

2.2 Input

- - - - - - diff --git a/manuals/chickadee/Installation.html b/manuals/chickadee/Installation.html index a362263..4872008 100644 --- a/manuals/chickadee/Installation.html +++ b/manuals/chickadee/Installation.html @@ -16,16 +16,16 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Installation + +Installation (The Chickadee Game Toolkit) - - + + - diff --git a/manuals/chickadee/Kernel.html b/manuals/chickadee/Kernel.html index 589c71e..c298723 100644 --- a/manuals/chickadee/Kernel.html +++ b/manuals/chickadee/Kernel.html @@ -16,21 +16,21 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Kernel + +Kernel (The Chickadee Game Toolkit) - - + + - - + + + + + + + + + +

+ +

2.2.9 Path Finding

+ +

Most game worlds have maps. Often, these games have a need to move +non-player characters around in an unscripted fashion. For example, +in a real-time strategy game, the player may command one of their +units to attack something in the enemy base. To do so, the unit must +calculate the shortest route to get there. It wouldn’t be a very fun +game if units didn’t know how to transport themselves efficiently. +This is where path finding algorithms come in handy. The +(chickadee math path-finding) module provides a generic +implementation of the popular A* path finding algorithm. Just add a +map implementation! +

The example below defines a very simple town map and finds the +quickest way to get from the town common to the school. +

(define world-map
+  '((town-common . (town-hall library))
+    (town-hall . (town-common school))
+    (library . (town-common cafe))
+    (school . (town-hall cafe))
+    (cafe . (library school))))
+(define (neighbors building)
+  (assq-ref town-map building))
+(define (cost a b) 1)
+(define (distance a b) 1)
+(define pf (make-path-finder))
+(a* pf 'town-common 'school neighbors cost distance)
+

+ +

In this case, the a* procedure will return the list +(town-common town-hall school), which is indeed the shortest +route. (The other possible route is (town-common library cafe +school).) +

The a* procedure does not know anything about about any kind of +map and therefore must be told how to look up neighboring nodes, which +is what the neighbors procedure in the example does. To +simulate different types of terrain, a cost procedure is used. In +this example, it is just as easy to move between any two nodes because +cost always returns 1. In a real game, perhaps moving from +from a field to a rocky hill would cost a lot more than moving from +one field to another. Finally, a heuristic is used to calculate an +approximate distance between two nodes on the map. In this simple +association list based graph it is tough to calculate a distance +between nodes, so the distance procedure isn’t helpful and +always returns 1. In a real game with a tile-based map, for example, +the heuristic could be a quick Manhattan distance calculation based on +the coordinates of the two map tiles. Choose an appropriate heuristic +for optimal path finding! +

Procedure: make-path-finder: Return a new path finder object. +

+ +

Procedure: path-finder? obj: Return #t if obj is a path finder. +

+ +

Procedure: a* path-finder start goal neighbors cost distance: +
Return a list of nodes forming a path from start to goal +using path-finder to hold state. neighbors is a procedure +that accepts a node and returns a list of nodes that neighbor it. +cost is a procedure that accepts two neighboring nodes and +returns the cost of moving from the first to the second as a real +number. distance is a procedure that accepts two nodes and +returns an approximate distance between them. +

+ +

+ + + + + + diff --git a/manuals/chickadee/Quaternions.html b/manuals/chickadee/Quaternions.html new file mode 100644 index 0000000..de4c8e4 --- /dev/null +++ b/manuals/chickadee/Quaternions.html @@ -0,0 +1,146 @@ + + + + + + +Quaternions (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + + + +

+ +

2.2.6 Quaternions

+ +

In game development, the quaternion is most often used to represent +rotations. Why not use a matrix for that, you may ask. Unlike +matrices, quaternions can be interpolated (animated) and produce a +meaningful result. When interpolating two quaternions, there is a +smooth transition from one rotation to another, whereas interpolating +two matrices would yield garbage. +

Procedure: quaternion x y z w: Return a new quaternion with values x, y, z, and +w. +

+ +

Procedure: quaternion? obj: Return #t if obj is a quaternion. +

+ +

Procedure: quaternion-w q: Return the W component of the quaternion q. +

+ +

Procedure: quaternion-x q: Return the X component of the quaternion q. +

+ +

Procedure: quaternion-y q: Return the Y component of the quaternion q. +

+ +

Procedure: quaternion-z q: Return the Z component of the quaternion q. +

+ +

Procedure: make-identity-quaternion: Return the identity quaternion. +

+ + + + + + diff --git a/manuals/chickadee/Rectangles.html b/manuals/chickadee/Rectangles.html index 6d0c9e8..edaf4e6 100644 --- a/manuals/chickadee/Rectangles.html +++ b/manuals/chickadee/Rectangles.html @@ -16,22 +16,22 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Rectangles + +Rectangles (The Chickadee Game Toolkit) - - + + - - - + + + + + + + + + + +

+ +

2.4 Scripting

+ +

Game logic is a web of asynchronous events that are carefully +coordinated to bring the game world to life. In order to make an +enemy follow and attack the player, or move an NPC back and forth in +front of the item shop, or do both at the same time, a scripting +system is a necessity. Chickadee comes with an asynchronous +programming system in the (chickadee scripting) module. +Lightweight, cooperative threads known as “scripts” allow the +programmer to write asynchronous code as if it were synchronous, and +allow many such “threads” to run concurrently. +

But before we dig deeper into scripts, let’s discuss the simple act +of scheduling tasks. +

+ + + + + + + + + + + + diff --git a/manuals/chickadee/Scripts.html b/manuals/chickadee/Scripts.html new file mode 100644 index 0000000..c9939f5 --- /dev/null +++ b/manuals/chickadee/Scripts.html @@ -0,0 +1,209 @@ + + + + + + +Scripts (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + + + +

+ +

2.4.2 Scripts

+ +

Now that we can schedule tasks, let’s take things to the next level. +It sure would be great if we could make procedures that described a +series of actions that happened over time, especially if we could do +so without contorting our code into a nest of callback procedures. +This is where scripts come in. With scripts we can write code in a +linear way, in a manner that appears to be synchronous, but with the +ability to suspend periodically in order to let other scripts have a +turn and prevent blocking the game loop. Building on top of the +scheduling that agendas provide, here is a script that models a child +trying to get their mother’s attention: +

(script
+  (while #t
+    (display "mom!")
+    (newline)
+    (sleep 60))) ; where 60 = 1 second of real time
+

+ +

This code runs in an endless loop, but the sleep procedure +suspends the script and schedules it to be run later by the agenda. +So, after each iteration of the loop, control is returned back to the +game loop and the program is not stuck spinning in a loop that will +never exit. Pretty neat, eh? +

Scripts can suspend to any capable handler, not just the agenda. +The yield procedure will suspend the current script and pass +its “continuation” to a handler procedure. This handler procedure +could do anything. Perhaps the handler stashes the continuation +somewhere where it will be resumed when the user presses a specific +key on the keyboard, or maybe it will be resumed when the player picks +up an item off of the dungeon floor; the sky is the limit. +

Sometimes it is necessary to abruptly terminate a script after it has +been started. For example, when an enemy is defeated their AI routine +needs to be shut down. When a script is spawned, a handle to that +script is returned that can be used to cancel it when desired. +

(define script (script (while #t (display "hey\n") (sleep 60))))
+;; sometime later
+(cancel-script script)
+

+ +

Procedure: spawn-script thunk: Apply thunk as a script and return a handle to it. +

+ +

Syntax: script body …: Evaluate body as a script and return a handle to it. +

+ +

Procedure: script? obj: Return #t if obj is a script handle. +

+ +

Procedure: script-cancelled? obj: Return #t if obj has been cancelled. +

+ +

Procedure: script-running? obj: Return #t if obj has not yet terminated or been +cancelled. +

+ +

Procedure: script-complete? obj: Return #t if obj has terminated. +

+ +

Procedure: cancel-script co: Prevent further execution of the script co. +

+ +

Procedure: yield handler: Suspend the current script and pass its continuation to the +procedure handler. +

+ +

Procedure: sleep duration: Wait duration before resuming the current script. +

+ +

Procedure: channel-get channel: Wait for a message from channel. +

+ +

Syntax: forever body …: Evaluate body in an endless loop. +

+ +

+ + + + + + diff --git a/manuals/chickadee/Shaders.html b/manuals/chickadee/Shaders.html index 7b3a2a0..70173a4 100644 --- a/manuals/chickadee/Shaders.html +++ b/manuals/chickadee/Shaders.html @@ -16,16 +16,16 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Shaders + +Shaders (The Chickadee Game Toolkit) - - + + - @@ -94,7 +94,7 @@ Next: Framebuf

2.4.8 Shaders

2.3.9 Shaders

Shaders are programs for the GPU to evaluate. They are written in the OpenGL Shading Language, or GLSL. Chickadee does not currently diff --git a/manuals/chickadee/Sprites.html b/manuals/chickadee/Sprites.html index 0c114bd..29d16ea 100644 --- a/manuals/chickadee/Sprites.html +++ b/manuals/chickadee/Sprites.html @@ -16,21 +16,21 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Sprites + +Sprites (The Chickadee Game Toolkit) - - + + - - + + + + + + + + +

+ +

2.3.4 Tile Maps

+ +

A tile map is a scene created by composing lots of small sprites, +called “tiles”, into a larger image. One program for editing such +maps is called Tiled. Chickadee has native +support for loading and rendering Tiled maps in the (chickadee +render tiled) module. +

Procedure: load-tile-map file-name: Load the Tiled formatted map in file-name and return a new tile +map object. +

+ +

Procedure: draw-tile-map tile-map [#:layers] [#:region] [#:origin] [#:position] [#:scale] [#:rotation]

Draw the layers of tile-map. By default, all layers are drawn. +To draw a subset of the available layers, pass a list of layer ids +using the layers keyword argument. +

Refer to draw-sprite (see Sprites) for information about +the other arguments. +

+ + + + + + diff --git a/manuals/chickadee/Tweening.html b/manuals/chickadee/Tweening.html new file mode 100644 index 0000000..3e344df --- /dev/null +++ b/manuals/chickadee/Tweening.html @@ -0,0 +1,132 @@ + + + + + + +Tweening (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + + + +

+ +

2.4.3 Tweening

+ +

Tweening is the process of transitioning something from an initial +state to a final state over a pre-determined period of time. In other +words, tweening is a way to create animation. The tween +procedure can be used within any script like so: +

(define x 0)
+(script
+  ;; 0 to 100 in 60 ticks of the agenda.
+  (tween 60 0 100 (lambda (y) (set! x y))))
+

+ +

Procedure: tween duration start end proc [#:step 1 #:ease smoothstep #:interpolate lerp]

Transition a value from start to end over duration, +sending each succesive value to proc. step controls the +amount of time between each update of the animation. +

To control how the animation goes from the initial to final state, an +“easing” procedure may be specified. By default, the +smoothstep easing is used, which is a more pleasing default +than a simplistic linear function. See Easings for a complete list +of available easing procedures. +

The interpolate procedure computes the values in between +start and end. By default, linear interpolation (“lerp” +for short) is used. +

+ + + + + + diff --git a/manuals/chickadee/Vectors.html b/manuals/chickadee/Vectors.html index eb79149..4857f0a 100644 --- a/manuals/chickadee/Vectors.html +++ b/manuals/chickadee/Vectors.html @@ -16,22 +16,22 @@ Foundation Web site at http://www.gnu.org/licenses/fdl.html. The document was typeset with http://www.texinfo.org/ (GNU Texinfo). --> - + -The Chickadee Game Toolkit: Vectors + +Vectors (The Chickadee Game Toolkit) - - + + - - - + +

• Agendas:		Scheduling tasks. +
• Scripts:		Cooperative multitasking. +
• Tweening:		Animations. +
• Channels:		Publish data to listeners. +