[TEMPLATE] for Posting Commands.

This forum serves as MSCI Reference at EGOSOFT. It's Read-Only for non MSCI Group members.

Moderators: Scripting / Modding Moderators, MSCI Moderators

Post Reply
mark_a_condren
Posts: 1385
Joined: Wed, 3. Aug 05, 05:05
x3tc

[TEMPLATE] for Posting Commands.

Post by mark_a_condren » Tue, 7. Sep 10, 15:56

@ START|[skip|else] if [not]|while [not]| <RetVar/IF/START> = <RefObj> call script <Script Name>: [<Parameter>=<Value>] [...]


START|[skip|else] if [not]|while [not]| = The possible 'Conditional' statements that can be used with this command.
<RetVar> = If the called script is to 'return' information.
<RefObj> = The 'Object' that the called script is to be run on.
<Script Name> = The script that is to be 'called'.
<Parameter> = The arguments that are to be passed to the 'called' script, if any.


Use this command to call another script from a currently running script. Dependant on the first 'Parameter' used ie START or <RetVar> etc, the called script will be run concurrently with the calling script or the calling script will wait for the called script to finish and return before continuing.

Without START, the script is called to run on the same object and task ID as the calling script.
The calling script is still on the stack but the called script is now on top of the stack and will run until it quits and returns control back to the calling script with a return.

<RefObj> is ignored unless you use START.

Using START and a <RefObj> of null, will run the script as an independent global script.
Global scripts are more difficult to control because they cannot be detected by other scripts.

Using START and an existing <RefObj> will kill all task 0 scripts on <RefObj> and start this script on task 0 instead.
Not all objects are valid. Asteroids and missiles are examples of invalid objects.

A script cannot overwrite itself so a task 0 script can not START on a <RefObj> = [THIS].

START spawns a new process instead of “calling” on top of the current one so control is returned to the calling script immediately.

An '@' character in a scripting statement marks an “interrupt point”.

A return variable can be assigned to the value returned by the called script.
In this case, whatever value is passed to the return statement in the called script is assigned to the specified variable in the calling script. The result of the call can also be used as a condition in an if, skip, or while.
If this is done, then the result can only be tested for whether or not it is null. If it isn't null, then the conditional test passes. If it is null, then it fails.

A 'called' script may have up to 10 arguments, dependant on how many were used when the script was written. All arguments must have their parameter set, this may however be as simple as null if the called script was written to allow for this.


Examples:

@ START = $ship call script The.script.i.want.to.run : argument 1: $do.this, argument 2: $then.do.this ....

Starts the 'called' script The.script.i.want.to.run on the 'object' $ship and pass it the arguments $do.this and $then.do.this. This will result in the 'called' script running concurrently with the 'calling' script. The 'calling' script will continue on while the 'called' script does its thing.

-----------------------------------

@ $return = $ship call script The.script.i.want.to.run : argument 1: $do.this, argument 2: $then.do.this ....

The 'called' script The.script.i.want.to.run will be run and passed the arguments $do.this and $then.do.this. This will result in the 'called' script running sequentially with the 'calling' script. The 'calling' script will wait while the 'called' script does its thing and will only continue on after the 'called' script has finished and returned the variable $return (or the 'called' script is stopped).

-----------------------------------

@ = $ship call script The.script.i.want.to.run : argument 1: $do.this, argument 2: $then.do.this ....

OR

$anull = null
@ = $anull call script The.script.i.want.to.run : argument 1: $do.this, argument 2: $then.do.this ....

As above but, the 'calling' script will wait for the 'called' script to finish, but no return is required by the 'calling' script.

To obtain the '=' without having 'null' or a '$return.variable' there you select 'No return variable' from the list of possible conditional statements at the bottom of the SE menu.

$anull = null is used to allow the insertion of null in place of a <RefObj> to set the script to run as a 'Global Script'.
null is inserted instead of a <RefObj> in this instance.


Related Commands:
  • Use this area if there are any 'Related Commands' for the command that you wish to mention.

Unknown Outcomes:
  • Use this area if there are any 'unknown outcomes' for the command that you wish to mention.
Command Location:
  • »» General Commands
    • »» Script Calls
      @ <RetVar/IF/START><RefObj> call script <Script Name> : <Parameter>

Post Reply

Return to “MSCI Reference”