--- deliantra/server/lib/cf.pm	2006/09/12 22:18:55	1.65
+++ deliantra/server/lib/cf.pm	2006/10/01 10:59:30	1.71
@@ -23,6 +23,32 @@
 our $TICK_WATCHER;
 our $NEXT_TICK;
 
+our %CFG;
+
+#############################################################################
+
+=head2 GLOBAL VARIABLES
+
+=over 4
+
+=item $cf::LIBDIR
+
+The perl library directory, where extensions and cf-specific modules can
+be found. It will be added to C<@INC> automatically.
+
+=item $cf::TICK
+
+The interval between server ticks, in seconds.
+
+=item %cf::CFG
+
+Configuration for the server, loaded from C</etc/crossfire/config>, or
+from wherever your confdir points to.
+
+=back
+
+=cut
+
 BEGIN {
    *CORE::GLOBAL::warn = sub {
       my $msg = join "", @_;
@@ -53,25 +79,43 @@
 my %command;
 my %extcmd;
 
-#############################################################################
-# utility functions
+=head2 UTILITY FUNCTIONS
+
+=over 4
+
+=cut
 
 use JSON::Syck (); # TODO# replace by JSON::PC once working
 
+=item $ref = cf::from_json $json
+
+Converts a JSON string into the corresponding perl data structure.
+
+=cut
+
 sub from_json($) {
    $JSON::Syck::ImplicitUnicode = 1; # work around JSON::Syck bugs
    JSON::Syck::Load $_[0]
 }
 
+=item $json = cf::to_json $ref
+
+Converts a perl data structure into its JSON representation.
+
+=cut
+
 sub to_json($) {
    $JSON::Syck::ImplicitUnicode = 0;  # work around JSON::Syck bugs
    JSON::Syck::Dump $_[0]
 }
 
+=back
+
+=cut
+
 #############################################################################
-# "new" plug-in system
 
-=head3 EVENTS AND OBJECT ATTACHMENTS
+=head2 EVENTS AND OBJECT ATTACHMENTS
 
 =over 4
 
@@ -381,15 +425,15 @@
 
 =back
 
-=head2 methods valid for all pointers
+=cut
 
-=over 4
+#############################################################################
 
-=item $object->valid
+=head2 METHODS VALID FOR ALL CORE OBJECTS
 
-=item $player->valid
+=over 4
 
-=item $map->valid
+=item $object->valid, $player->valid, $map->valid
 
 Just because you have a perl object does not mean that the corresponding
 C-level object still exists. If you try to access an object that has no
@@ -706,7 +750,12 @@
 ;
 
 #############################################################################
-# core extensions - in perl
+
+=head2 CORE EXTENSIONS
+
+Functions and methods that extend core crossfire objects.
+
+=over 4
 
 =item cf::player::exists $login
 
@@ -756,8 +805,21 @@
    $self->send ("ext " . to_json \%msg);
 }
 
+=back
+
+=cut
+
 #############################################################################
-# map scripting support
+
+=head2 SAFE SCRIPTING
+
+Functions that provide a safe environment to compile and execute
+snippets of perl code without them endangering the safety of the server
+itself. Looping constructs, I/O operators and other built-in functionality
+is not available in the safe scripting environment, and the number of
+functions and methods that cna be called is greatly reduced.
+
+=cut
 
 our $safe = new Safe "safe";
 our $safe_hole = new Safe::Hole;
@@ -768,6 +830,16 @@
 
 # here we export the classes and methods available to script code
 
+=pod
+
+The following fucntions and emthods are available within a safe environment:
+
+  cf::object contr pay_amount pay_player
+  cf::object::player player
+  cf::player peaceful
+
+=cut
+
 for (
    ["cf::object"         => qw(contr pay_amount pay_player)],
    ["cf::object::player" => qw(player)],
@@ -779,6 +851,18 @@
       for @funs;
 }
 
+=over 4
+
+=item @retval = safe_eval $code, [var => value, ...]
+
+Compiled and executes the given perl code snippet. additional var/value
+pairs result in temporary local (my) scalar variables of the given name
+that are available in the code snippet. Example:
+
+   my $five = safe_eval '$first + $second', first => 1, second => 4;
+
+=cut
+
 sub safe_eval($;@) {
    my ($code, %vars) = @_;
 
@@ -810,6 +894,21 @@
    wantarray ? @res : $res[0]
 }
 
+=item cf::register_script_function $function => $cb
+
+Register a function that can be called from within map/npc scripts. The
+function should be reasonably secure and should be put into a package name
+like the extension.
+
+Example: register a function that gets called whenever a map script calls
+C<rent::overview>, as used by the C<rent> extension.
+
+   cf::register_script_function "rent::overview" => sub {
+     ...
+   };
+
+=cut
+
 sub register_script_function {
    my ($fun, $cb) = @_;
 
@@ -817,6 +916,10 @@
    *{"safe::$fun"} = $safe_hole->wrap ($cb);
 }
 
+=back
+
+=cut
+
 #############################################################################
 
 =head2 EXTENSION DATABASE SUPPORT
@@ -862,7 +965,7 @@
 
 {
    my $db;
-   my $path = cf::datadir . "/database.pst";
+   my $path = cf::localdir . "/database.pst";
 
    sub db_load() {
       warn "loading database $path\n";#d# remove later
@@ -874,7 +977,7 @@
    sub db_save() {
       warn "saving database $path\n";#d# remove later
       waitpid $pid, 0 if $pid;
-      unless ($pid = fork) {
+      if (0 == ($pid = fork)) {
          $db->{_meta}{version} = 1;
          Storable::nstore $db, "$path~";
          rename "$path~", $path;
@@ -912,6 +1015,13 @@
       }
       db_dirty;
    }
+
+   attach_global
+      prio => 10000,
+      on_cleanup => sub {
+         db_sync;
+      },
+   ;
 }
 
 #############################################################################