diff options
Diffstat (limited to 'doc/chickadee.texi')
| -rw-r--r-- | doc/chickadee.texi | 55 |
1 files changed, 50 insertions, 5 deletions
diff --git a/doc/chickadee.texi b/doc/chickadee.texi index a65af9e..0585688 100644 --- a/doc/chickadee.texi +++ b/doc/chickadee.texi @@ -4,7 +4,7 @@ @settitle The Chickadee Game Toolkit @c %**end of header @copying -Copyright @copyright{} 2017-2020 David Thompson @email{davet@@gnu.org} +Copyright @copyright{} 2017-2021 David Thompson @email{davet@@gnu.org} @quotation Permission is granted to copy, distribute and/or modify this document @@ -53,8 +53,8 @@ The document was typeset with * Installation:: Installing Chickadee. * Getting Started:: Writing your first Chickadee program. * Command Line Interface:: Run Chickadee programs from the terminal. +* Live Coding:: Tips for building games from the REPL. * API Reference:: Chickadee API reference. - * Copying This Manual:: The GNU Free Documentation License and you! * Index:: @end menu @@ -93,7 +93,6 @@ Chickadee depends on the following packages: @item libvorbisfile @end itemize - @node Getting Started @chapter Getting Started @@ -271,11 +270,57 @@ 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. + +@command{telnet localhost 37146} (or whatever port number was given) +will do the trick, but using the @uref{https://www.nongnu.org/geiser/, +Geiser} extension for Emacs is by far the best way to develop at the +REPL with Guile. Use @code{M-x connect-to-guile} to connect to the +REPL server. @end table +@node Live Coding +@chapter Live Coding + +One of the biggest appeals of any Lisp dialect is the ability to use +the ``read-eval-print loop'' (REPL for short) to build programs +iteratively and interactively while the program is running. However, +programs that run in an event loop and respond to user input (such as +a game using the Chickadee library!) require special care for this +workflow to be pleasant. + +If you are using the @command{chickadee play} command to run your +game, then the @code{--repl} or @code{--repl-server} arguments are all +you need to get a live coding environment running. + +If, however, you are using @code{run-game} to start the game loop then +it's still fairly easy to hook up a special kind of REPL by yourself. + +First, create a cooperative REPL server (It's important to use Guile's +cooperative REPL server instead of the standard REPL server in +@code{(system repl server)} to avoid thread synchronization issues). +Then, in the game loop's update procedure, call +@code{poll-coop-repl-server} and pass the REPL object. Here is a +template to follow: + +@example +(use-modules (chickadee) + (system repl coop-server)) + +(define repl (spawn-coop-repl-server)) + +(define (update dt) + (poll-coop-repl-server repl) + ...) + +(run-game #:update update ...) +@end example + +To use the REPL, connect to it via port 37146. Telnet will do the +trick, but using the @uref{https://www.nongnu.org/geiser/, Geiser} +extension for Emacs is by far the best way to develop at the REPL with +Guile. Use @code{M-x connect-to-guile} to connect to the REPL server. + @node API Reference @chapter API Reference |