ACS_NamedExecuteWithResult

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.

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;
    }
}