Rough draft of manual.

3 files changed, 151 insertions, 0 deletions

diff --git a/doc/scripting/actions.texi b/doc/scripting/actions.texi
new file mode 100644
index 0000000..96b0c3c
--- /dev/null
+++ b/doc/scripting/actions.texi
@@ -0,0 +1,76 @@
+@node Actions
+@section Actions
+
+Actions are composable procedures that perform an operation over a
+period of game time. Action objects have two properties: an arbitrary
+procedure and a duration in game ticks. Action procedures accept one
+argument: a time delta in the range [0, 1]. Use actions in combination
+with coroutines for things that are a function of time, such as moving
+a sprite across the screen.
+
+@anchor{2d actions make-action}@defun make-action proc duration
+Create a new action object that takes DURATION updates to complete.  PROC
+is a procedure that takes a value in the range [0, 1] as its only
+argument.  An error is thrown if DURATION is 0.
+
+@end defun
+
+@anchor{2d actions action?}@defspec action?
+@end defspec
+
+@anchor{2d actions null-action}@defvar null-action
+[unbound!]
+@end defvar
+
+@anchor{2d actions null-action?}@defvar null-action?
+[unbound!]
+@end defvar
+
+@anchor{2d actions action-duration}@defspec action-duration
+@end defspec
+
+@anchor{2d actions action-proc}@defspec action-proc
+@end defspec
+
+@anchor{2d actions perform-action}@defun perform-action action
+Execute ACTION.  `perform-action` must be called from within a
+coroutine, as it yields back to the agenda after each step.
+
+@end defun
+
+@anchor{2d actions schedule-action}@defun schedule-action action
+Schedules a coroutine in the current agenda that will perform ACTION on
+the next update.
+
+@end defun
+
+@anchor{2d actions action-cons}@defun action-cons a1 a2
+Return an action that performs A1 first, followed by A2.
+
+@end defun
+
+@anchor{2d actions action-list}@defun action-list . actions
+Return an action that performs every action in the list ACTIONS.
+
+@end defun
+
+@anchor{2d actions action-parallel}@defun action-parallel . actions
+Perform every action in the list ACTIONS in parallel.
+
+@end defun
+
+@anchor{2d actions action-repeat}@defun action-repeat n action
+Return an action that will perform ACTION N times.
+
+@end defun
+
+@anchor{2d actions idle}@defun idle duration
+Return an action that does nothing.
+
+@end defun
+
+@anchor{2d actions lerp}@defun lerp proc start end duration
+Linearly interpolate a number from START to END that takes DURATION
+updates.  Apply PROC to the linearly interpolated at each step.
+
+@end defun
diff --git a/doc/scripting/agenda.texi b/doc/scripting/agenda.texi
new file mode 100644
index 0000000..2954c15
--- /dev/null
+++ b/doc/scripting/agenda.texi
@@ -0,0 +1,37 @@
+@node Agendas
+@section Agendas
+
+Agendas are used to schedule procedures to be called at distinct
+points in game time.
+
+@anchor{2d agenda make-agenda}@defun make-agenda
+Create a new, empty agenda.
+
+@end defun
+
+@anchor{2d agenda with-agenda}@defspec with-agenda agenda body ...
+@end defspec
+
+@anchor{2d agenda agenda-schedule}@defun agenda-schedule thunk [delay]
+Schedule THUNK in the current agenda to run after DELAY updates (1 by
+default).
+
+@end defun
+
+@anchor{2d agenda agenda-schedule-interval}@defun agenda-schedule-interval thunk [interval] [delay]
+Schedule THUNK in the current agenda to run after DELAY updates and run
+every INTERVAL updates thereafter.  Both DELAY and INTERVAL default to
+1.  Simply pass THUNK and nothing else to schedule THUNK to be run upon
+every update.
+
+@end defun
+
+@anchor{2d agenda update-agenda}@defun update-agenda
+Update the current agenda.
+
+@end defun
+
+@anchor{2d agenda clear-agenda}@defun clear-agenda
+Clear the current agenda.
+
+@end defun
diff --git a/doc/scripting/coroutine.texi b/doc/scripting/coroutine.texi
new file mode 100644
index 0000000..75723da
--- /dev/null
+++ b/doc/scripting/coroutine.texi
@@ -0,0 +1,38 @@
+@node Coroutines
+@section Coroutines
+
+Coroutines are the building block for cooperative multitasking. When
+used with agendas, they are a powerful mechanism for writing game
+scripts.
+
+@anchor{2d coroutine coroutine}@defun coroutine thunk
+Calls a procedure that can yield a continuation.
+
+@end defun
+
+@anchor{2d coroutine colambda}@defspec colambda args body ...
+Syntacic sugar for a lambda that is run as a coroutine.
+
+@end defspec
+
+@anchor{2d coroutine codefine}@defspec codefine (name ...) . body
+Syntactic sugar for defining a procedure that is run as a coroutine.
+
+@end defspec
+
+@anchor{2d coroutine codefine*}@defspec codefine* (name ...) . body
+Syntactic sugar for defining a procedure with optional and keyword
+arguments that is run as a coroutine.
+
+@end defspec
+
+@anchor{2d coroutine wait}@defun wait [delay]
+Yield coroutine and schdule the continuation to be run after DELAY
+ticks.
+
+@end defun
+
+@anchor{2d coroutine yield}@defun yield callback
+Yield continuation to a CALLBACK procedure.
+
+@end defun