From OniGalore
Jump to navigation Jump to search
TRGV : Trigger Volumes (TVs)
XML modding tips
  • See HERE to start learning about XML modding.
  • See HERE if you are searching for information on how to handle object coordinates.
  • See HERE for some typical modding errors and their causes.

AKVA << Other file types >> CBPI

TMBD << Other BINA >> ONIE

TRIG << Other OBJC >> SNDG

switch to OBD page

general information

  • BINACJBOTrigger Volume.oni is level specific. (It can be found in AE/AEInstaller/vanilla/levelX_Final.dat)
  • The XML code on this page is based on onisplit v0.9.61.0

BSL support

show trigger activity

debug_triggers = 1 shows tv event and what character enters, stays inside or leaves

Resetting the trigger volume

trigvolume_reset (string tv_name) resets the TV to its preset state. The primary use of this is to re-enable "entry", "inside" or "exit" calls once the TV has been triggered (only necessary if the respective trigger-only-once flags are set of course). Note that some or all the TV functions are disabled at level load, you'll have to enable them manually after resetting the TV.

Removing corpses

trigvolume_corpse (integer tv_id) removes all corpses inside the specified trigger volume.

file structure

Trigger volume.jpg

The red and blue lines were added to the screenshot in a graphics program, not by debug_triggers.

If you have an updated Oni Mac engine, the TVs can be made visible.

Used BSL commands:

  • debug_triggers = 1
  • chr_nocollision 0 1
  • chr_debug_characters = 1
  • chr_location 0 x y z
<?xml version="1.0" encoding="utf-8"?>

[...] means at least one trigger volume. Paste all tv data into there (this includes <TRGV Id="..."> and </TRGV> tag).


       <TRGV Id="7383">
               <Position>-651.5666 -298 -633.4166</Position>
               <Rotation>0 0 0</Rotation>
               <Size>46 31 46</Size>
start      + size = end
- 651.5666 + 46   = -605.5666 = x_blue_line_end
- 298      + 31   = -267      = y_blue_line_end
- 633.4166 + 46   = -587.4166 = z_blue_line_end


tag type description
<?xml version="1.0" encoding="utf-8"?> float, flag Don't change this.
<Oni> - XML root node
<TRGV Id="..."> integer You can also use <TRGV> without the id parameter.
<Header> -
<Flags> flag Used in the past.
<Position> float x3 TV is spawned at this xyz-position
<Rotation> float x3 TV has this xyz-rotation (in degrees)
<OSD> -
<Name> string can have up to 63 characters
<Scripts> - BSL functions; each can have up to 32 characters
<Entry> string called up when character enters the TV
<Inside> string called while character is inside the TV

This one is triggered at every frame (60 times per second) unless the trigger-only-once flag is set. Continuous triggering is typically needed for fire or gas damage.

<Exit> string called up when character leaves the TV
<Teams> flags
1 - Konoko
2 - TCTF
4 - Syndicate
8 - Neutral
16 - SecurityGuard
32 - RogueKonoko
64 - Switzerland
128 - SyndicateAccessory

Every combination is possible. E.g.:

255 - all teams (1 + 2 + 4 + 8 + 16 + 32 + 64 + 128 = 255)
<Size> float x3 volume
<TriggerVolumeId> integer used by BSL command "trigvolume_corpse ID"
<ParentId> integer not used ?
<Notes> string space for 128 characters
<Flags> flags
OneTimeEnter - entry function called only once (otherwise called every time character enters the TV)
OneTimeInside - inside function called only once (otherwise called at every frame while character is in the TV)
OneTimeExit - exit function called only once (otherwise called every time character leaves the TV)
EnterDisabled - entry function disabled (can be enabled with "trigvolume_enable tv_name entry 1")
InsideDisabled - inside function disabled (can be enabled with "trigvolume_enable tv_name inside 1")
ExitDisabled - exit function disabled (can be enabled with "trigvolume_enable tv_name exit 1")
Disabled - all 3 functions disabled (master switch, can be enabled with "trigvolume_enable tv_name all 1")
PlayerOnly - only player characters can fire off the TV

BSL bugs and workarounds

String comparison bug

Trigger volumes can call bsl functions. This function can receive a string variable which contains the character name that triggered the trigger volume.

Unfortunately seems there are a bug when comparing this string parameter with another string variable in the BSL. Even if the trigger volume string and the other string are equal when you compare them in BSL it always returns false.

