TDM Movers

From The DarkMod Wiki
Revision as of 09:12, 22 June 2008 by Greebo (talk | contribs) (categorised)
Jump to navigationJump to search

For The Dark Mod, we extended the existing idMover class by a set of classes specifically designed for creating maps in the medieval steampunk setting. Apart from elevators, most movers in TDM are two-state movers, meaning that they can be either in "open" or "closed" state. The class hierarchy is depicted here (I use the internal C++ class names here):



There are two base classes: BinaryFrobMover and MultiStateMover, which both build on top of the vanilla Doom 3 idMover class and provides all the methods needed to make all kinds of two- or multistate movers.

Each following section is dedicated to a certain subclass, listing information about spawnargs, script events as well as the C++ methods. This article is going to be long and should probably be split into pieces once the rough shape is formed.

CBinaryFrobMover

The corresponding entityDef is atdm:mover_binarymover_base

This is the base class for all kind of TDM movers like doors, levers and buttons. The class is designed for movers with two final states, namely open and closed. "Open" and "closed" are abstract definitions and just refer to the "one" and the "other" state of the mover. All movers are considered to spawn "closed", until specifically specified otherwise.

The class provides a set of virtual C++ methods which can be specialised by their subclasses to implement the correct behaviour. It also supports a number if spawnargs which allow for easy customisation right in the editor.

