Trap Specification

Discussion in 'General Modification' started by anatoliy, Apr 30, 2020.

Remove all ads!
  1. anatoliy

    anatoliy Established Member

    Feb 18, 2017
    Likes Received:
    Trap Specification

    A Trap in ToEE is special object, which is instantiated from pre-listed specifications by the Engine when it is setup by a game designer.

    Traps Specifications from (data/rules/

    | name                 | trigger | flags          | particle       | search dc | disable dc | replace with | dmg 1-5       | cr | id |
    | TRAP_POISON_GAS      | san_use |                | Trap-poisonGas | 31        | 26         | TRAP_NONE    | poison 0d0+31 | 1  | 1  |
    | TRAP_FIRE_TRAP_SPELL | san_use | TRAP_F_MAGICAL | Trap-Fire      | 31        | 31         | TRAP_NONE    | fire 1d4+10   | 1  | 6  |
    | TRAP_SCYTHE          | san_use |                | Trap-Scythe    | 21        | 18         | TRAP_NONE    | Slashing 2d4  | 1  | 8  |
    The Trap definition has following fields:
    • id, - identifier of the specification.
    • name, - internal name of the specification.
    • flags, - the following: TF_IN_STONE, TF_PC, TF_SPOTTED, TF_MAGICAL.
    • particle, - particle effect name.
    • search dc.
    • disable dc.
    • replace with, - If the obj is not a "real" trap, the trap script will be replaced by this trap after triggering (by name)
    • cr, - critter rating, for the XP.
    • dmg1-5, - five different damage specifications.

    The damage specifications for traps are obsolete and must be replaced by Python event hook of type "san_trap".

    A Trap instance cannot be created manually by a game designer, but have to be setup on a portal (door) or chest.

    A Trap Setup is specified in Holder's Scripts \ san_trap field using following syntax: "script_id trap_spec_id 0 0 0".

    For example see proto 1001 "Treasure Chest", it has san_trap specified as: "32007 8 0 0 0". Here you can see that the Treasure Chest object has Trap setup. The Trap Specification ID is 8, which is TRAP_SCYTHE in the specifications file. The Trap would be triggered when the Chest will be used, and the execution of the Trap would be defined in Python script 32007, which corresponds to file "".

    The Trap Setup Syntax uses extended format of san script, which aside of script_id also includes Counters (0-4). These are treated as additional arguments of a script. In case of a Trap it is Counter 0.

    Therefore, if one would rather define Trap Setup in the ToEE World Editor, he should use Counter 0 in Script Dialog as Trap Specification ID.

    Example of a Python Trap execute script:
    import toee
    def san_trap(trap, triggerer):
        assert isinstance(triggerer, toee.PyObjHandle)
        assert isinstance(trap, toee.PyTrap), trap.obj), 1)
        dice = toee.dice_new("1d4+1")
        dice_crit = toee.dice_new("2d4+2")
        radius_ft = 7
        for obj in, radius_ft, toee.OLC_CRITTERS):
            f = obj.object_flags_get()
            if ((f & toee.OF_OFF) or (f & toee.OF_DESTROYED) or (f & toee.OF_DONTDRAW)): continue
            caf = trap.attack(obj, 10, 20, 1)
            if (not (caf & toee.D20CAF_HIT)):
            dce = dice
            if (caf & toee.D20CAF_CRITICAL): dce = dice_crit
            obj.damage(trap.obj, toee.D20DT_PIERCING, dce, toee.D20DAP_NORMAL, toee.D20A_UNSPECIFIED_ATTACK)
        return toee.SKIP_DEFAULT
  2. Shiningted

    Shiningted I want my goat back Global Moderator

    Oct 23, 2004
    Likes Received:
    Great work anatoliy :D My last (unfinished) tutorial was on traps, this is much more succinct.

    Traps can be added to items as well - remember the trapped theives tools in the moathouse. There is a script from Agetian somewhere about how to do an area effect trap, and I have done some preliminary work on models for BG-style floor traps.

    EDIT: I can't access the .dats atm, but the Co8 mod lists the following traps:

    Last edited: Apr 30, 2020
    Allyx and anatoliy like this.
  3. anatoliy

    anatoliy Established Member

    Feb 18, 2017
    Likes Received:
    Thank you Shiningted! :)

    Indeed all Trap specifications from vanilla's are nicely listed in the scr folder.

    Scripting adds great flexibility over execution of Traps when they are triggered. One can check how to implement saving throws checks in on of the scripts listed by Shiningted.

    So if designer wants to set up a new Trap from DMG, say Spear Trap - he could choose to use TRAP_SPIKES (id: 9) from the existing specifications, and copy-paste execution with some small adjustments into new Python script file.

    But TRAP_SPIKES has search dc of 25 and disable of 22, which differs greatly from 20/20 specified in DMG.

    In such case one should add new row into
    Allyx and Shiningted like this.
Our Host!