diff options
| -rw-r--r-- | doc/api.texi | 374 |
1 files changed, 132 insertions, 242 deletions
diff --git a/doc/api.texi b/doc/api.texi index 5b02d60..5bfad7a 100644 --- a/doc/api.texi +++ b/doc/api.texi @@ -1,9 +1,7 @@ @menu * Kernel:: The fundamental components. -* Input:: Keyboard, mouse, and controller input. * Math:: Linear algebra and more. * Graphics:: Eye candy. -* Audio:: Sound effects and music. * Scripting:: Bringing the game world to life. @end menu @@ -11,138 +9,126 @@ @section Kernel At the very core of Chickadee, in the @code{(chickadee)} 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. +an event loop. This loop, or ``kernel'', is responsible for ensuring +that the game is updated at the desired interval, rendering the +current state of the game world, and handling errors if they occur. The kernel implements what is known as a ``fixed timestep'' game loop, meaning that the game simulation will be advanced by a fixed interval of time and will never vary from frame to frame, unlike some other styles of game loops. The appropriately named @code{run-game} and @code{abort-game} procedures are the entry and exit points to the -Chickadee kernel. +Chickadee game loop kernel. 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} can be used to respond to the -@code{a} 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 @xref{Hooks,,, -guile, GNU Guile Reference Manual}. - -@deffn {Procedure} run-game [#:window-title "Chickadee!"] @ - [#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f] @ +actually respond to input events, update game state, or render output, +the programmer must provide an engine. But don’t worry, you don’t +have to start from scratch! Chickadee comes with a simple engine that +uses SDL to create a graphical window and handle input devices, and +OpenGL to handle rendering. This default engine is enough for most +users to get started writing games quickly. More advanced users may +want to write a custom engine that uses a different I/O system. +Perhaps you are writing a text adventure or roguelike that reads from +and writes to a terminal instead of a graphical window. The game loop +kernel makes no assumptions. + +@deffn {Procedure} run-game [#:update] [#:render] [#:time] [#:error] @ [#:update-hz 60] -Start the event loop. This procedure will not return until +Start the game loop. This procedure will not return until @code{abort-game} is called. -The @code{update-hook} will be run @var{update-hz} times per second. +The core game loop is generic and requires four additional procedures +to operate: -A new graphical window will be opened with @var{window-width} x -@var{window-height} as its dimensions, @var{window-title} as its -title, and in fullscreen mode if @var{window-fullscreen?} is -@code{#t}. -@end deffn +@itemize +@item +@var{update}: Called @var{update-hz} times per second to advance the +game simulation. This procedure is called with a single argument: The +amount of time that has passed since the last update, in milliseconds. +@item +@var{render}: Called each iteration of the loop to render the game to +the desired output device. This procedure is called with a single +argument: A value in the range [0, 1] which represents how much time +has past since the last game state update relative to the upcoming +game state update, as a percentage. Because the game state is updated +independent of rendering, it is often the case that rendering is +occuring between two updates. If the game is rendered as it was +during the last update, a strange side-effect will occur that makes +animation appear rough or ``choppy''. To counter this, the +@var{alpha} 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. +@item +@var{time}: Called to get the current time in milliseconds. This +procedure is called with no arguments. +@item +@var{error}: Called when an error from the @var{update} or +@var{render} procedures reaches the game loop. This procedure is +called with three arguments: The call stack, the error key, and the +error arguments. If no error handler is provided, the default +behavior is to simply re-throw the error. +@end itemize -@deffn {Procedure} abort-game -Stop the currently running Chickadee event loop. @end deffn -@deffn {Procedure} time -Return the current game time in milliseconds. +@deffn {Procedure} abort-game +Stop the currently running Chickadee game loop. @end deffn -@defvr {Variable} load-hook -A hook that is run once when the event loop boots, before any other -hook is run. This hook is run with zero arguments. - -@example -(add-hook! load-hook (lambda () (display "hello!\n"))) -@end example - -@end defvr - -@defvr {Variable} update-hook -A hook that is run every time the game simulation should be advanced. -This hook is run with a single argument @var{dt}, the fixed timestep -that was configured when the event loop was started, in milliseconds. - -@example -(add-hook! update-hook (lambda (dt) (display "tick!\n"))) -@end example +Since most users will want to write 2D/3D games with hardware +accelerated graphics rendering, controlled via keyboard, mouse, or +game controller, Chickadee comes with an easy to use engine just for +this purpose in the @code{(chickadee sdl)} module: +@code{run-game/sdl}. -@end defvr +@deffn {Procedure} run-game/sdl [#:window-title "Chickadee!"] @ + [#:window-width 640] [#:window-height 480] @ + [#:window-fullscreen? @code{#f}] [#:update-hz 60] @ + [#:load] [#:update] [#:draw] [#:quit] @ + [#:key-press] [#:key-release] [#:text-input] @ + [#:mouse-press] [#:mouse-release] [#:mouse-move] @ + [#:controller-add] [#:controller-remove] [#:controller-press] @ + [#:controller-release] [#:controller-move] [#:error] -@defvr {Variable} before-draw-hook -A hook that is run before a frame is rendered. This hook is run with -zero arguments. +Run the Chickadee game loop using the SDL engine. -@example -(add-hook! before-draw-hook (lambda () (display "about to draw!\n"))) -@end example - -@end defvr - -@defvr {Variable} after-draw-hook -A hook that is run after a frame is rendered. This hook is run with -zero arguments. - -@example -(add-hook! after-draw-hook (lambda () (display "done drawing!\n"))) -@end example - -Combined with @code{before-draw-hook}, one can perform a frames per -second calculation to monitor game performance and stability. - -@end defvr - -@defvr {Variable} draw-hook -A hook that is run each time a frame should be rendered. This hook is -run with a single argument @var{alpha}, 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} 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. - -@c TODO: Add example of linear interpolation - -@example -(add-hook! draw-hook (lambda (alpha) (display "<(._.<) \n"))) -@end example +A new graphical window will be opened with @var{window-width} x +@var{window-height} as its dimensions, @var{window-title} as its +title, and in fullscreen mode if @var{window-fullscreen?} is +@code{#t}. -@end defvr +@itemize +@item +@var{load}: Called with zero arguments when the game window has opened +but before the game loop has started. Can be used to perform +initialization that requires an open window and OpenGL context such as +loading textures. -@defvr {Variable} quit-hook -A hook that is run when the user clicks the close button on the game -window. This hook is run with zero arguments. +@item +@var{update}: Called @var{update-hz} times per second with one +argument: The amount of time to advance the game simulation. -@example -(add-hook! quit-hook (lambda () (display "bye!\n"))) -@end example +@item +@var{draw}: Called each time a frame should be rendered with a single +argument known as the @code{alpha} value. See the documentation for +@code{run-game} for an explanation of this value. -@end defvr +@item +@var{quit}: Called with zero arguments when the user tries to close +the game window. The default behavior is to exit the game. -@defvr {Variable} key-press-hook -A hook that is run when a key is pressed on the keyboard. This hook -is run with four arguments: +@item +@var{key-press}: Called with four arguments when a key is pressed on +the keyboard: @enumerate @item @var{key}: The symbolic name of the ``virtual'' key that was pressed. For example: @code{backspace}. 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''. +entirely, such as how the author likes to bind the ``caps lock'' key +to mean ``control''. @item @var{scancode}: The symbolic name of the physical key that was @@ -158,19 +144,9 @@ include @code{ctrl}, @code{alt}, and @code{shift}. @end enumerate -@example -(add-hook! key-press-hook - (lambda (key scancode modifiers repeat?) - (display "pressed key: ") - (display key) - (newline))) -@end example - -@end defvr - -@defvr {Variable} key-release-hook -A hook that is run when a key is released on the keyboard. This hook -is run with three arguments: +@item +@var{key-release}: Called with three arguments when a key is released +on the keyboard: @enumerate @item @@ -186,18 +162,13 @@ were being held down when the key was released. @end enumerate -@end defvr - -@defvr {Variable} text-input-hook -A hook that is run when printable text is typed on the keyboard. This -hook is run with a single argument, @var{text}, a string containing -the text that was entered. -@end defvr - -@defvr {Variable} mouse-press-hook -A hook that is run when a mouse button is pressed. This hook is run -with four arguments: +@item +@var{text-input}: Called with a single argument, a string of text, +when printable text is typed on the keyboard. +@item +@var{mouse-press}: Called with four arguments when a mouse button is +pressed: @enumerate @item @@ -215,11 +186,9 @@ as @code{left}, @code{middle}, or @code{right}. @end enumerate -@end defvr - -@defvr {Variable} mouse-release-hook -A hook that is run when a mouse button is released. This hook is run -with three arguments: +@item +@var{mouse-release}: Called with three arguments when a mouse button +is released: @enumerate @@ -234,11 +203,8 @@ with three arguments: @end enumerate -@end defvr - -@defvr {Variable} mouse-move-hook -A hook that is run when the mouse is moved. This hook is run with -five arguments: +@item +@var{mouse-move}: Called with five arguments when the mouse is moved: @enumerate @@ -262,23 +228,17 @@ mouse was moved. @end enumerate -@end defvr - -@defvr {Variable} controller-add-hook -A hook that is run when a game controller is connected. This hook is -run with a single argument, @var{controller}, the controller that was -connected. -@end defvr +@item +@var{controller-add}: Called with a single argument, an SDL game +controller object, when a game controller is connected. -@defvr {Variable} controller-remove-hook -A hook that is run when a game controller is disconnected. This hook -is run with a single argument, @var{controller}, the controller that -was disconnected. -@end defvr +@item +@var{controller-remove}: Called with a single argument, an SDL game +controller object, when a game controller is disconnected. -@defvr {Variable} controller-press-hook -A hook that is run when a button on a game controller is pressed. -This hook is run with two arguments: +@item +@var{controller-press}: Called with two arguments when a button on a +game controller is pressed: @enumerate @@ -325,12 +285,9 @@ Possible buttons are: @end enumerate -@end defvr - -@defvr {Variable} controller-release-hook -A hook that is run when a button on a game controller is released. - -This hook is run with two arguments: +@item +@var{controller-release}: Called with two arguments when a button on a +game controller is released: @enumerate @@ -342,11 +299,9 @@ This hook is run with two arguments: @end enumerate -@end defvr - -@defvr {Variable} controller-move-hook -A hook that is run when an analog stick or trigger on a game -controller is moved. This hook is run with three arguments +@item +@var{controller-move}: Called with three arguments when an analog +stick or trigger on a game controller is moved: @enumerate @@ -374,27 +329,26 @@ values are: @end enumerate -@end defvr +@item +@var{error}: Called with three arguments when an error occurs: -@node Input -@section Input +@enumerate -Chickadee can handle input events from the keyboard, mouse, and game -controllers. +@item +@var{stack}: The call stack at the point of error. -@menu -* Keyboard:: Keyboard input. -@end menu +@item +@var{key}: The exception key. + +@item +@var{args}: The arguments thrown with the exception. -@node Keyboard -@subsection Keyboard +@end enumerate -@deffn {Procedure} key-pressed? @var{key} -Return @code{#t} if @var{key} is currently being pressed. -@end deffn +The default behavior is to re-throw the error. + +@end itemize -@deffn {Procedure} key-released? @var{key} -Return @code{#t} if @var{key} is not currently being pressed. @end deffn @node Math @@ -962,70 +916,6 @@ The default framebuffer. @node Viewports @subsection Viewports -@node Audio -@section Audio - -Chickadee has two data types for audio: samples and music. Samples -are for short sound effects like explosions. Music is for, well, -uh@dots{}, music. - -Supported file formats include WAV and OGG. - -@deffn {Procedure} load-sample @var{file} -Load audio sample from @var{file}. -@end deffn - -@deffn {Procedure} set-sample-volume! @var{volume} -Set the volume that all samples are played at to @var{volume}, an -integer value between 0 and 128. -@end deffn - -@deffn {Procedure} play-sample @var{sample} -Play @var{sample}. Pretty straightforward! -@end deffn - -@deffn {Procedure} load-music @var{file} -Load music from @var{file}. -@end deffn - -@deffn {Procedure} music-volume -Return the volume level for music, an integer value between 0 and 128. -@end deffn - -@deffn {Procedure} set-music-volume! @var{volume} -Set the volume that music is played at to @var{volume}, an integer -value between 0 and 128. -@end deffn - -@deffn {Procedure} play-music @var{music} [@var{loop?}] -Play @var{music}. If @var{loop?}, play it over and over and over and -over and@dots{} -@end deffn - -@deffn {Procedure} pause-music -Pause the current music track. -@end deffn - -@deffn {Procedure} resume-music -Resume the current music track. -@end deffn - -@deffn {Procedure} rewind-music -estart the current music track from the beginning. -@end deffn - -@deffn {Procedure} stop-music -Stop playing the current music track. -@end deffn - -@deffn {Procedure} music-playing? -Return @code{#t} if music is currently playing. -@end deffn - -@deffn {Procedure} music-paused? -Return @code{#t} if music is currently paused. -@end deffn - @node Scripting @section Scripting |