Spawnargs

  • rotate: Describes the angles (pitch, yaw, roll) the mover will rotate from its closed to its open position (default is: "90 0 0").
  • translate: Describes the relative movement of the origin from the closed position to the open position (default is "0 0 0" = no movement).
  • translate_speed: Is the linear velocity in units per second (defaults to "0", which means that the idMover's "move_time" value is in effect).
  • open: (1/0) Specifies whether this frobmover spawns at the open position. Can be used to let doors be open right at map start (default is "0").
  • locked: (1/0) Specifies whether this frobmover is locked (default is "0").
  • open_on_unlock: (1/0) When set to 1, the mover will automatically open when unlocked.
  • interruptable: (1/0) When set to 1, the mover can be stopped by frobbing it while moving. Doors are interruptable by default, whereas levers are not.
  • stop_when_blocked: (1/0) Set stop_when_blocked to 0 to let this entity keep moving after the blocking entity is out of the way. Default is "1".
  • push_player: (1/0) Set this to 1 to let this entity push the player (default is 0). Note: belongs to idMover class.
  • start_rotate: (Angles) Defines the angles (pitch, yaw, roll) the mover should have at spawn time (to let the mover start out half-open, for instance). Defaults to "0 0 0".
  • "start_position": (Vector) Defines the position the mover should have at spawn time (to let the mover start out open, for instance). Defaults to "0 0 0".
  • first_frob_open: (1/0) This helps to disambiguate the behaviour when a mover starts at a half-open position. When this is set to "1" the first frob will make the mover open. Defaults to "0", which means that half-open doors will close on first frob by default.
  • snd_open (Soundshader) The sound to be played when the door starts to open after being fully closed.
  • snd_close (Soundshader) The sound to be played when the door reaches its fully closed position.
  • snd_locked (Soundshader) The sound to be played when the mover becomes locked.
  • snd_unlock (Soundshader) The sound to be played when the mover unlocks.
  • trigger_on_open: (1/0) If set to "1", this binary mover will trigger its targets when it starts out completely closed and is opened. Default is "0".
  • trigger_on_close: (1/0) If set to 1, this binary mover will trigger its targets when it completely closes after being open. Default is "0".
  • trigger_when_opened: (1/0) If set to 1, this binary mover will trigger its targets when it is completely opened. Default is "0".
  • auto_close_time: Set this to something >= 0 to let the mover automatically close (again) after this time when being fully opened (measured in seconds). Defaults to -1, which means 'do not autoclose'. The event is also activated when the mover starts at the open position at map start.
  • auto_open_time: Set this to something >= 0 to let the mover automatically open (again) after this time when being fully closed (measured in seconds). Defaults to -1, which means 'do not autoopen'. The event is also activated when the mover starts at the closed position at map start.
  • impulse_thresh_open: (float) Defines the minimum impulse which needs to be applied to this door before it starts to open. If 0, no open impulse is defined. Default is "0".
  • impulse_thresh_close: (float) Defines the minimum impulse which needs to be applied to this door before it starts to close. If 0, no close impulse is defined. Default is "0".
  • impulse_dir_open: (vector) Defines the direction the open impulse needs to be applied in. Default is '0 0 0'.
  • impulse_dir_close: (vector) Defines the direction the close impulse needs to be applied in. Default is '0 0 0'.
  • state_change_callback: (script function) Defines the (global) script function which gets called when the mover changes its state. Function signature is: void statChangeCallback(entity self, bool open, bool locked, bool interrupted);

Script Events

scriptEvent void Open();
Opens the frobmover, regardless of its previous state. The mover will not move when it's locked.
scriptEvent void Close();
Closes the frobmover, regardless of its previous state.
scriptEvent void ToggleOpen();
Toggles the mover state. Closes when fully open, opens when fully closed. If the mover is "interrupted" (e.g. when the player frobbed the mover in between), the move direction depends on the state of the internal "intent_open" flag.
scriptEvent float IsOpen();
Returns true (nonzero) if the mover is open, which is basically the same as "not closed". A mover is considered closed when it is at its close position.
scriptEvent void Lock();
Locks the mover. Calls to Open() will not succeed after this call.
scriptEvent void Unlock();
Unlocks the mover. Calls to Open() will succeed after this call. Depending on the value of the spawnarg "open_on_unlock" the mover might automatically open after this call.
scriptEvent void ToggleLock();
Toggles the lock state. Unlocked movers will be locked and vice versa. The notes above concerning Unlock() still apply if this call unlocks the mover.
scriptEvent float IsLocked();
Returns true (nonzero) if the mover is currently locked.

C++ Methods and Events

The class declaration can be found in DarkMod/BinaryFrobMover.h. Apart from the mandatory Spawn/Save/Restore triple, a set of virtual functions are defined, which can be overridden by the subclasses to specialise the mover.

Note: This is just an abstract. A detailed description of these events can be found in the BinaryFrobMover.h header itself.

The class provides a few virtual "interceptor" methods, which can be used to prevent the mover from changing its state. These are: 

virtual bool PreOpen();
virtual bool PreClose();
virtual bool PreInterrupt();
virtual bool PreLock(bool bMaster);
virtual bool PreUnlock(bool bMaster);

These functions are called when the mover is about to perform the respective action. If these are returning TRUE, the mover has green light and it will start to open/close/lock/unlock/get interrupted. Returning FALSE will prevent the calling method from continuing. An example of such a use case is the CBinaryFrobMover::PreOpen() routine, which returns FALSE when the mover is locked. It also playes the "I'm locked" sound before returning.

There are a couple of "state change events", which get invoked when the mover has reached a certain state: 

// Gets called when the mover actually starts to move, regardless what the state was beforehand. 
// The boolean tells which state the mover is heading towards.
virtual void OnMoveStart(bool open);

// Gets called when the mover is about to move towards its "open" and "closed" position, resp..
virtual void OnStartOpen(bool wasClosed, bool bMaster);
virtual void OnStartClose(bool wasOpen, bool bMaster);

// Gets called when the mover has just reached its fully open/closed position. Does not get called when the mover didn't move.
virtual void OnOpenPositionReached();
virtual void OnClosedPositionReached();

// Gets called when the mover has just been interrupted.
virtual void OnInterrupt();

// Is called when the mover has just been locked/unlocked.
virtual void OnLock(bool bMaster);
virtual void OnUnlock(bool bMaster);

General note on overriding these events: Althought most default implementations are empty, it's still advisable to call the base class from the overriding function. Default behaviour might be changed in the future, so always call the base class, unless you really need to prevent the default action from being executed.

CFrobDoor

Spawnargs

  • loss_open (float) Defines the sound volume loss in dB when this door is open (default: 1).
  • loss_closed (float) Defines the sound volume loss in dB when this door is fully closed (default: 15).
  • loss_double_open (float) Defines the sound volume loss in dB when one of the double doors is open and the other is closed (default: 1).
Retrieved from "https://wiki.thedarkmod.com/index.php?title=TDM_Movers&oldid=6554"