actor: Add action-effect-lift.

* sly/actor.scm (action-effect-lift): New procedure.
* doc/api/scripting.texi (Actions): Document it.

2 files changed, 35 insertions, 0 deletions

diff --git a/doc/api/scripting.texi b/doc/api/scripting.texi
index ca2cfd4..299cf0f 100644
--- a/doc/api/scripting.texi
+++ b/doc/api/scripting.texi
@@ -221,6 +221,28 @@ transformed.
 
 @end deffn
 
+@deffn {Scheme Procedure} action-effect-lift @var{proc}
+Create an action constructor from @var{proc}, a procedure of any
+number of arguments, whose first two arguments are the world being
+transformed and the game object being acted upon.  The actions
+returned from this new procedure specify that @var{proc} should be
+performed as an effect on the world, and do not change the actor
+itself.
+
+@example
+;; Theoretical procedure that spawns a new enemy next to the current
+;; enemy actor.
+(define (spawn-enemy world enemy type)
+  (add-enemy world (enemy-position enemy) (make-enemy type))
+
+(define spawn-enemy* (action-effect-lift spawn-enemy))
+
+;; Create a new action that spawns a goblin.
+(spawn-enemy* 'goblin)
+@end example
+
+@end deffn
+
 @deffn {Scheme Procedure} both @var{a} @var{b}
 Peform action @var{a} immediately followed by action @var{b}.  When
 the action is run, the remainder of both @var{a} and @var{b} are
diff --git a/sly/actor.scm b/sly/actor.scm
index fd21a64..5b6d7e3 100644
--- a/sly/actor.scm
+++ b/sly/actor.scm
@@ -37,6 +37,7 @@
             call-with-actor
 
             action-lift
+            action-effect-lift
             idle
             both
             then
@@ -106,6 +107,18 @@ transformed."
               effects
               (apply proc object args)))))
 
+(define (action-effect-lift proc)
+  "Create an action constructor from PROC, a procedure of any number
+of arguments, whose first two arguments are the world being
+transformed and the game object being acted upon.  The actions
+returned from this new procedure specify that PROC should be performed
+as an effect on the world, and do not change the actor itself."
+  (lambda args
+    (lambda (world effects object)
+      (values #f
+              (list (lambda (world) (apply proc world object args)))
+              object))))
+
 (define (idle world effects object)
   "Do nothing.  Do not change OBJECT nor add anything to EFFECTS."
   (values #f effects object))