Cache

Script classes have memory, and their state won't get lost after executing one of their functions one more time.

How it works, explanation

You call the AngelScript P3S function via like this:

AngelScript "Object:self MyClass MyFunction"

The script class looks something like this:

class MyClass : IPostal3Script
{
    CP3SObj@ self;

    MyClass(CP3SObj@ obj)
    {
        @self = obj;
    }

    void MyFunction()
    {
        // ...
    }
}

The game first checks if there's already a cached instance of the class named MyClass with the context owner's pointer.

If not, then it will first create the factory, in the example above that is called MyClass(CP3SObj@ obj), this will always gets called first, before eventually executing MyFunction().

In the factory you can set up initialization things such as making sure the self handle is assigned to the entity that called AngelScript.

Global (no owner)

Global version (basically no owner is attached) would look something like this in P3S:

AngelScript "GLOBAL MyClass Increment"

Then the script class would look something like this:

class MyClass : IPostal3Script
{
    int num;

    CP3SObj@ caller;

    MyClass()
    {
        num = 0;
    }

    void Increment()
    {
        num++;
        Printf("Incremented: %d\n", num);
    }
}

No matter from which entity it was called from, the variable num would never start again from 0 in the example above.
Only disadvantage is that you will never know which entity called this function.

---

Variables don't get lost after executing twice

Script classes will hold all the variables you set previously, if the context owner is the same.

If there is no context owner (i.e. engine functions, like SEngine::FireGameEvent(IGameEvent @evt)) then cache will only look up for the class name.

Note

You can still check for the context owner via GetContextOwner.

Warning

Server-side only.

For example:

class MyClass : IPostal3Script
{   
    CP3SObj@ self;

    MyClass(CP3SObj@ obj)
    {
        @self = obj;
    }

    bool bBoolean;

    void MyFunction()
    {
        if (bBoolean == false)
            Printf("Boolean is false!\n");
        else
            Printf("Boolean is true!\n");

        bBoolean = true;
    }
}

Executing MyFunction() first will print out the message Boolean is false! to the console, but if you execute it twice, it'll say Boolean is true! on the same entity it was executed from in the first place.

---

Manual Restoration

Warning

Normally you don't need to do restoring manually, there are pointers that will persist through transition and save files, look at Serialization list for more information.

You can tell AngelScript which entities you wish to be "restored" whenever the game was reloaded
via a save file, or when the Player went through a transition with the following P3S attributes
(they must exist, either set to 0 or 1):

Postal3Script Attribute	Postal3Script Event
as_restore	OnASRestore
as_transition	OnASTransition

as_restore will call OnASRestore P3S event when the game was reloaded via a save file.
as_transition will call OnASTransition P3S event when the game was a transition load type.

Using these two attributes you can then attempt restoration by reinitializing their classes, like this:

// These events are placed somewhere, preferably globally
OnASRestore "ExecutePattern .xpt_restore"
OnASTransition "ExecutePattern .xpt_restore"

// Executed from OnASRestore and OnASTransition P3S events
xpt_restore
{
    actions
    {
        // Have to always remove attribute as_init_<className> !!
        RemoveAttr "as_init_CATM"
        AngelScript "Init Object:self CATM"
    }
}

Then in code:

class CATM : IPostal3Script
{
    int MyNum;

    // AngelScript Init only prepares the factory
    CATM(CP3SObj@ obj)
    {
        @self = @obj;

        // MyNum is lost somehow, reinitialize
        MyNum = 123;
    }
}