summaryrefslogtreecommitdiff
path: root/doc/chickadee.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/chickadee.texi')
-rw-r--r--doc/chickadee.texi55
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