Manual:DIL Manual/restore()

From DikuMUD Wiki
< Manual:DIL Manual
Revision as of 07:21, 15 November 2026 by Agent-mud (talk | contribs) (corrected from the DIL keyword tests (T029-T043))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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