To reproduce the bug you can open "warehouse_level_scripts.bsl" in "EnvWarehouse" folder and replace the t65 function by this one (make a backup of the file first):

   func void t65(string ai_name)
       var string testVar = "char_0";
       if(testVar eq "char_0"){
           dmsg("regular string comparison works!");
           dmsg("regular string comparison failed!");
       if(ai_name eq "char_0"){
           dmsg("trigger volume string comparison worked!");
           dmsg("trigger volume string comparison failed!");
       dprint t65
       if(d6 eq 0)
           message xdoorislocked
           dprint door_is_locked

Load savepoint 1 in chapter 1 and move the character until the door. This function will be triggered. What is the output that you expect? "trigger volume string comparison worked!" right? Wrong it will print "trigger volume string comparison failed!" even though both string variables have the same value.

Trigger volume string comparison bug.jpg

(EDIT: Interestingly, ai_name eq ai_name evaluates to true. Apparently, as detailed by Loser HERE, strings are compared by pointer and not by content. --geyser (talk) 18:47, 6 August 2020 (CEST) )

Possible workarounds

If you need to detect a few characters and if all of these are from different teams you can clone the trigger volume one time for each character and call different functions one for each team. This way you make sure you know which character triggered the trigger volume since each character has a unique team and a unique trigger volume function.

On Windows, you can take advantage of the Daodan DLL's custom function d_getindex(string ai_name) and compare by ID.

chr_poison bug

chr_poison is a bsl function which is used in the original game to damage the characters within a specific interval, it is used in fire (example level4) and in gas (level5). It uses trigger volumes to call a function (every frame) which contains chr_poison (using TV "Inside" call). It works as expected except if the trigger volume is trigger many times which in case will trigger the "FATAL SCRIPTING ERROR: exceeded maximum scripting parameter base size of 32768" message in developer console and stop working.

Possible workarounds

Instead of using Inside to call the damage function use Entry to call an intermediate function let's call it "trigger_damage", "trigger_damage" will call another function called "damage_character", this function will be now be responsible for damaging the character every frame. We also need to know when the player leave the TV so we can stop damaging him, for this in the trigger volume xml file we will also use Exit to trigger the function "trigger_stop_damage".

To know which character leaved the damaging trigger volume, we will first give the LSI item to him and then remove it when he leaves the trigger volume, so will damage him only when he has the LSI. You can use another techniques here if you don't want to use the LSI, for instance you can use the multiple TV one explained above to fix the string comparison bug.

The final bsl code will look like this:

   # this function now does the work of damage the character each frame
   # once the character looses lsi it stops damage him
   func void damage_character(string ai){
           chr_poison(ai, 5, 10);
           fork damage_character(ai);
   func void trigger_damage(string ai){
       fork damage_character(ai);
   func void trigger_stop_damage(string ai){
       chr_inv_reset(ai); # clear lsi

And the trigger volume XML will look like this:

   <TRGV Id="1">
           <Position>2005.23 1239.87 -3628.82</Position>
           <Rotation>0 0 0</Rotation>
               <Inside />
           <Size>-287.04 1 -179.85</Size>
           <Flags />

If the technique above is not enough and you are still experiencing the "FATAL SCRIPTING ERROR: exceeded maximum scripting parameter base size of 32768" error after a while, you may try using duplicated trigger volumes, where after a while (and before the error appears) you disable the first one and active the second one (which is a copy of the first).

The duplicated one can look like this:

   <TRGV Id="2">
           <Position>2005.23 1239.87 -3628.82</Position>
           <Rotation>0 0 0</Rotation>
               <Inside />
           <Size>-287.04 1 -179.85</Size>
           <Flags />

Code to switch between them:

   trigvolume_enable("BurnCharacter",0); # disable the first one
   trigvolume_enable("BurnCharacterPart2",1); # activate the second one

Note that you should have only one of the copies active at a time (so for instance when "BurnCharacter" TV is enabled, "BurnCharacterPart2" TV should be disabled.

Mod Tool addon

trigger volume manager

With OniTools.xsiaddon you can drag'n'drop BINACJBOTrigger Volume.oni into the viewport.

Add or remove TVs, edit position and rotation as if they were real objects. Change size by moving the polygons.

When ready, export the data as BINACJBOTrigger Volume.xml to a folder of your choice.