ACS_Execute

Name

ACS_Execute — begins execution of a script.

Synopsis

ACS_Execute (script, map, s_arg1, s_arg2, s_arg3);

ACS_Execute (
  script,    // script to execute
  map,       // map containing the script
  s_arg1,    // first argument passed to the script
  s_arg2,    // second argument passed to the script
  s_arg3     // third argument passed to the script
);

Parameters

script: The script to execute. The specified map's BEHAVIOR resource is searched for a matching script first. If the BEHAVIOR does not have a matching script, then any libraries imported by the BEHAVIOR will be searched for the script. If the script cannot be found, a warning will be printed to the console, and no other action will be taken.
map: The map to execute the script on. This corresponds to the map's levelnum set in the MAPINFO lump. If you set map to zero, then the script will be executed on the current map.
s_arg1: An optional parameter to pass to the script.
s_arg2: An optional parameter to pass to the script.
s_arg3: An optional parameter to pass to the script.

ACS

This special's function is the same whether you activate it on a line or use it in a script.

Remarks

If the script to be executed is on the current map, whether because map was set to 0 or because it was set to the same levelnum as the current map, the script will begin executing immediately. If the script is on another map, it will not begin executing until the next time the player visits that map.

In either case, ACS_Execute will only allow one copy of a script to execute at a time. If you start a script with ACS_Execute and then try to start the same script again before it finishes, the second call to ACS_Execute will do nothing. Note that if you use ACS_ExecuteAlways to start a script, you can start the script again using ACS_Execute, but any further attempts to start the script with ACS_Execute will fail until the first instance of the script started with ACS_Execute completes.

If the specified script was already started but is currently suspended, ACS_Execute will "wake it up" and resume execution immediately after the statement that caused it to go to sleep.

It is possible to have scripts with the same number in separate modules. If the map's BEHAVIOR defines a script that is also defined in a library that it imports, the copy in the BEHAVIOR will always be the one that gets executed. If the BEHAVIOR does not define the script, but it is defined in more than one imported library, there is no guarantee which copy of the script will be executed. If you make use of libraries containing scripts, you should adopt some sort of uniform numbering system to ensure that you never have duplicate scripts in modules that might be used together.

Scripts can have up to three parameters passed to them. When you use this special from inside a script, you do not need to specify any parameters the executed script does not use. When you use this special on a linedef, s_arg1, s_arg2, and s_arg3 must be specified. In this case, you can use zeroes for script parameters that aren't really used.

Examples

Executing a script on the current map

Execute script 1 on the current map without any script parameters:

ACS_Execute (1, 0);

Execute script 1 on the current map with one script parameter; the value 5 will be passed as the first parameter to the script:

ACS_Execute (1, 0, 5);

Execute script 1 on the current map with all three script parameters; the values 5, 6, and 7 will be passed as parameters to the script:

ACS_Execute (1, 0, 5, 6, 7);

Executing a script on another map

The following three examples execute a script on a map with levelnum 3. Unless you specify otherwise in your MAPINFO, this will correspond to MAP03.

Execute script 1 on another map without any script parameters:

ACS_Execute (1, 3);

Execute script 1 on another map with one script parameter; the value 5 will be passed as the first parameter to the script:

ACS_Execute (1, 3, 5);

Execute script 1 on another map with all three script parameters; the values 5, 6, and 7 will be passed as parameters to the script:

ACS_Execute (1, 3, 5, 6, 7);

First Available In

Hexen

80:ACS_Execute