From 1f1deea662da4328bf588c0642c8a90c7b1f2144 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Tue, 24 Sep 2013 21:06:41 -0400 Subject: Rough draft of manual. --- doc/audio.texi | 98 +++++++++++++++++++++++++++++++++++ doc/game.texi | 113 ++++++++++++++++++++++++++++++++++++++++ doc/graphics.texi | 23 ++++++++ doc/graphics/animation.texi | 84 ++++++++++++++++++++++++++++++ doc/graphics/color.texi | 64 +++++++++++++++++++++++ doc/graphics/font.texi | 70 +++++++++++++++++++++++++ doc/graphics/sprite.texi | 121 +++++++++++++++++++++++++++++++++++++++++++ doc/graphics/texture.texi | 65 +++++++++++++++++++++++ doc/graphics/tileset.texi | 41 +++++++++++++++ doc/guile-2d.texi | 14 ++++- doc/introduction.texi | 45 +++++++++++++++- doc/math.texi | 17 ++++++ doc/math/math.texi | 37 +++++++++++++ doc/math/rect.texi | 90 ++++++++++++++++++++++++++++++++ doc/math/vector2.texi | 76 +++++++++++++++++++++++++++ doc/scripting.texi | 21 ++++++++ doc/scripting/actions.texi | 76 +++++++++++++++++++++++++++ doc/scripting/agenda.texi | 37 +++++++++++++ doc/scripting/coroutine.texi | 38 ++++++++++++++ 19 files changed, 1127 insertions(+), 3 deletions(-) create mode 100644 doc/audio.texi create mode 100644 doc/game.texi create mode 100644 doc/graphics.texi create mode 100644 doc/graphics/animation.texi create mode 100644 doc/graphics/color.texi create mode 100644 doc/graphics/font.texi create mode 100644 doc/graphics/sprite.texi create mode 100644 doc/graphics/texture.texi create mode 100644 doc/graphics/tileset.texi create mode 100644 doc/math.texi create mode 100644 doc/math/math.texi create mode 100644 doc/math/rect.texi create mode 100644 doc/math/vector2.texi create mode 100644 doc/scripting.texi create mode 100644 doc/scripting/actions.texi create mode 100644 doc/scripting/agenda.texi create mode 100644 doc/scripting/coroutine.texi (limited to 'doc') diff --git a/doc/audio.texi b/doc/audio.texi new file mode 100644 index 0000000..7f31f29 --- /dev/null +++ b/doc/audio.texi @@ -0,0 +1,98 @@ +@node Audio +@chapter Audio + +Guile-2D provides a simple wrapper over SDL's mixer API for working +with music and sound effects. + +@menu +* Music +* Samples +@end menu + +@node Music +@section Music + +Music objects are used for a game's background music. Only one music +object is playing at any given time. + +@anchor{2d audio make-music}@defspec make-music +@end defspec + +@anchor{2d audio load-music}@defun load-music filename +Load music from FILENAME. Return #f on failure. + +@end defun + +@anchor{2d audio music?}@defspec music? +@end defspec + +@anchor{2d audio music-audio}@defspec music-audio +@end defspec + +@anchor{2d audio music-pause}@defun music-pause +@end defun + +@anchor{2d audio music-paused?}@defun music-paused? +@end defun + +@anchor{2d audio music-play}@defun music-play music +Play MUSIC. + +@end defun + +@anchor{2d audio music-playing?}@defun music-playing? +@end defun + +@anchor{2d audio music-resume}@defun music-resume +@end defun + +@anchor{2d audio music-rewind}@defun music-rewind +@end defun + +@anchor{2d audio music-stop}@defun music-stop +@end defun + +@anchor{2d audio music-volume}@defun music-volume +Return the volume that music is played at. + +@end defun + +@node Samples +@section Samples + +Samples are short audio clips, typically sound effects. Many samples +can be played at the same time. + +@anchor{2d audio make-sample}@defspec make-sample +@end defspec + +@anchor{2d audio load-sample}@defun load-sample filename +Load audio sample from FILENAME. Return #f on failure. + +@end defun + +@anchor{2d audio sample?}@defspec sample? +@end defspec + +@anchor{2d audio sample-audio}@defspec sample-audio +@end defspec + +@anchor{2d audio sample-play}@defun sample-play sample +Play audio SAMPLE. + +@end defun + +@anchor{2d audio sample-volume}@defun sample-volume +Return volume that samples are played at. + +@end defun + +@anchor{2d audio set-music-volume}@defun set-music-volume volume +Set the volume that music is played at. + +@end defun + +@anchor{2d audio set-sample-volume}@defun set-sample-volume volume +Set the volume that samples are played at to VOLUME. + +@end defun diff --git a/doc/game.texi b/doc/game.texi new file mode 100644 index 0000000..82d9435 --- /dev/null +++ b/doc/game.texi @@ -0,0 +1,113 @@ +@node Games and Scenes +@chapter Games and Scenes + +In Guile-2D, games are defined declaratively. Game objects define +things such as the title and screen resolution. Games are composed of +many scenes, which encapsulate a particular aspect of the +game. Examples would be a main menu, a world map, or a battle screen. + +@node Games +@section Games + +@anchor{2d game make-game}@defun make-game [#:title] [#:resolution] [#:fullscreen] [#:first-scene] +Return a new game. All game properties have some reasonable default +value. + +@end defun + +@anchor{2d game define-game}@defspec define-game name kwargs ... +Syntactic sugar over define and make-game. + +@end defspec + +@anchor{2d game game?}@defspec game? +@end defspec + +@anchor{2d game game-first-scene}@defspec game-first-scene +@end defspec + +@anchor{2d game game-fullscreen?}@defspec game-fullscreen? +@end defspec + +@anchor{2d game game-resolution}@defspec game-resolution +@end defspec + +@anchor{2d game game-title}@defspec game-title +@end defspec + +@anchor{2d game run-game}@defun run-game game +Open a window and start the game loop for GAME. + +@end defun + +@node Scenes +@section Scenes + +@anchor{2d game make-scene}@defun make-scene [#:title] [#:events] [#:update] [#:draw] [#:state] +Return a new scene. TITLE is a human readable name for the scene. +EVENTS is an alist of event handlers. UPDATE is a procedure that +updates the scene. DRAW is a procedure that renders the scene. STATE +is an object that encapsulates the scene state. + +@end defun + +@anchor{2d game define-scene}@defspec define-scene name kwargs ... +Syntactic sugar over define and make-scene. Return a procedure that +creates a new scene. + +@end defspec + +@anchor{2d game scene?}@defspec scene? +@end defspec + +@anchor{2d game scene-draw-proc}@defspec scene-draw-proc +@end defspec + +@anchor{2d game scene-observer}@defspec scene-observer +@end defspec + +@anchor{2d game scene-state}@defspec scene-state +@end defspec + +@anchor{2d game scene-title}@defspec scene-title +@end defspec + +@anchor{2d game scene-update-proc}@defspec scene-update-proc +@end defspec + +@anchor{2d game current-fps}@defun current-fps +Return the current FPS value. + +@end defun + +@anchor{2d game default-scene-events}@defun default-scene-events +@end defun + +@anchor{2d game draw-scene}@defun draw-scene scene +Draw SCENE. + +@end defun + +@anchor{2d game pop-scene}@defun pop-scene +Exit the current scene and resume the previous scene. If there is no +previous scene, the game loop will terminate. + +@end defun + +@anchor{2d game push-scene}@defun push-scene scene +Pause the current scene and start SCENE upon next game tick. + +@end defun + +@anchor{2d game replace-scene}@defun replace-scene scene +@end defun + +@anchor{2d game scene-trigger}@defun scene-trigger scene event-type . args +Trigger an event on the scene observer. + +@end defun + +@anchor{2d game update-scene}@defun update-scene scene +Update SCENE. + +@end defun diff --git a/doc/graphics.texi b/doc/graphics.texi new file mode 100644 index 0000000..62ecc6d --- /dev/null +++ b/doc/graphics.texi @@ -0,0 +1,23 @@ +@node Graphics +@chapter Graphics + +Graphics are a fundamental part of most computer games. Guile-2D makes +it easy to make sprite-based games by providing all of the necessary +primitives. Graphics are rendered via OpenGL to take advantage of +hardware acceleration. + +@menu +* Sprites:: +* Textures:: +* Animations:: +* Colors:: +* Tilesets:: +* Fonts:: +@end menu + +@include graphics/sprite.texi +@include graphics/texture.texi +@include graphics/animation.texi +@include graphics/color.texi +@include graphics/tileset.texi +@include graphics/font.texi diff --git a/doc/graphics/animation.texi b/doc/graphics/animation.texi new file mode 100644 index 0000000..c872263 --- /dev/null +++ b/doc/graphics/animation.texi @@ -0,0 +1,84 @@ +@node Animations +@section Animations + +Animations are sequences of textures and/or texture regions. Common +uses for animations are to give the illusion that a character is +walking across the screen or swinging their sword at a +monster. Animator objects are used to control the playback of an +animation. + +@anchor{2d animation animation-frame-duration}@defspec animation-frame-duration +@end defspec + +@anchor{2d animation animation-frames}@defspec animation-frames +@end defspec + +@anchor{2d animation animation-loop?}@defspec animation-loop? +@end defspec + +@anchor{2d animation animation?}@defspec animation? +@end defspec + +@anchor{2d animation animator-animation}@defspec animator-animation +@end defspec + +@anchor{2d animation animator-frame}@defspec animator-frame +@end defspec + +@anchor{2d animation animator-playing?}@defspec animator-playing? +@end defspec + +@anchor{2d animation animator-time}@defspec animator-time +@end defspec + +@anchor{2d animation animator?}@defspec animator? +@end defspec + +@anchor{2d animation make-animation}@defspec make-animation +@end defspec + +@anchor{2d animation animation-duration}@defun animation-duration animation +Return the total duration of ANIMATION in ticks. + +@end defun + +@anchor{2d animation animation-frame}@defun animation-frame animation index +Return the texture for the given frame INDEX of ANIMATION. + +@end defun + +@anchor{2d animation animation-length}@defun animation-length animation +Return the number of frames in ANIMATION. + +@end defun + +@anchor{2d animation animator-frame-complete?}@defun animator-frame-complete? animator +Return #t when ANIMATOR is done displaying the current frame. + +@end defun + +@anchor{2d animation animator-next!}@defun animator-next! animator +Advance ANIMATOR to the next frame of its animation. + +@end defun + +@anchor{2d animation animator-next-frame}@defun animator-next-frame animator +Return the next frame index for ANIMATOR. + +@end defun + +@anchor{2d animation animator-texture}@defun animator-texture animator +Return a texture for the ANIMATOR's current frame. + +@end defun + +@anchor{2d animation animator-update!}@defun animator-update! animator +Increment the frame time for the ANIMATOR and advance to the next frame +when necessary. + +@end defun + +@anchor{2d animation make-animator}@defun make-animator animation +Create a new animator for ANIMATION. + +@end defun diff --git a/doc/graphics/color.texi b/doc/graphics/color.texi new file mode 100644 index 0000000..99e69ba --- /dev/null +++ b/doc/graphics/color.texi @@ -0,0 +1,64 @@ +@node Colors +@section Colors + +Colors store RGBA data in OpenGL format. Each color channel has a +value in the range [0, 1]. + +@anchor{2d color make-color}@defspec make-color +@end defspec + +@anchor{2d color color?}@defspec color? +@end defspec + +@anchor{2d color color-r}@defspec color-r +@end defspec + +@anchor{2d color color-g}@defspec color-g +@end defspec + +@anchor{2d color color-b}@defspec color-b +@end defspec + +@anchor{2d color color-a}@defspec color-a +@end defspec + +@anchor{2d color use-color}@defun use-color color +Set the current OpenGL color state to the contents of COLOR. + +@end defun + +A lot of people are used to working with colors as hexadecimal values, +so the following procedures are provided to convert hexadecimal color +codes into color objects. + +@anchor{2d color rgba}@defun rgba color-code +Translate an RGBA format string COLOR-CODE into a color object. For +example: #xffffffff will return a color with RGBA values 1, 1, 1, 1. + +@end defun + +@anchor{2d color rgb}@defun rgb color-code +Translate an RGB format string COLOR-CODE into a color object. For +example: #xffffff will return a color with RGBA values 1, 1, 1, 1. + +@end defun + +Commonly used colors are predefined for convenience. + +@anchor{2d color white}@defvar white +@end defvar + +@anchor{2d color black}@defvar black +@end defvar + +@anchor{2d color red}@defvar red +@end defvar + +@anchor{2d color green}@defvar green +@end defvar + +@anchor{2d color blue}@defvar blue +@end defvar + +@anchor{2d color magenta}@defvar magenta +@end defvar diff --git a/doc/graphics/font.texi b/doc/graphics/font.texi new file mode 100644 index 0000000..59057a2 --- /dev/null +++ b/doc/graphics/font.texi @@ -0,0 +1,70 @@ +@node Fonts +@section Fonts + +Guile-2D can render TTF fonts via the FTGL library. + +@anchor{2d font font-ftgl-font}@defspec font-ftgl-font +@end defspec + +@anchor{2d font font-size}@defspec font-size +@end defspec + +@anchor{2d font font?}@defspec font? +@end defspec + +@anchor{2d font make-font}@defspec make-font +@end defspec + +@anchor{2d font set-textbox-color!}@defspec set-textbox-color! +@end defspec + +@anchor{2d font set-textbox-position!}@defspec set-textbox-position! +@end defspec + +@anchor{2d font set-textbox-text!}@defspec set-textbox-text! +@end defspec + +@anchor{2d font textbox-alignment}@defspec textbox-alignment +@end defspec + +@anchor{2d font textbox-color}@defspec textbox-color +@end defspec + +@anchor{2d font textbox-font}@defspec textbox-font +@end defspec + +@anchor{2d font textbox-layout}@defspec textbox-layout +@end defspec + +@anchor{2d font textbox-line-length}@defspec textbox-line-length +@end defspec + +@anchor{2d font textbox-position}@defspec textbox-position +@end defspec + +@anchor{2d font textbox-text}@defspec textbox-text +@end defspec + +@anchor{2d font textbox?}@defspec textbox? +@end defspec + +@anchor{2d font draw-font}@defun draw-font font text +Renders the string text using the given font. + +@end defun + +@anchor{2d font draw-textbox}@defun draw-textbox textbox +Draw TEXTBOX. + +@end defun + +@anchor{2d font load-font}@defun load-font filename size +Load a font from FILENAME with the given SIZE in points. + +@end defun + +@anchor{2d font make-textbox}@defun make-textbox font text position color alignment line-length +Create a textbox that will draw TEXT with the given FONT, at vector +POSITION, with ALIGNMENT, and a maximum LINE-LENGTH. + +@end defun diff --git a/doc/graphics/sprite.texi b/doc/graphics/sprite.texi new file mode 100644 index 0000000..9b20e3f --- /dev/null +++ b/doc/graphics/sprite.texi @@ -0,0 +1,121 @@ +@node Sprites +@section Sprites + +Sprites are typically the most important part of a 2D game. Sprites +represent a texture with a specific color, position, rotation and +scale. Sprites can render texture objects or animations. + +@anchor{2d sprite set-sprite-batch-size!}@defspec set-sprite-batch-size! +@end defspec + +@anchor{2d sprite set-sprite-batch-texture!}@defspec set-sprite-batch-texture! +@end defspec + +@anchor{2d sprite set-sprite-drawable!}@defspec set-sprite-drawable! +@end defspec + +@anchor{2d sprite set-sprite-vertices!}@defspec set-sprite-vertices! +@end defspec + +@anchor{2d sprite sprite-anchor}@defspec sprite-anchor +@end defspec + +@anchor{2d sprite sprite-batch-max-size}@defspec sprite-batch-max-size +@end defspec + +@anchor{2d sprite sprite-batch-size}@defspec sprite-batch-size +@end defspec + +@anchor{2d sprite sprite-batch-texture}@defspec sprite-batch-texture +@end defspec + +@anchor{2d sprite sprite-batch-vertices}@defspec sprite-batch-vertices +@end defspec + +@anchor{2d sprite sprite-batch?}@defspec sprite-batch? +@end defspec + +@anchor{2d sprite sprite-color}@defspec sprite-color +@end defspec + +@anchor{2d sprite sprite-drawable}@defspec sprite-drawable +@end defspec + +@anchor{2d sprite sprite-position}@defspec sprite-position +@end defspec + +@anchor{2d sprite sprite-rotation}@defspec sprite-rotation +@end defspec + +@anchor{2d sprite sprite-scale}@defspec sprite-scale +@end defspec + +@anchor{2d sprite sprite-vertices}@defspec sprite-vertices +@end defspec + +@anchor{2d sprite sprite?}@defspec sprite? +@end defspec + +@anchor{2d sprite with-sprite-batch}@defspec with-sprite-batch batch body ... +@end defspec + +@anchor{2d sprite animated-sprite?}@defun animated-sprite? sprite +Return #t if SPRITE has an animation as its drawable object. + +@end defun + +@anchor{2d sprite draw-sprite}@defun draw-sprite sprite +Render SPRITE to the screen. A sprite batch will be used if one is +currently bound. + +@end defun + +@anchor{2d sprite load-sprite}@defun load-sprite filename [#:position] [#:scale] [#:rotation] [#:color] [#:anchor] +Load a sprite from the file at FILENAME. See make-sprite for optional +keyword arguments. + +@end defun + +@anchor{2d sprite make-sprite}@defun make-sprite drawable [#:position] [#:scale] [#:rotation] [#:color] [#:anchor] +Create a new sprite object. DRAWABLE is either a texture or animation +object. All keyword arguments are optional. POSITION is a vector2 +object with a default of (0, 0). SCALE is a vector2 object that +describes how much DRAWABLE should be strected on the x and y axes, with +a default of 1x scale. ROTATION is an angle in degrees with a default +of 0. COLOR is a color object with a default of white. ANCHOR is +either a vector2 that represents the center point of the sprite, or +'center which will place the anchor at the center of DRAWABLE. Sprites +are centered by default. + +@end defun + +@anchor{2d sprite make-sprite-batch}@defun make-sprite-batch [max-size] +Creates a new sprite batch. The default max-size is 1000. + +@end defun + +@anchor{2d sprite set-sprite-anchor!}@defun set-sprite-anchor! sprite value +@end defun + +@anchor{2d sprite set-sprite-color!}@defun set-sprite-color! sprite value +@end defun + +@anchor{2d sprite set-sprite-position!}@defun set-sprite-position! sprite value +@end defun + +@anchor{2d sprite set-sprite-rotation!}@defun set-sprite-rotation! sprite value +@end defun + +@anchor{2d sprite set-sprite-scale!}@defun set-sprite-scale! sprite value +@end defun + +@anchor{2d sprite sprite-batch-draw}@defun sprite-batch-draw . args +Add a textured quad to the current sprite batch. X, Y, WIDTH, and +HEIGHT represent the quad in pixels. ORIGIN-X and ORIGIN-Y represent +the center point of the quad which is used for rotation. SCALE-X and +SCALE-Y are the scaling factors for the x and y axis, respectively. +ROTATION is the angle in degrees to rotate the quad. U, V, U2, and V2 +represent the texture coordinate region to texture the quad with. COLOR +is a color object. + +@end defun diff --git a/doc/graphics/texture.texi b/doc/graphics/texture.texi new file mode 100644 index 0000000..2ac1503 --- /dev/null +++ b/doc/graphics/texture.texi @@ -0,0 +1,65 @@ +@node Textures +@section Textures + +Textures are images loaded in graphics memory. Guile-2D supports many +texture formats via the FreeImage library. A texture object can +describe a full image or a rectangular section of an image. + +@anchor{2d texture make-texture}@defun make-texture id parent width height s1 t1 s2 t2 +Create a new texture object. ID is the OpenGL texture id. PARENT is a +texture object (if this texture only represents a region of another +texture) or #f. WIDTH and HEIGHT are the texture dimensions in pixels. +S1, T1, S2, and T2 are the OpenGL texture coordinates representing the +area of the texture that will be rendered. + +@end defun + +@anchor{2d texture make-texture-region}@defun make-texture-region texture x y width height +Creates new texture region object. TEXTURE is the region's parent +texture. X, Y, WIDTH, and HEIGHT represent the region of the texture +that will be rendered, in pixels. + +@end defun + +@anchor{2d texture load-texture}@defun load-texture filename +Load a texture from an image file at FILENAME. + +@end defun + +@anchor{2d texture texture?}@defspec texture? +@end defspec + +@anchor{2d texture texture-region?}@defun texture-region? texture +Return #t if TEXTURE has a parent texture. + +@end defun + +@anchor{2d texture texture-id}@defspec texture-id +@end defspec + +@anchor{2d texture texture-width}@defspec texture-width +@end defspec + +@anchor{2d texture texture-height}@defspec texture-height +@end defspec + +@anchor{2d texture texture-s1}@defspec texture-s1 +@end defspec + +@anchor{2d texture texture-t1}@defspec texture-t1 +@end defspec + +@anchor{2d texture texture-s2}@defspec texture-s2 +@end defspec + +@anchor{2d texture texture-t2}@defspec texture-t2 +@end defspec + +@anchor{2d texture surface->texture}@defvar surface->texture +[unbound!] +@end defvar + +@anchor{2d texture draw-texture}@defun draw-texture texture x y [color] +Render a textured quad in GL immediate mode. + +@end defun diff --git a/doc/graphics/tileset.texi b/doc/graphics/tileset.texi new file mode 100644 index 0000000..1f229dc --- /dev/null +++ b/doc/graphics/tileset.texi @@ -0,0 +1,41 @@ +@node Tilesets +@section Tilesets + +In most 2D games, the game world is composed of many small, +rectangular pieces called tiles. In Guile-2D, tilesets are used to +encapsulate a group of uniformly sized texture regions that come from +a single parent texture. + +@anchor{2d tileset make-tileset}@defun make-tileset texture width height [#:margin] [#:spacing] +Return a new tileset that is built by splitting TEXTURE into tiles. + +@end defun + +@anchor{2d tileset load-tileset}@defun load-tileset filename width height [#:margin] [#:spacing] +Return a new tileset that is built by loading the texture at FILENAME +and splitting the texture into tiles. + +@end defun + +@anchor{2d tileset tileset?}@defspec tileset? +@end defspec + +@anchor{2d tileset tileset-tiles}@defspec tileset-tiles +@end defspec + +@anchor{2d tileset tileset-width}@defspec tileset-width +@end defspec + +@anchor{2d tileset tileset-height}@defspec tileset-height +@end defspec + +@anchor{2d tileset tileset-margin}@defspec tileset-margin +@end defspec + +@anchor{2d tileset tileset-spacing}@defspec tileset-spacing +@end defspec + +@anchor{2d tileset tileset-ref}@defun tileset-ref tileset i +Return the tile texture of TILESET at index I. + +@end defun diff --git a/doc/guile-2d.texi b/doc/guile-2d.texi index c05bc26..8789f1d 100644 --- a/doc/guile-2d.texi +++ b/doc/guile-2d.texi @@ -27,9 +27,9 @@ The document was typeset with @end copying @titlepage -@title Guile-2D +@title Guile-2D 0.1 @subtitle Guile-2D is a 2D game development framework for GNU Guile -@author David Thompson +@author David Thompson @page @vskip 0pt plus 1filll @insertcopying @@ -50,11 +50,21 @@ The document was typeset with * Copying This Manual:: * Index:: * Introduction:: +* Games and Scenes:: +* Graphics:: +* Audio:: +* Scripting:: +* Math:: @end menu @c Update all node entries with `C-c C-u C-n'. @c Insert new nodes with `C-c C-c n'. @include introduction.texi +@include game.texi +@include graphics.texi +@include audio.texi +@include scripting.texi +@include math.texi @node Copying This Manual @appendix Copying This Manual diff --git a/doc/introduction.texi b/doc/introduction.texi index 0629a37..c833bf1 100644 --- a/doc/introduction.texi +++ b/doc/introduction.texi @@ -3,4 +3,47 @@ Guile-2D is a 2D game development framework for GNU Guile. Guile-2D aims to be simple for beginners to learn and to provide users with all -of the necessary tools for making 2D computer games. +of the necessary tools for making 2D computer games, such as: Sprites, +tilesets, audio, scripting, and collision detection. + +This manual is a work in progress. You will find that it is lacking in +many areas. If Guile-2D interests you, please consider helping to +improve the documentation. + +@menu +* Goals +* The Game Loop +@end menu + +@node Purpose +@section Purpose + +There are many existing game libraries and engines already, so why +make another one? Well, I, the author, believe that GNU Guile is a +fantastic Scheme implementation with a great purpose: to bring +practical user freedom to the GNU system via Emacs-like +extensibility. There are many libraries available to make games with +languages such as Python, Java, and Lua, but there isn't much out +there for Scheme. Guile-2D aims to change that. + +I originally set out on the journey to write a game in C with a Scheme +scripting layer. A year later, I've decided that it would be best to +create an generic game framework in order to give back to the Guile +community and help promote Guile to game developers. + +Guile-2D draws much inspiration from existing game libraries for +other, more popular programming languages. Pygame, pyglet, and love2d +are very beginner friendly, and Guile-2D hopes to translate their good +ideas into the Scheme world. + +@node The Game Loop +@section The Game Loop + +The game loop is so fundamental that it has to be discussed +immediately, so as to avoid any confusion about how it +operates. Guile-2D's game loop operates on a fixed-timestep of 1/60th +of a second. Time is measured in frames rather in seconds to avoid the +pitfalls of a variable time-based approach. Though the update rate is +fixed, the frame-rate is not. Guile-2D will render at as high of a +framerate as it can. Keyboard and mouse input is polled during every +update and events are emitted to the relevant callbacks. diff --git a/doc/math.texi b/doc/math.texi new file mode 100644 index 0000000..1398eda --- /dev/null +++ b/doc/math.texi @@ -0,0 +1,17 @@ +@node Math +@chapter Math + +Games typically require a lot of linear algebra and trigonometry in +order to function. Guile-2D provides modules to perform 2D vector +math, degree to/from radian conversions, and axis-aligned bounding box +collision tests. + +@menu +* Vectors +* Rectangles +* Miscellaneous +@end menu + +@include math/vector2.texi +@include math/rect.texi +@include math/math.texi diff --git a/doc/math/math.texi b/doc/math/math.texi new file mode 100644 index 0000000..12330f9 --- /dev/null +++ b/doc/math/math.texi @@ -0,0 +1,37 @@ +@node Miscellaneous +@section Miscellaneous + +Miscellaneous math procedures. + +@anchor{2d math pi}@defvar pi +@end defvar + +@anchor{2d math degrees->radians}@defun degrees->radians angle +Convert ANGLE in degrees to radians. + +@end defun + +@anchor{2d math radians->degrees}@defun radians->degrees angle +Convert ANGLE in radians to degrees. + +@end defun + +@anchor{2d math sin-degrees}@defun sin-degrees angle +Compute the sin of ANGLE expressed in degrees. + +@end defun + +@anchor{2d math cos-degrees}@defun cos-degrees angle +Compute the cosine of ANGLE expressed in degrees. + +@end defun + +@anchor{2d math tan-degrees}@defun tan-degrees angle +Compute the tangent of ANGLE expressed in degrees. + +@end defun + +@anchor{2d math atan-degrees}@defun atan-degrees y x +Compute the arctangent in degrees of the coordinates Y and X. + +@end defun diff --git a/doc/math/rect.texi b/doc/math/rect.texi new file mode 100644 index 0000000..62477ea --- /dev/null +++ b/doc/math/rect.texi @@ -0,0 +1,90 @@ +@node Rectangles +@section Rectangles + +Rects are axis-aligned bounding boxes that can be used for performing +simple collision detection. + +@anchor{2d rect make-rect}@defspec make-rect +@end defspec + +@anchor{2d rect rect?}@defspec rect? +@end defspec + +@anchor{2d rect rect-x}@defspec rect-x +@end defspec + +@anchor{2d rect rect-y}@defspec rect-y +@end defspec + +@anchor{2d rect rect-x2}@defun rect-x2 rect +@end defun + +@anchor{2d rect rect-y2}@defun rect-y2 rect +@end defun + +@anchor{2d rect rect-center-x}@defun rect-center-x rect +@end defun + +@anchor{2d rect rect-center-y}@defun rect-center-y rect +@end defun + +@anchor{2d rect rect-half-width}@defun rect-half-width rect +@end defun + +@anchor{2d rect rect-half-height}@defun rect-half-height rect +@end defun + +@anchor{2d rect rect-width}@defspec rect-width +@end defspec + +@anchor{2d rect rect-height}@defspec rect-height +@end defspec + +@anchor{2d rect rect-position}@defun rect-position rect +Return the top-left corner of RECT as a vector2. + +@end defun + +@anchor{2d rect rect-size}@defun rect-size rect +Return the size of RECT as a vector2. + +@end defun + +@anchor{2d rect rect-move}@defun rect-move rect v +Create a new rectangle by moving RECT by the given offset. rect-move +accepts a vector2 or x and y coordinates as separate arguments. + +@end defun + +@anchor{2d rect rect-inflate}@defun rect-inflate rect v +Create a new rectangle by growing RECT by the given amount without +changing the center point. rect-inflate accepts a vector2 or x and y +coordinates as separate arguments. + +@end defun + +@anchor{2d rect rect-union}@defun rect-union rect1 rect2 +Return a rect that covers the area of RECT1 and RECT2. + +@end defun + +@anchor{2d rect rect-clip}@defun rect-clip rect1 rect2 +Return the overlapping region of RECT1 and RECT2. If the rects do not +overlap, a rect of size 0 is returned. + +@end defun + +@anchor{2d rect rect-within?}@defun rect-within? rect1 rect2 +Return #t if RECT2 is completely within RECT1. + +@end defun + +@anchor{2d rect rect-intersects?}@defun rect-intersects? rect1 rect2 +Return #t if RECT2 overlaps RECT1. + +@end defun + +@anchor{2d rect rect-contains?}@defun rect-contains? rect v +Return #t if the given point is within RECT. + +@end defun diff --git a/doc/math/vector2.texi b/doc/math/vector2.texi new file mode 100644 index 0000000..13c2f80 --- /dev/null +++ b/doc/math/vector2.texi @@ -0,0 +1,76 @@ +@node Vectors +@section Vectors + +2D vector math operations. Vector objects are of type vector2 to avoid +confusion with regular Scheme vectors. + +@anchor{2d vector2 vector2}@defspec vector2 +@end defspec + +@anchor{2d vector2 vector2?}@defspec vector2? +@end defspec + +@anchor{2d vector2 vx}@defspec vx +@end defspec + +@anchor{2d vector2 vy}@defspec vy +@end defspec + +@anchor{2d vector2 null-vector2}@defvar null-vector2 +@end defvar + +@anchor{2d vector2 identity-vector2}@defvar identity-vector2 +@end defvar + +@anchor{2d vector2 vector2-polar}@defun vector2-polar r theta +Convert the polar coordinates (R, THETA) into a cartesian vector. + +@end defun + +@anchor{2d vector2 v+}@defun v+ . vectors +Return the sum of all VECTORS. + +@end defun + +@anchor{2d vector2 v*}@defun v* . vectors +Return the product of all VECTORS. + +@end defun + +@anchor{2d vector2 vscale}@defun vscale v scalar +Multiply the vector V by a scalar value. + +@end defun + +@anchor{2d vector2 vmag}@defun vmag v +Return the magnitude of the vector V. + +@end defun + +@anchor{2d vector2 vnorm}@defun vnorm v +Normalize the vector V. + +@end defun + +@anchor{2d vector2 vdot}@defun vdot v1 v2 +Return the dot product of the vectors V1 and V2. + +@end defun + +@anchor{2d vector2 vcross}@defun vcross v1 v2 +Return the cross product of the vectors V1 and V2. Technically, the +cross product of a 2D vector is not defined. This function instead +returns the Z coordinate of the cross product as if the vectors were in +3D space. + +@end defun + +@anchor{2d vector2 vector2-translate}@defun vector2-translate v +Perform an OpenGL translate operation with the vector V. + +@end defun + +@anchor{2d vector2 vector2-scale}@defun vector2-scale v +Perform an OpenGL scale operation with the vector V. + +@end defun diff --git a/doc/scripting.texi b/doc/scripting.texi new file mode 100644 index 0000000..951fe2d --- /dev/null +++ b/doc/scripting.texi @@ -0,0 +1,21 @@ +@node Scripting +@chapter Scripting + +The ability to write scripts is very important for most games. Scripts +are short programs that modify game state. In an RPG, one might want +to write a script that causes an NPC to walk up to the player and +begin a conversation with them. Guile-2D allows for easy, linear +script writing by using cooperative multitasking, also known as +coroutines. Agendas are used to schedule scripts to be run at distinct +points in game time, and actions provide an API to describe +transformations that happen over a period of game time. + +@menu +* Coroutines +* Agendas +* Actions +@end menu + +@include scripting/coroutine.texi +@include scripting/agenda.texi +@include scripting/actions.texi diff --git a/doc/scripting/actions.texi b/doc/scripting/actions.texi new file mode 100644 index 0000000..96b0c3c --- /dev/null +++ b/doc/scripting/actions.texi @@ -0,0 +1,76 @@ +@node Actions +@section Actions + +Actions are composable procedures that perform an operation over a +period of game time. Action objects have two properties: an arbitrary +procedure and a duration in game ticks. Action procedures accept one +argument: a time delta in the range [0, 1]. Use actions in combination +with coroutines for things that are a function of time, such as moving +a sprite across the screen. + +@anchor{2d actions make-action}@defun make-action proc duration +Create a new action object that takes DURATION updates to complete. PROC +is a procedure that takes a value in the range [0, 1] as its only +argument. An error is thrown if DURATION is 0. + +@end defun + +@anchor{2d actions action?}@defspec action? +@end defspec + +@anchor{2d actions null-action}@defvar null-action +[unbound!] +@end defvar + +@anchor{2d actions null-action?}@defvar null-action? +[unbound!] +@end defvar + +@anchor{2d actions action-duration}@defspec action-duration +@end defspec + +@anchor{2d actions action-proc}@defspec action-proc +@end defspec + +@anchor{2d actions perform-action}@defun perform-action action +Execute ACTION. `perform-action` must be called from within a +coroutine, as it yields back to the agenda after each step. + +@end defun + +@anchor{2d actions schedule-action}@defun schedule-action action +Schedules a coroutine in the current agenda that will perform ACTION on +the next update. + +@end defun + +@anchor{2d actions action-cons}@defun action-cons a1 a2 +Return an action that performs A1 first, followed by A2. + +@end defun + +@anchor{2d actions action-list}@defun action-list . actions +Return an action that performs every action in the list ACTIONS. + +@end defun + +@anchor{2d actions action-parallel}@defun action-parallel . actions +Perform every action in the list ACTIONS in parallel. + +@end defun + +@anchor{2d actions action-repeat}@defun action-repeat n action +Return an action that will perform ACTION N times. + +@end defun + +@anchor{2d actions idle}@defun idle duration +Return an action that does nothing. + +@end defun + +@anchor{2d actions lerp}@defun lerp proc start end duration +Linearly interpolate a number from START to END that takes DURATION +updates. Apply PROC to the linearly interpolated at each step. + +@end defun diff --git a/doc/scripting/agenda.texi b/doc/scripting/agenda.texi new file mode 100644 index 0000000..2954c15 --- /dev/null +++ b/doc/scripting/agenda.texi @@ -0,0 +1,37 @@ +@node Agendas +@section Agendas + +Agendas are used to schedule procedures to be called at distinct +points in game time. + +@anchor{2d agenda make-agenda}@defun make-agenda +Create a new, empty agenda. + +@end defun + +@anchor{2d agenda with-agenda}@defspec with-agenda agenda body ... +@end defspec + +@anchor{2d agenda agenda-schedule}@defun agenda-schedule thunk [delay] +Schedule THUNK in the current agenda to run after DELAY updates (1 by +default). + +@end defun + +@anchor{2d agenda agenda-schedule-interval}@defun agenda-schedule-interval thunk [interval] [delay] +Schedule THUNK in the current agenda to run after DELAY updates and run +every INTERVAL updates thereafter. Both DELAY and INTERVAL default to +1. Simply pass THUNK and nothing else to schedule THUNK to be run upon +every update. + +@end defun + +@anchor{2d agenda update-agenda}@defun update-agenda +Update the current agenda. + +@end defun + +@anchor{2d agenda clear-agenda}@defun clear-agenda +Clear the current agenda. + +@end defun diff --git a/doc/scripting/coroutine.texi b/doc/scripting/coroutine.texi new file mode 100644 index 0000000..75723da --- /dev/null +++ b/doc/scripting/coroutine.texi @@ -0,0 +1,38 @@ +@node Coroutines +@section Coroutines + +Coroutines are the building block for cooperative multitasking. When +used with agendas, they are a powerful mechanism for writing game +scripts. + +@anchor{2d coroutine coroutine}@defun coroutine thunk +Calls a procedure that can yield a continuation. + +@end defun + +@anchor{2d coroutine colambda}@defspec colambda args body ... +Syntacic sugar for a lambda that is run as a coroutine. + +@end defspec + +@anchor{2d coroutine codefine}@defspec codefine (name ...) . body +Syntactic sugar for defining a procedure that is run as a coroutine. + +@end defspec + +@anchor{2d coroutine codefine*}@defspec codefine* (name ...) . body +Syntactic sugar for defining a procedure with optional and keyword +arguments that is run as a coroutine. + +@end defspec + +@anchor{2d coroutine wait}@defun wait [delay] +Yield coroutine and schdule the continuation to be run after DELAY +ticks. + +@end defun + +@anchor{2d coroutine yield}@defun yield callback +Yield continuation to a CALLBACK procedure. + +@end defun -- cgit v1.2.3