Add a CLI.

2 files changed, 187 insertions, 0 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 56df86f..b22fd57 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -33,6 +33,9 @@ styles of game loops.  The appropriately named @code{run-game} and
 @code{abort-game} procedures are the entry and exit points to the
 Chickadee game loop.
 
+If you are using @command{chickadee play} to launch your game, then
+calling @code{run-game} is already taken care of for you.
+
 @deffn {Procedure} run-game [#:window-title "Chickadee!"] @
        [#:window-width 640] [#:window-height 480] @
        [#:window-fullscreen? @code{#f}] @
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