ACS_NamedExecuteWithResult

From ZDoom Wiki
Jump to navigation Jump to search

int ACS_NamedExecuteWithResult (string script, int s_arg1, int s_arg2, int s_arg3, int s_arg4)

Usage

Variant of ACS_ExecuteWithResult for named scripts.

There is both an ACS and a DECORATE version of this function. Both behave identically. The DECORATE version can also be called by the shorter alias CallACS in DECORATE expressions. Another alias for this function is ACS_ScriptCall, which introduces the ability for the function to be called by arbitrary actor objects as well as self object (see the second example below). This alias is exclusive to DECORATE and ZScript.

ACS_(Named)ExecuteWithResult has one small difference aside returning a value. They execute immediately once called, while the other types will usually wait a tic before acting.

However, it is not available as an action special: to call named scripts from a a line or thing special, you have to use the non-named variant (ACS_ExecuteWithResult) in UDMF, with the arg0str custom argument set to the name of the script — this will override the first parameter.

Parameters

  • script: Name of the 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

Return value

Returns the return value of the executed script. See SetResultValue.

Examples

This example shows an item similar to Hexen's Mystic Ambit item: Checks which player class uses an item and having a different effect.

Decorate Item:

Actor ClassBoost : CustomInventory
{
  Inventory.MaxAmount 25
  Inventory.InterHubAmount 25
  +INVENTORY.INVBAR
  Inventory.Icon "ARTIHRAD"
  States
  {
  Spawn:
    HRAD ABCDEFGHIJKLMNOP 4 Bright
    Loop
  Use:
    TNT1 A 0 A_JumpIf(CallACS("CheckPlayerClass", 0, 0, 0) == 0, "NormalPlayer")
    TNT1 A 0 A_JumpIf(CallACS("CheckPlayerClass", 0, 0, 0) == 1, "AlternatePlayer")
    Fail
  NormalPlayer:
    TNT1 A 0 A_RadiusGive("Health", 256, RGF_PLAYERS | RGF_GIVESELF, random(50, 90))
    Stop
  AlternatePlayer:
    TNT1 A 0 A_RadiusGive("PowerImproveDamage", 256, RGF_PLAYERS | RGF_GIVESELF, 1)
    Stop
  }
}

ACS Script:

script "CheckPlayerClass" (void)
{
  if(CheckActorClass(0, "DoomPlayer"))
  {
    SetResultValue(0);
    terminate;
  }
  else if(CheckActorClass(0, "AlternateDoomPlayer"))
  {
    SetResultValue(1);
    terminate;
  }
}


This example item demonstrates the use of ACS_ScriptCall. Upon pickup, its spawns a baron of hell and makes two ACS script calls: one which is done by the baron of hell itself, and another which is done by the actor which picked up the item.

class BaronSummoner : CustomInventory
{
    States
    {
    Spawn:
        SOUL ABCD 6 Bright;
        Loop;

    Pickup:
        TNT1 A 0
        {
            bool res;
            Actor mobj;
            [res, mobj] = A_SpawnItemEx("BaronOfHell", 100);

            if (res && mobj)
            {
                // Caller is the baron of hell object.
                // Using ACS_NamedExecuteWithResult, instead, is unacceptable here.
                mobj.ACS_ScriptCall("SomeScript");

                // Caller is the self object (the actor which picked the item up).
                // Using ACS_NamedExecuteWithResult, instead, is okay here.
                ACS_ScriptCall("SomeOtherScript");
            }
        }
        Stop;
    }
}
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