Difference between revisions of "Manual:DIL Manual/restore()"

From DikuMUD Wiki
Jump to navigation Jump to search
(checked against the compiler and the interpreter; example compiles)
(corrected from the DIL keyword tests (T029-T043))
 
Line 26: Line 26:
  
 
== Notes ==
 
== Notes ==
 +
* A program read from a file (a room's or object's program when the zone boots, a unit brought back with [[Manual:DIL Manual/restore()|restore()]], a <code>recall</code> program on a player) doesn't run until the first event reaches it, and that event only takes it as far as its <code>wait()</code>: the event itself is lost. A room program waiting for a command misses the first one after a boot. Programs on units that <code>%reset</code> loads start at once and aren't affected.
 
* The files are in the <code>units</code> folder of the zone's DIL file directory, or of the
 
* The files are in the <code>units</code> folder of the zone's DIL file directory, or of the
 
   server's <code>dil_file_dir</code> (<code>server.cfg</code>) when the zone has none.
 
   server's <code>dil_file_dir</code> (<code>server.cfg</code>) when the zone has none.

Latest revision as of 07:21, 15 November 2026

restore()

Function (unitptr). Loads units saved with store() back into the game.

restore(filename : string, u : unitptr)

Reads the file that store() wrote and loads the units in it into u, or into the unit running the program when u is null. Units inside other units come back inside them, and equipment a character wore is worn again. With store() this keeps things through a reboot: a chest's contents, a room's donations, parcels in a mail system.

Parameters

Name Type Meaning
filename string The file's name, as given to store(): letters, digits, _ and . only, at most 512 characters.
u unitptr The unit to put them in, or null for the unit running the program.

Returns

unitptr: the first unit loaded, whether u is null or not. That is the container when it was stored with store(u, name, TRUE), and otherwise the first of the stored contents (the others are in u too). Null when there is no such file, or it is empty.

Notes

  • A program read from a file (a room's or object's program when the zone boots, a unit brought back with restore(), a recall program on a player) doesn't run until the first event reaches it, and that event only takes it as far as its wait(): the event itself is lost. A room program waiting for a command misses the first one after a boot. Programs on units that %reset loads start at once and aren't affected.
  • The files are in the units folder of the zone's DIL file directory, or of the
 server's dil_file_dir (server.cfg) when the zone has none.
  • A name with other characters (a /, a space) is refused with a line in the zone's
 log, and the result is null.
  • Restoring doesn't remove the file: restore it twice and you have two copies. Remove it with
 delunit() when it has served.
  • store() of a unit with nothing in it writes no file, so an older file stays and
 is restored. Use delunit() when the unit is empty, as in the example.
  • A unit whose definition no longer exists in its zone comes back as slime
 (The slimy remains of ...).
  • Only zones whose access level in zonelist is 10 or less may use it. In other
 zones the program stops at once, and the attempt is logged.
  • It reads the disk: don't call it often.

Example

dilbegin keep_chest();
var
   u : unitptr;
   i : integer;
   fn : string;
code
{
   fn := "chest_" + self.nameidx + "." + self.zoneidx;
   u := restore(fn, self);         // put back what was in it before the reboot

   heartbeat := PULSE_SEC * 300;
   :start:
   pause;
   if (self.inside == null)
      i := delunit(fn);            // store() of an empty chest writes nothing
   else
      store(self, fn, FALSE);      // the contents, not the chest
   goto start;
}
dilend

A chest that keeps its contents through reboots: it puts back what it held, then saves its contents every five minutes.

See also