path: root/doc/api/scripting.texi

@node Scripting
@section Scripting

@menu
* Overview::                  Scripting basics.
* Actors::                    Scriptable game objects.
* Actions::                   Action combinators.
@end menu

@node Overview
@subsection Overview

@example
(use-modules (sly actor))
@end example

An actor associates an object within the game world with a ``script''
to control that object.  For example, one can control a non-player
character's movements in a role-playing game with an actor script.
Or, a shoot-em-up game could make the game world itself an actor whose
script adds enemies to the world at designated times.  Like all
high-level interfaces in Sly, it is purely functional.

An actor is a wrapper around another game object.  To create an actor,
use the @code{make-actor} constructor:

@example
(make-actor (make-enemy) script)
@end example

Each script is composed of ``actions'', which are procedures that
perform a user-defined transformation on a game object.  Action
procedures take three arguments: The ``world'', the ``effects'' list,
and the game object itself.

The world is an object that the action can query as part of its logic.
For example, an enemy action that shot a bullet aimed at the player
could query the world to find out the current location of the player.

An effect is a procedure generated by an action that alters the game
world rather than the actor itself.  Going back to the previous
example, in order for the enemy to actually shoot a bullet it would
have to add to the effects list, because adding a bullet alters the
world, not the actor.

An action must return three values: the next action (or @code{#f} if
there is nothing left to do), the new effects lists, and the new game
object.  Let's take a look at the simplest possible action,
@code{idle}, which does not change the game object, nor add an effect,
nor do anything else afterwards:

@example
(define (idle world effects object)
  (values #f effects object))
@end example

Now for something a bit more complicated.  Here's a higher-order
procedure that returns an action that moves an enemy object
horizontally:

@example
(define (move-horizontally x)
  (lambda (world effects object)
    (values #f effects (move-enemy object (vector2 x 0)))))

;; Create a new action that moves the enemy by 3 units.
(move-horizontally 3)
@end example

But what if one wants to wait a turn and then move horizontally?
Enter action combinators, which allow multiple, simpler actions to be
@emph{composed} into a complex action.

To perform actions one after another, use the @code{sequence}
combinator:

@example
(sequence idle
          (move-horizontally 3)
          idle
          (move-horizontally 6))
@end example

To perform actions at the same time, use the @code{together}
combinator:

@example
(together (move-horizontally 3)
          shoot-at-player)
@end example

To perform an action in an unbounded loop, use the @code{forever}
combinator:

@example
(forever (move-horizontally 3))
@end example

To perform an action a fixed number of times, use the @code{repeat}
combinator:

@example
(repeat 10 (move-horizontally 3))
@end example

To perform one of two actions depending upon a condition, like
@code{if} in regular Scheme code, use the @code{ifa} combinator:

@example
(ifa enemy-close-to-player?
     shoot-at-player
     (move-horizontally 3))
@end example

To take a single step in the actor script, use @code{update-actor}:

@example
(update-actor game-world effects-list actor)
@end example

The following sections provide a detailed reference for all of the
procedures in the scripting interface.

@node Actors
@subsection Actors

@deffn {Scheme Procedure} make-actor @var{object} @var{action}
Create a new actor that wraps @var{object}, an arbitrary game object,
and associates it with @var{action}, an action procedure.
@end deffn

@deffn {Scheme Procedure} actor? @var{object}
Return @code{#t} if @var{object} is an actor.
@end deffn

@deffn {Scheme Procedure} actor-ref @var{actor}
Return the object stored within @var{actor}.
@end deffn

@deffn {Scheme Procedure} actor-action @var{actor}
Return the action for @var{actor}.
@end deffn

@deffn {Scheme Procedure} update-actor @var{world} @var{effects} @var{actor}
Apply the action for @var{actor} with the given @var{world}, the game
world object, and @var{effects}, the effects list.
@end deffn

@deffn {Scheme Procedure} actor-filter-update @var{predicate} @var{world} @var{actors}
Update each actor in the list @var{actors} with respect to @var{world}
and return a new list of actors whose objects satisfy @var{predicate}.
@end deffn

@deffn {Scheme Procedure} call-with-actor @var{actor} @var{proc}
Apply @var{proc} with the object stored in @var{actor} and return a
new actor containing the value returned from @var{proc}.  The actor's
action remains unchanged.
@end deffn

@deffn {Scheme Procedure} apply-effects @var{effects} @var{world}
Apply each effect procedure in @var{effects} using @var{world} as an
initial value.  Each successive effect is applied with the world
returned by the previous effect.
@end deffn

@node Actions
@subsection Actions

@deffn {Scheme Procedure} idle @var{world} @var{effects} @var{object}
Do nothing.  Do not change @var{object} nor add anything to
@var{effects}.
@end deffn

@deffn {Scheme Procedure} wait @var{duration}
Create an action that does nothing @var{duration} times.
@end deffn

@deffn {Scheme Procedure} forever @var{action}
Create an action that performs @var{action} in an infinite loop, once
per tick.
@end deffn

@deffn {Scheme Procedure} sequence @var{actions} @dots{}
Create an action that sequentially performs each action in the order
specified in the arguments list.
@end deffn

@deffn {Scheme Procedure} together @var{actions} @dots{}
Create an action that concurrently performs each action in the order
specified in the arguments list.
@end deffn

@deffn {Scheme Procedure} ifa @var{predicate} @var{consequent} @var{alternate}
Create an action that performs @var{consequent} if @var{predicate} is
satisfied, or @var{alternate} otherwise.  @var{predicate} is a
procedure that accepts a single argument: The game object stored
within the actor that is performing the action.
@end deffn

@deffn {Scheme Procedure} whena @var{predicate} @var{consequent}
Create an action that performs @var{consequent} when @var{predicate}
is satisfied, otherwise nothing is done.
@end deffn

@deffn {Scheme Procedure} unlessa @var{predicate} @var{alternate}
Create an action that performs @var{alternate} unless @var{predicate}
is satisfied, otherwise nothing is done.
@end deffn

@deffn {Scheme Procedure} repeat @var{times} @var{action}
Create an action that performs @var{action} @var{times} in a row.
@end deffn

@deffn {Scheme Procedure} action-lift
Create an action constructor from @var{proc}, a procedure of any
number of arguments whose first argument is the game object being
transformed.

@example
(define (move-player player offset) ...)

(define move-player* (action-lift move-player))

;; Create a new action that moves the player horizontally.
(move-player* (vector2 10 0))
@end example

@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
returned as the next action to perform.

This is a low-level combinator.  Use @code{together} instead.
@end deffn

@deffn {Scheme Procedure} then @var{a} @var{b}
Perform action @var{a} followed by action @var{b}.  Unlike
@code{both}, action @var{b} is not performed immediately after @var{a}
finishes, but rather requires another tick.

This is a low-level combinator.  Use @code{sequence} instead.
@end deffn