[SCRIPT] Question about parameters

[Zokrar]

I'm relatively uneducated when it comes to programming in general, so if possible, please try to explain simply.

My question is, why do callback functions require parameters? Such as...

Code: (Select All)

void RandomFunc(string &in asParent, string &in asChild, int alState)

For example, if I have the following script:

Code: (Select All)

AddEntityCollideCallback("Player", "AreaDoor", "EventDoor", true, 1);

void EventDoor(string &in asParent, string &in asChild, int alState)
{
    
    AddDebugMessage("Player collided with AreaDoor. Starting door scare.", false);
    SetSwingDoorClosed("Door", false, false);
    SetSwingDoorDisableAutoClose("Door", true);

    PlaySoundAtEntity("creak", "joint_door_move_special.snt", "Door", 1, false);

    AddTimer("", 2, "TimerStopSound");
    AddTimer("Door", 0, "TimerMoveDoor");
    
}

Why were the parameters required in the EventDoor function? I didn't reference them in the brackets.

[Romulator]

Assuming the parameters are the Parent, Child and State, they are primarily used in the declaration to determine what collides with what.

Basically, they are there so that within this routine if you do need to reference them within the braces, you can call them from the void, and the void pulls them from the declaration. This can save you from typing in the object names from the Level Editor on multiple occasions if things only happen between these two objects. A good example is using alState in an if statement:

PHP Code: (Select All)

void func_shelf(string &in asEntity, int alState)
{
     if (alState == 1)           //Pull lever down all the way.
     {
     SetMoveObjectState("shelf",1.0f);           //Move shelf to reveal path
     PlaySoundAtEntity("", "quest_completed.snt", "shelf_move_1", 0, false);       //Play some catchy tunes
          return;
     }
} 


Another one could be something like using a key to open a door:

PHP Code: (Select All)

void OnStart()
{
    AddUseItemCallback("", "rusty_key", "locked_door_1", "OpenDoor", true);
}
 
void OpenDoor(string &in asItem, string &in asEntity)
{
    SetSwingDoorLocked(asEntity, false, true);          //locked_door_1 unlocks
    PlaySoundAtEntity("", "unlock_door", asEntity, 0, false);     //Play unlock sound at door
    RemoveItem(asItem);                     //Key comes out of inventory
} 


Bottom line is that if something happens to the declared Parent, Child, State, Effects etc, they can be referenced within the braces with ease

[PutraenusAlivius]

In my opinion, these callback syntaxes gives the parameter's types.

Like in a timer:

PHP Code: (Select All)

string &in asTimer 


It gives the fact that the string is a timer string.

[Zokrar]

Okay, I see. Thanks for the replies. One more thing, what does "&in" mean? Is that a C memory thing?

Also, seeing as the parameters are just... parameters, why do I have to call them asParent, asChild and such? Why could I not name them anything and have it work?

[WALP]

Well thats because you can name it anything and have it work. I often prefer using AsArea instead and I have had no issues with that.

[Zokrar]

Well, I'll be damned lol. That'll make things cleaner. One last question... I still don't understand why I must have parameters in the callback function, even if they're not used within the brackets. (If I don't have parameters, it doesn't crash the game, but the method simply does not do anything.)

[PutraenusAlivius]

Well, I'll be damned lol. That'll make things cleaner. One last question... I still don't understand why I must have parameters in the callback function, even if they're not used within the brackets. (If I don't have parameters, it doesn't crash the game, but the method simply does not do anything.)

It matches the signature of the parameter and it's respective callback syntax.

I think so.

[Zokrar]

It matches the signature of the parameter and it's respective callback syntax.

I think so.

I don't understand what you mean. Could you try explaining it another way, please?

[Romulator]

In adding the callback, you assign what happens to what, such as in a Collide Callback, when the parent and the child collide, a certain function happens depending on the state they are in.

The function then needs the parent and child to assure that it is a proper collision function between these two. This might be a way to determine what happens if you had two functions with the same name, however Amnesia restricts that by returning an error either way. Like for an example, you cant have two functions called "CollidewithScript"

[Adrianis]

... I still don't understand why I must have parameters in the callback function, even if they're not used within the brackets ...

The short answer is:
Because that's how Frictional Games have set it up. You don't have to use the parameters in the function, but they have to be there


The long answer is:
When the callback that you set up is activated, the engine looks for a function with the name you set the callback with (in your case, "EventDoor"), the word "void" at the beginning (which is whats called the 'return type' of the function), and the whole list of parameters.

The reason you can change the name of the parameter ('asEntity', 'alState', etc), but not the type ('string &in', 'int' etc) is because the engine is actually just looking for the list of parameter types, it doesn't care about the name.

The details it is looking for are...

PHP Code: (Select All)

void YourFunctionName(string &in name, string &in name, int name) 


Those details that the callback is looking for, have already been set up in the engine, so we can't change them. That means that although you don't need use the parameters, they need to be there or else the engine won't be able to find what code to run (the function you write)

One more thing, what does "&in" mean? Is that a C memory thing?

It's related to it, yeh
The '&' means it takes the address to the bit of memory that the variable is in (meaning the actual value of the variable doesn't have to get copied into new memory, just an address), and 'in' means it can only take that data 'in', it can't pass it 'out' (which means that the value cannot be changed).
So, 'string &in' basically means its a string that function receives that cannot be changed, but its the original string, not a copy

Obviously there's loads more detail to all this, if you interested there's a manual on 'AngelScript', this language, heres a good place to start, but it assumes quite a bit of knowledge.