From 1f1deea662da4328bf588c0642c8a90c7b1f2144 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Tue, 24 Sep 2013 21:06:41 -0400 Subject: Rough draft of manual. --- doc/scripting/actions.texi | 76 ++++++++++++++++++++++++++++++++++++++++++++ doc/scripting/agenda.texi | 37 +++++++++++++++++++++ doc/scripting/coroutine.texi | 38 ++++++++++++++++++++++ 3 files changed, 151 insertions(+) create mode 100644 doc/scripting/actions.texi create mode 100644 doc/scripting/agenda.texi create mode 100644 doc/scripting/coroutine.texi (limited to 'doc/scripting') 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 -- cgit v1.2.3