diff options
Diffstat (limited to 'doc/chickadee.texi')
| -rw-r--r-- | doc/chickadee.texi | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/doc/chickadee.texi b/doc/chickadee.texi index db2ebc6..06535c9 100644 --- a/doc/chickadee.texi +++ b/doc/chickadee.texi @@ -51,6 +51,8 @@ The document was typeset with @c Generate the nodes for this menu with `C-c C-u C-m'. @menu * Installation:: Installing Chickadee. +* Getting Started:: Writing your first Chickadee program. +* Command Line Interface:: Run Chickadee programs from the terminal. * API Reference:: Chickadee API reference. * Copying This Manual:: The GNU Free Documentation License and you! @@ -93,6 +95,188 @@ Additionally, Chickadee depends on being able to create an OpenGL 3.3 context at runtime, which means that some older computers may not be able to run games written with Chickadee. +@node Getting Started +@chapter Getting Started + +One of the simplest programs we can make with Chickadee is rendering +the text ``Hello, world'' on screen. Here's what that looks like: + +@example +(define (draw alpha) + (draw-text "Hello, world!" (vec2 64.0 240.0))) +@end example + +The @code{draw} procedure is called frequently to draw the game scene. +For the sake of simplicity, we will ignore the @code{alpha} variable +in this tutorial. + +To run this program, we'll use the @command{chickadee play} command: + +@example +chickadee play hello.scm +@end example + +This is a good start, but it's boring. Let's make the text move! + +@example +(define position (vec2 0.0 240.0)) + +(define (draw alpha) + (draw-text "Hello, world!" position)) + +(define (update dt) + (set-vec2-x! position (+ (vec2-x position) (* 100.0 dt)))) +@end example + +The @code{vec2} type is used to store 2D coordinates +(@pxref{Vectors}.) A variable named @code{position} contains the +position where the text should be rendered. A new hook called +@code{update} has been added to handle the animation. This hook is +called frequently to update the state of the game. The variable +@code{dt} (short for ``delta-time'') contains the amount of time that +has passed since the last update, in seconds. Putting it all +together, this update procedure is incrementing the x coordinate of +the position by 100 pixels per second. + +This is neat, but after a few seconds the text moves off the screen +completely, never to be seen again. It would be better if the text +bounced back and forth against the sides of the window. + +@example +(define position (vec2 0.0 240.0)) + +(define (draw alpha) + (draw-text "Hello, world!" position)) + +(define (update dt) + (update-agenda dt)) + +(define (update-x x) + (set-vec2-x! position x)) + +(let ((start 0.0) + (end 536.0) + (duration 4.0)) + (script + (while #t + (tween duration start end update-x) + (tween duration end start update-x)))) +@end example + +This final example uses Chickadee's scripting features +(@pxref{Scripting}) to bounce the text between the edges of the window +indefinitely using the handy @code{tween} procedure. The only thing +the @code{update} procedure needs to do now is advance the clock of +the ``agenda'' (the thing that runs scripts.) The script takes care +of the rest. + +This quick tutorial has hopefully given you a taste of what you can do +with Chickadee. The rest of this manual gets into all of the details +that were glossed over, and much more. Try rendering a sprite, +playing a sound effect, or handling keyboard input. But most +importantly: Have fun! + +@node Command Line Interface +@chapter Command Line Interface + +While Chickadee is a library at heart, it also comes with a command +line utility to make it easier to get started. + +@menu +* Invoking chickadee play:: Run Chickadee programs +@end menu + +@node Invoking chickadee play +@section Invoking @command{chickadee play} + +The @command{chickadee play} command is used to open a window and run +the Chickadee game contained within a Scheme source file. + +@example +chickadee play the-legend-of-emacs.scm +@end example + +In this file, special procedures may be defined to handle various +events from the game loop: + +@itemize +@item load-game +@item quit-game +@item draw +@item update +@item key-press +@item key-release +@item text-input +@item mouse-press +@item mouse-release +@item mouse-move +@item mouse-wheel +@item controller-add +@item controller-remove +@item controller-press +@item controller-release +@item controller-move +@end itemize + +See @ref{The Game Loop} for complete information on all of these +hooks, such as the arguments that each procedure receives. + +In additional to evaluating the specified source file, the directory +containing that file is added to Guile's load path so that games can +easily be divided into many different files. Furthermore, that +directory is entered prior to evaluating the file so that data files +(images, sounds, etc.) can be loaded relative to the main source file, +regardless of what the current directory was when @command{chickadee +play} was invoked. + +Many aspects of the initial game window and environment can be +controlled via the following options: + +@table @code +@item --title=@var{title} +@itemx -t @var{title} + +Set the window title to @var{title}. + +@item --width=@var{width} +@itemx -w @var{width} + +Set the window width to @var{width} pixels. + +@item --height=@var{height} +@itemx -h @var{height} + +Set the window height to @var{height} pixels. + +@item --fullscreen +@itemx -f + +Open window in fullscreen mode. + +@item --resizable +@itemx -r + +Make window resizable. + +@item --update-hz=@var{n} +@itemx -u @var{n} + +Update the game @var{n} times per second. + +@item --repl + +Launch a REPL in the terminal. This will allow the game environment +to debugged and modified without having to stop and restart the game +after each change. + +@item --repl-server[=@var{port}] + +Launch a REPL server on port @var{port}, or 37146 by default. +Especially useful when paired with the +@url{https://www.nongnu.org/geiser/, Geiser} extension for Emacs. + +@end table + @node API Reference @chapter API Reference |