ACS_ExecuteWithResult

From ZDoom Wiki
Jump to: navigation, search

84:ACS_ExecuteWithResult (script, s_arg1, s_arg2, s_arg3, s_arg4)

Usage

This is like ACS_ExecuteAlways, except the script is always run on the current map, and the return value is whatever the script sets with SetResultValue.

Parameters

  • script: Script to execute
  • s_arg1: First argument passed to the script
  • s_arg2: Second argument passed to the script
  • s_arg3: Third argument passed to the script
  • s_arg4: Fourth argument passed to the script

Examples

This special has a slightly unusual behaviour as most scripts are not designed to functionally return a value. It is possible, however. The syntax fits together like this:

script 1 (void)
{
    Print(d:ACS_ExecuteWithResult(2, 0, 0, 0)); //prints 667
}

script 2 (void)
{
    SetResultValue(667);
}

The point of creating a script like this is slightly overlooked by the use of functions. Functions cannot use Delay or other waiting commands. ACS_ExecuteWithResult can use them, but the result has to be decided before they are used. This means that ACS_ExecuteWithResult is sort of like a hybrid between a normal script and a function.

The purpose of this special would be to have other time-dependent events happen after the result is determined.

Another notable use of ACS_ExecuteWithResult is with switch animations. If the result value of the executed script is FALSE, the switch animation and sound will not play when the switch is hit. If the result is TRUE, the switch will animate. One example might be a switch which only responds to a specific weapon. Normally, any line marked as projectile activated will play a switch animation when hit by any weapon. Setting up a script like the following allows for more pleasing behavior. The switch only animates when it is hit with the pistol:

script 1 (void)
{
    if( CheckWeapon("Pistol") ) {
        Print(s:"You shot me with the pistol.");
        SetResultValue( TRUE ); // Cause the switch to animate
    } else {
        SetResultValue( FALSE ); // The switch will not animate if you use another weapon
    }
}


ACS_ExecuteWithResult can also be used in DECORATE expressions:

actor ReloadingPistol : Weapon
{
  states
  {
  Ready:
    PISG A 0 A_JumpIfInventory ("PistolClip", 0, 2)
    PISG A 0 A_JumpIf(1 == (ACS_ExecuteWithResult(999,0,0,0)), "Reload")
    PISG A 1 A_WeaponReady
    loop
  }
}

Also, unlike the other ACS specials, ACS_ExecuteWithResult can pass a fourth script parameter, making it useful as a line special.

Script functions
ACS_Execute ACS_NamedExecute
ACS_ExecuteWait ACS_NamedExecuteWait
ACS_ExecuteAlways ACS_NamedExecuteAlways
ACS_ExecuteWithResult ACS_NamedExecuteWithResult
ACS_LockedExecute ACS_NamedLockedExecute
ACS_LockedExecuteDoor ACS_NamedLockedExecuteDoor
ACS_Suspend ACS_NamedSuspend
ACS_Terminate ACS_NamedTerminate
ScriptWait NamedScriptWait
FS_Execute UsePuzzleItem