[WiP] [General Information] Signals

[ScRaT_GER]

Preface

Signals allow you to react on events in the universe in a lightweight way. Signals are always associated with the object, which emitted the signal and they pass specific arguments to the scripts they are connected to.

When you connect a script to a certain signal, you also assign a priority, the script should be called with (see <RefObj> connect ship command/signal <Object Command/Signal> to script <Script Name> with prio <Var/Number>).
Thus the called script obbeys the normal iterrupt rules:

• if the priority is lower or equal to the one of the currently running script on the corresponding task, it doesn't interrupt this script
• if the priority is higher, execution of the currently running script on the corresponding task is interrupted, until the interrupting script returns

Structure

In the following section the signals will be explained in more detail. For every signal their attributes will be listed, along with the conditions which must be met for the signal to be emitted. Additionally possible uses are listed.
A signals attributes take the following form:

SIGNAL_NAME

Task: P / S
Passed arguments: <Args>

SIGNAL_NAME = The name of the signal, always uppercase letters, beginning with SIGNAL_
P = Task of script attached to the signal, when signal is a primary signal
S = Task of script attached to the signal, when signal is a secondary signal
<Args> = List of arguments, which are passed to the attached script.


Signal reference

SIGNAL_ATTACKED

Task: 0 / 18
Passed arguments:

• 1: Var/Ship/Station - attacker - object which attacked [THIS]
• 2: Var/Number - action - action [THIS] is currently performing (see also Actions)

Conditions: This signal is emitted by an object when it's being attacked. It will only be emitted by foes, so player owned ships will never emit this signal when attacked by another player owned ship (i.e. the playership).
The signal is not emitted constantly, when a ship is attacked, but it has a cool down phase of a few seconds (maybe 1-2 seconds). This means that you cannot use the signal to react to single shots, which wouldn't be desirable anyways, because of the performance impact of runnig one or more scripts every time a ship is hit.

Possible uses: Any fight script


SIGNAL_BUYWARE

Task: 0 / 18
Passed arguments:

• 1: Var/Ship/Station - trading partner (can be ship or station, depending on the associated object)
• 2: Var/Ware - bought ware
• 3: Var/Number - bought amount
• 4: Var/Number - price of single ware (not total price)
• 5: Value - Special*

* At the time of writing, the fifth script argument is only set, when buying marines or other kinds of passengers. In this case the passenger object (DATATYP_PASSENGER) is stored in the fifht argument.

Conditions: This signal is emitted when an object buys a ware. It only buys a ware, if credits are transacted, so the signal will not be emitted if the player loads wares onto the playership at his own station. See SIGNAL_LOADWARE for this case.

Possible uses: Logging scripts, custom trade scripts


SIGNAL_SELWARE

Equivalent to SIGNAL_BUYWARE.


SIGNAL_LOADWARE

Task: 0 / 18
Passed arguments:

• 1: Var/Ship/Station - trading partner (can be ship or station, depending on the associated object)
• 2: Var/Ware - bought ware
• 3: Var/Number - bought amount

Note that, opposed to SIGNAL_BUYWARE, this command doesn't pass a price to the connected scripts, because no transaction takes place. Additionally, the fifth "special" argument of SIGNAL_BUYWARE is seemingly not used - even when loading passengers.

Conditions: This signal is emitted when an objects loads a ware. It only loads a ware, if no credits are transacted, so the signal will no be emitted if the player buys a ware at a station. See SIGNAL_BUYWARE for this case.

Possible uses: Loggin scripts, custom trade scripts


SIGNAL_UNLOADWARE

Equivalent to SIGNAL_LOADWARE.


SIGNAL_DOCKED

Task: 0 / 18
Passed arguments:

• Var/Ship/Station - object [THIS] docked at

Note that this signal is rather buggy, especially on the playership:

• a) It fires twice
  b) Not all connected scripts are run, because when docking with the playership all scripts running on task 0 are killed
  c) You can create a very strange hack using a secondary signal, which enables you to run a script on task 0, while you're docked and while task 0 should normally not run any script. This script can even keep on running on task 0 while you still can control the ship completely, which shouldn't be possible, when task 0 is running. Since this is a bug, you'll have to research yourself if you want to know more about it.

As you can see, there are quite a few problems, so use this signal with care.



TO DO:
List all signals and gather all information.
Add examples for every signal.
Link to related topics.

[h2o.Ava]

I've observed the following behavior, some of it is related to 0 hull invulnerable ships.

SIGNAL_KILLED:
Runs twice: First run allows for scripts to be executed based on its death, the completion of the second run removes the object.
A local var needs to be created to prevent anything from occurring during the second run.

Waits, etc placed in the script called by SIGNAL.KILLED will prolong the death of the ship until all non-parallel (START) scripts are complete (Useful for longer capital ship deaths, etc).
If you want the ship to disappear immediately, then place it in a different sector while your scripts run.

Don't destroy or jump the 'dead' ship out of existence, it will go away upon completion of the second SIGNAL.KILLED (possible cause of 0 hull invulnerable ships).

[ScRaT_GER]

Thanks for the input.

Unfortunately I'm quite swamped with RL stuff (university) atm, which is why I won't include that right now. But I'll have time to finish this overview during the christmas holidays and hopefully document the other signal related commands aswell.

Greetings,
ScRaT

[h2o.Ava]

more info on SIGNAL_KILLED

it looks like it passes 6 arguments
1: Value - killer - killer
2: Object Command - cmd - cmd
3: Value - cmdtarget - cmdtarget
4: Value - cmdtarget2 - cmdtarget2
5: Value - cmdpar1 - cmdpar1
6: Value - cmdpar2 - cmdpar2