Doors (Programming)

-- Main.NecAnthrope - 07 May 2004

[ Note that if you already have a working exit and you want to easily doorify it, @make-door exit in the room (ie @make-door south) -- Main.WoodChuck - 02 Sep 2006 ]

This document is intended to give a programmer's specification of door objects within Hellmoo.

Doors are an extension of the generic exit. Like $exit, a $door object is a member of a virtual pair of objects, each one a $door that is resident in a $room. They link to each other via their .otherside property, which points to the opposite member of the pair. They are corified as $door. The basic idea behind doors is to emulate thier real-world function - to provide a method of access control between physical areas.

A door is a container, but only descendants of $lock (see ProgLocks) are allowed to reside inside them.

The properties defined on a $door are as follows:

  * $door.open         
     * The current state of the door (open == 1)
     * Type INT
     * Boolean
     * Set by $door:_open() and $door:_close() (see Verbs section, below)
  * $door.operational      
     * Whether or not the door can open (operational == 1)
     * Type INT
     * Boolean
  * $door.open_action      
     * The action used to open the door (see ProgActions)
     * Type OBJ
  * $door.close_action      
     * The action used to close the door (see ProgActions)
     * Type OBJ
  * $door.autoopen_on_unlock   
     * Whether or not the door automatically opens when it is unlocked.  Default is 0
     * Type INT
     * Boolean
     * Set by $door:autoopen_on_unlock() (see Verbs section, below)
  * $door.autoclose_on_lock   
     * Whether or not the door automatically closes when it is locked.  Default is 1
     * Type INT
     * Boolean
     * Set by $door:autoclose_on_lock() (see Verbs section, below)
  * $door.lock_installable   
     * Whether or not locks can be installed in a door.  Default is 1
     * Type INT
     * Boolean
     * Set by $door:lock_installable() (see Verbs section, below)
  * $door.health   
     * Type INT      
     * How much damage the door can take
  * $door.health_max      
     * The maxiumum amount of damage capacity possessed by the door
     * Type INT
  * $door.armor         
     * Any inherent armor the door possesses due to its composition (i.e. wood, steel, etc)
     * Type LIST
     * Structured similarly to the .armor property in $clothing (See ProgClothing)
     * Example: {{#269,2,4},{#277,4,8}} - Deflects 2-4 points of beating and 4-8 points of slashing
     * Type '@tree $damage with kids' to see damage type objects
  * $door.squeals         
     * The message set used in messages when the door is bashed (See ProgSqueals)
     * Type OBJ
  * $door.autoclose
     * Whether or not to close automatically after being opened for a short period
     * Type NUM
     * Used by $door:_autoclose() (see Verbs section, below)
  * $door.systems
     * The objrefs for security system objects that can change the door's state
     * Type LIST
     * Used by Security System API (see Verbs section, below)
  * $door.default_attenuation
     * The amount of 'sound reduction' for the door when it is closed. (See ProgExit)
     * Type NUM

The verbs defined on a $door are as follows:

  * open/close
     * Top level, user-invoked verb for changing the door's open state.  Queues events that invoke _open or _close after sanity checks.
  * _open
     * Checks the door's operational status and lock state, invokes _do_open, and announces appropriate messages.
  * _close
     * Check's the door's operational status, invokes _do_open, and announces appropriate messages.
  * _do_open
     * Actually changes the door's state, and the state of the door's .otherside, to open.
     * Sets the door's .attenuation to that of a standard exit (-3) (See ProgExit)
  * _do_close
     * Actually changes the door's state, and the state of the door's .otherside, to closed.
     * Sets the door's .attenuation to it's own .default_attenuation (See ProgExit)
  * lock/unlock
     * Top level, user-invoked verb for changing the door's lock state.  Queues actions that invoke _lock or _unlock after sanity checks.
     * Also checks if the door's .autoopen_on_unlock or .autoclose_on_lock props are set.
        * If so, closes the door if it is being locked, or opens the door if it is being unlocked, respectively.
  * _lock/_unlock
     * Iterates through the door's contents, which should only be descendents of $lock.
     * Invokes logic on each lock to attempt to change its state (see ProgLocks).
  * knock
     * Top level, user-invoked verb.  Simulates knocking on doors.  Queues an event that invokes _knock.
  * _knock
     * Announces messages on either side of the door indicating someone is knocking.
  * pick
     * Top level, user-invoked verb.  Matches on a particular $lock and queues an event that invokes that $lock's _pick verb.  (see ProgLocks)

  * _announce
     * Announces messages on both sides of the door.
     * Invoked by _open/_close, _lock/_unlock, and _pick.

  * look_self
     * Returns text to be printed to the player when someone looks at the door.
  * keyholes
     * Iterates through all $locks in a door, makes a pretty list of those $lock's .keyhole_msg properties, and returns it
     * Invoked by look_self

  * _move
     * Checks if a door is open, does not allow movement through it if it is closed
     * Extends verb on $exit (see ProgExit)
  * try_me
     * Checks if a door is open, does not allow movement through it if it is closed
     * Overrides verb on $exit (see ProgExit)
  * invoke
     * If player's unlockdoors pref is set, queue door unlock action (see ProgActions)
     * If player's opendoors pref is set, queue door open action (see ProgActions)
     * Overrides verb on $exit (see ProgExit)
  * allows
     * Checks if a door is open, does not allow movement through it if it is closed
     * Extends verb on $exit (see ProgExit)
  * throws_to
     * Checks if a door is open, does not allow objexts to be thrown through it if it is closed
     * Extends verb on $exit (see ProgExit)
  * acceptable
     * Only allows children of $lock to be placed inside a $door
     * Extends verb on $exit (see ProgExit)

  * go_fail_msg/go_fail_open_msg
     * Returns $door.(verb)

  * hear_event_say
     * Passes args to all installed $locks' :hear_event_say (if it exists) (see ProgActions)
     * Included to emulated voice-activated electronic locks
  * app*raise
     * Top level, user invoked verb for tellling players information about the door
     * Calls tell_appraise
  * tell_appraise
     * Called by appraise
     * Determines information on locks and armor values of door
  * uninstall
     * Invokes the specified $lock's _uninstall (see ProgLocks)
     * Determines which lock via matching logic
  * take_damage
     * Applies damage from weapons
     * Calls :die() if door is out of health
  * squeal_msg
     * Return this object's reaction to receiving this damage, based on the damage actually done after armor
     * Defaults to .squeals (see ProgSqueals)
  * die
     * Called when $door's health is reduced below zero by weapons
     * Sets $door.operational to 0
     * Sets $door.otherside.operational to 0
     * Opens door
     * Sets all $locks' .operational to 0
     * Sets all $locks' .otherside.operational to 0
     * Unlocks all locks
  * _repair
     * Sets $door.operational to 1
     * Sets $door.otherside.operational to 1
     * Closes door
     * Sets all $locks' .operational to 1
     * Sets all $locks' .otherside.operational to 1
     * Locks all locks
     * Designed to be called by 'repairman' NPCs
  * on_reset
     * Identical functionality to $door:_repair
     * Designed to be called by $area:on_reset (See ProgArea)
  * _repair_check
     * Makes skill check against player/NPC's repair skill
  * is_broken
     * returns inverse of $door.operational
  * lock_installable
     * Toggles $door.lock_installable (see above)

  * autoopen_on_unlock
     * Toggles $door.autoopen_on_unlock (see above)
  * autoclose_on_lock
     * Toggles $door.autoclose_on_lock (see above)
  * _autoclose
     * Automatically closes the door 30 seconds after it is opened.
     * Invoked only if $door.autoclose is set to 1.
     * This is intended for NPCs only - there is no method that allows players to use this functionality at present.

<B>NPC API:</B><br /> (These verbs are intended to be used by NPCs for programming door related operations)

  * _is_locked
     * Polls all locks installed in the door
        * If any of the locks are engaged, return 1
        * If all locks are disengaged, return 0
  * _can_be_unlocked_by
     * Polls all locks installed in the door
        * If ALL of the locks can be unlocked by args[1], return 1
        * If ANY of the locks cannot be unlocked by args[1], return 0
  * _open
     * See above.
  * _close
     * See above.
  * _lock/_unlock
     * See above.

<B>Security System API</B><br /> (These verbs are intended to be used by security systems for programming door related operations)

  * _security_autoopen
     * Opens door, prints appropriate messages on both sides
     * Messages printed are .otherside_* messages, which do not indicate a user
  * _security_autounlock
     * Unlocks all locks in door, prints appropriate messages on both sides
     * Invokes $lock:_security_autounlock on all locks (see ProgLocks)
     * Messages printed are .otherside_* messages, which do not indicate a user
  * _security_autoclose
     * Closes door, prints appropriate messages on both sides
     * Messages printed are .otherside_* messages, which do not indicate a user
  * _security_autolock
     * Locks all locks in door, prints appropriate messages on both sides
     * Invokes $lock:_security_autounlock on all locks (see ProgLocks)
     * Messages printed are .otherside_* messages, which do not indicate a user

<B>Gang API:</B><br /> (These verbs are intended to be used by gangs for programming door related operations)<br /> <B>n.b.: These verbs are ONLY present on children of biometric locks.</B>

  * add_lock_user 
     * Adds an object to the lock's .keyed_to property.
  * remove_lock_user 
     * Removes an object to the lock's .keyed_to property.
  * set_lock_users 
     * Resets the lock's .keyed_to property to the specified list of objects.