--- deliantra/server/lib/cf/mapscript.pm	2009/01/08 03:03:24	1.1
+++ deliantra/server/lib/cf/mapscript.pm	2009/07/16 21:42:56	1.5
@@ -1,24 +1,100 @@
 #! perl
 
-# this implements the mapscript connectable
+=head1 NAME
+
+cf::mapscript
+
+=head1 DESCRIPTION
+
+This module implements the mapscript object.
+
+Map scripts are perl snippets that get executed whenever any connected
+element is triggered (e.g. a check inv, a lever etc.)
+
+=head1 ENVIRONMENT
+
+The map scripts are compiled and executed into a namespace with the
+following symbols available:
+
+=over 4
+
+=cut
 
 package safe::mapscript;
 
 use strict qw(subs vars);
 
-our ($self, $activator, $state);
+=item $self
+
+The mapscript object itself
+
+=item $state
+
+The state value (0 means release, <>0 means push/trigger/enable) that
+triggered the map script.
+
+=item $activator
+
+The object that was triggered (the lever, check inv element, npc etc.).
+
+=item $originator
+
+The object that triggered the activator, usually (but not always) the
+player who stepped on a check inv, pulled a lever etc. Can be C<undef>.
+
+=cut
+
+our ($self, $state, $activator, $originator);
+
+=item @obs = find $id_or_object
+
+Finds all objects with the given I<connected> C<$id>. If an object
+reference is passed, it will be returned unchanged.
+
+=cut
+
+sub find($) {
+   ref $_[0] ? $_[0]
+             : $self->map->find_link ($_[0])
+}
+
+=item trigger $id_or_object[, $state]
+
+Triggers the linked chain with the given I<connected> id, or the connected
+chain associated with the given object (if an objetc reference is passed),
+and passes the given state (or C<1>, if missing) to it.
+
+=cut
+
+sub trigger($;$) {
+   $self->map->trigger ($_[0], $#_ ? $_[1] : 1, $self);
+}
+
+=item timer $id_or_object, $seconds
+
+Starts the timer on the given mapscript object (usually, $id_or_object is
+C<$self>). When the timer expires on the mapscript object, it will trigger
+the script with C<$activator == $self> and C<$originator == undef>.
+
+=cut
+
+sub timer($$) {
+   my $ob = (&find)[0];
+   $ob->speed_left (-$_[1] / cf::TICK);
+   $ob->set_speed (1);
+}
 
 package cf::mapscript;
 
 use strict qw(subs vars);
 
-sub activate($$$) {
-   ($self, $activator, $state) = @_;
+our %CACHE;
 
-   warn "$self->{msg} $self->{on_activate}\n";#d#
+sub activate($$$) {
+   ($self, $state, $activator, $originator) = @_;
 
    (
-      $self->{on_activate} ||= cf::safe_eval
+      $CACHE{$self->msg} ||= cf::safe_eval
          "package mapscript; sub {\n"
          . "#line 1 '" . ($self->debug_desc) . "'\n"
          . $self->msg
@@ -27,4 +103,12 @@
    )->();
 }
 
+=back
+
+=head1 EXAMPLE
+
+Have a look at F<scorn/anthonty/portgate.map> for a nontrivial example.
+
+=cut
+
 1;