This is a description of how the recover feature works and how you can
implement it in your objects.

The file contains both ordinary text and program excerpts of a recoverable
object. Read EVERYTHING since explanatory text is given in the program
parts as well.

What 'recover' is 
=================

When the game reboots, or when a player wants to take a short break for
changing terminal, eat dinner or whatever he should not have to sell all
object and start over later. What is needed is a facility for storing his
objects for a brief period of time during certain circumstances. The
'recover' feature handles this.

Recover is possible IF the gamedriver has issued a memory failure alert (ie
armageddon is active) OR if the player is standing on one of the default or
temporary starting locations that are available.

If any of these two conditions are met AND the object is coded properly,
information about the object is stored in the player when he logs out. The
object is then destroyed, not dropped, so that automatic cloning of
valuable stuff won't happend.

If the player logs in within two hours of logging out, the stored objects
are recovered. If he logs in at a later time they are lost, he won't even
get their value back.

What the player sees
====================

When the player appraises a recoverable object, the string 'This object
seems to be able to last a while' is shown. If he types 'save' while
standing on spot where recover is valid the objects that can be recovered
will glow briefly. This happends when he quits as well. When the player
logs in, he will be told which objects are recovered.

How to implement recover in objects
===================================

The recoverable object should define two functions: 
'public string query_recover()' and 'void init_recover(string arg)'.
When the player quits or saves, the status of the gamedriver and the location
of the player is first checked. If recover is possible the function 
'query_recover()' is called in every object in the inventory of the player.

The function 'query_recover()' should return a string on the format:
"path:rec" where 'path' is the path to the object to restore and 'recg'
is a string used as argument to 'init_recover()'. If the argument 'rec'
is <= 128 bytes in length the entire string will be stored in the player.

When he logs in, within two hours of logging out, the object is cloned
using the path and initialized by a call to 'init_recover()' with the
stored recover string as argument.

Some standard objects, like /std/weapon and /std/armour already contain
code for storing and recovering dynamic variables. Just read the header
of the code to find out how to do. There also exists some examples of
recoverable armour and weapons in the examples part of the documentation.

An easy example of recover code
===============================

I will here give an easy example of the recover code. In this case it is
the /doc/examples/weapon/knife.c with a bit of extra stuff added.

/*
   knife.c

   A sample weapon
*/
inherit "/std/weapon";

#include <macros.h>

static int wtime;

void
create_weapon()
{
    set_name("knife"); set_pname("knives");
    set_short("small knife"); set_pshort("small knives");
    set_adj("small");
    set_long("It is a very simple looking knife, quite deadly though.\n");
 
    set_default_weapon();
    set_wf(this_object());
    wtime = 0;
}

string
query_recover()
{
    return MASTER + ":" + query_wep_recover() + "#k_wt#" + wtime + "#";
}

void
init_recover(string arg)
{
    string foobar;

    init_wep_recover(arg);
    sscanf(arg, "%s#k_wt#%d#%s", foobar, wtime, foobar);
}

wield()
{
    write("You have wielded this knife " + (++wtime) + " times.\n");
}
