CBinaryFrobMover

From The DarkMod Wiki
Jump to: navigation, search

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: (angles) Describes the angles (pitch, yaw, roll) the mover will rotate from its closed to its open position (default is: "90 0 0").
  • translate: (vector) Describes the relative movement of the origin from the closed position to the open position (default is "0 0 0" = no movement).
  • translate_speed: (float) 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").
  • pickable (1/0) If set to 1, is pickable by the player's lockpicks.
  • lock_picktype (string) This is a sequence of characters defining the lockpick types which need to be used on this door. For instance, 'bs' means that the player must use the "bent" lockpick ('b') and the "snake" lockpick ('s') - in this order - to pick this lock. It's also possible to define a star "*", which matches all lockpick types.
  • lock_pins (string) Defines the number of samples per pin to be created for this lock, example: "56" will create two patterns, one with 5 samples, the other with 6 samples. The minimum is 5.
  • 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.
  • snd_lockpick_pin_NN (soundshader) Defines the sample sound for the pin with NN being in the range 00..14. The number must have a leading zero in it (e.g. '02').
  • snd_lockpick_pin_sweetspot (soundshader) Defines the sweet spot sound to be inserted into a pattern.
  • snd_lockpick_lock_picked (soundshader) Is played when the entire lock is successfully picked.
  • snd_lockpick_pin_success (soundshader) Is played when a single pin is successfully picked.
  • snd_lockpick_pin_fail (soundshader) Is played when the player fails to pick a pin.
  • snd_lockpick_pick_wrong (soundshader) Is played when the user either attempts to use the wrong lockpick type or the door is not locked or already picked.
  • 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: (float) 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: (float) 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.
scriptEvent float IsPickable();
Returns true (nonzero) if this mover is pickable.

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.

As many spawnargs refer to other entities, most of the setup work can be performed after all entities have been spawned. This is why the FrobMover base class provides a virtual PostSpawn() method which can be overridden by the subclasses to do work after all map entities have been spawned. Note: don't forget to call the base class!

// Gets called 16 ms after all entities have been spawned
virtual void PostSpawn();

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.