Difference between revisions of "Script.plist"

From Elite Wiki
m (→‎Queriable states)
m (Tagged as Legacy scripting)
 
(29 intermediate revisions by 8 users not shown)
Line 1: Line 1:
−
'''script.plist''' Used by [[missions]] and [[OXP]]'s to check [[conditions]] and change scripted parameters accordingly. In OXP's it provides Oolite with additional information to generate and populate customised systems. Every condition is followed by a scripted action, a '[[Do]]' or '[[Else]]' entry, a 'do' entry can be nested (have conditions, followed by Do)
+
'''script.[[plist]]''' Used by [[Oolite_Missions|missions]] and [[OXP]]'s to check [[conditions]] and perform scripted actions accordingly. The legacy scripting engine used by this is not recommended for use in new OXPs - use [[Oolite_JavaScript_Reference|Javascript]] for scripted behaviour instead.
   
−
== Conditions ==
  
  +
In OXP's it can provide Oolite with additional information to generate and populate customised systems.
−
Check whether the current status of one of a number of queriable states are '''equal''', '''lessthan''', '''morethan''' a given value or state, or '''oneof''' a list of space separated states.
  
   
−
example:
  
  +
== Structure ==
−
<key>conditions</key>
  
−
<dict>
 
−
<array>
  
−
<string>shipsFound_number equal 0</string>
  
−
</array>
  
−
</dict>
  
   
−
=== Queriable states ===
  
  +
''script.plist'''s structure is a dictionary, each entry is a particular script with a unique key.
   
−
mission_string;
  
  +
Each script is an array of actions and conditional statements that are executed or checked at regular intervals (every 10 seconds or so during flight or docking).
−
status_string;
  
−
gui_screen_string;
  
   
−
galaxy_number;
  
  +
For increased performance of a script one needs to add nested structures within the script structure. see: [[Structured Legacy Scripts]]
−
planet_number;
  
−
score_number;
  
−
credits_number;
  
−
scriptTimer_number;
  
−
legalStatus_number;
  
   
−
shipsFound_number;
  
  +
== Actions ==
   
−
d100_number;
  
  +
An action is a simple string referring to a [[methods|method]]
−
pseudoFixedD100_number;
  
   
−
clock_number; // returns the game time in seconds
  
  +
== Conditional statements ==
−
clock_secs_number; // returns the game time in seconds
  
−
clock_mins_number; // returns the game time in minutes
  
−
clock_hours_number; // returns the game time in hours
  
−
clock_days_number; // returns the game time in days
  
   
−
fuel_level_number; // returns the fuel level in LY
  
  +
Conditional statements consist of a dictionary with entries for the keys '''conditions''' and '''do''' (and optionally '''else'''.)
   
−
dockedAtMainStation_bool;
  
  +
=== conditions ===
−
foundEquipment_bool;
  
   
−
sunWillGoNova_bool; // returns whether the sun is going to go nova
  
  +
'''conditions''' consists of an array of tests to be performed. Each test checks whether the current status of one of a number of [[Methods#Querying_states|queriable states]] and [[mission_variable]]s are '''equal''', '''lessthan''', '''greaterthan''' a given value or state, or '''oneof''' a list of comma separated states.
−
sunGoneNova_bool; // returns whether the sun has gone nova
  
  +
Note: As of v1.69 also a '''notequal''' operator will be available for Legacy scripting.
   
−
missionChoice_string; // returns nil or the key for the chosen option
  
  +
Multiple conditions may be specified, a logical 'AND' is applied to determine whether the conditions are met or not.
   
−
dockedStationName_string; // returns 'NONE' if the player isn't docked, [station name] if it is, 'UNKNOWN' otherwise
  
  +
If all the conditions are met then the '''do''' entry is executed, if any are not met then the '''else''' entry is executed (if it exists).
   
−
systemGovernment_string;
  
  +
example:
−
systemGovernment_number;
  
  +
<key>conditions</key>
−
systemEconomy_number;
  
  +
<dict>
−
systemTechLevel_number;
  
  +
<array>
−
systemPopulation_number;
  
  +
<string>shipsFound_number equal 0</string>
−
systemProductivity_number;
  
  +
</array>
  +
</dict>
   
−
== Do ==
 +
=== do ===
−
The actions to perform when conditions are met.
+
  +
'''do''' consists of an array of actions (and further conditional statements if required), executed if the '''conditions''' are met.
   
 
Example:
  
Example:
Line 67: Line 48:
 
</dict>
  
</dict>
   
−
== Else ==
 +
=== else ===
−
Actions performed when conditions are not met. Same as "Do".
 +
  +
'''else''' consists of an array of actions (and further conditional statements if required), executed if the '''conditions''' are NOT met.
  +
  +
Example:
  +
<key>else</key>
  +
<dict>
  +
<array>
  +
<string>addShips: super-pirate 1</string>
  +
</array>
  +
</dict>
  +
   
−
----
  
−
Just a small start. probably better to list the condition parameters, methods in their own Omnibus. A_H
  
   
−
----
  
  +
==Examples==
−
This is a stubby stub.
  
   
  +
A few simple ''rendezvous'' scripts, to make ships appear in space, can be found in [[OXP_howto_plist#script.plist|here]].
   
  +
Missions are offered with special commands.
  +
How to do this so you won't disturb other OXP missions is seen [[OXP_mission_offering|here]].
   
   
−
--------------------------------------------------------------------------------
  
 
[[Category:Oolite]]
  
[[Category:Oolite]]
  +
[[Category:Oolite scripting]] [[Category:Legacy scripting]]

Latest revision as of 10:45, 9 August 2021

script.plist Used by missions and OXP's to check conditions and perform scripted actions accordingly. The legacy scripting engine used by this is not recommended for use in new OXPs - use Javascript for scripted behaviour instead.

In OXP's it can provide Oolite with additional information to generate and populate customised systems.

Structure

script.plist's structure is a dictionary, each entry is a particular script with a unique key.

Each script is an array of actions and conditional statements that are executed or checked at regular intervals (every 10 seconds or so during flight or docking).

For increased performance of a script one needs to add nested structures within the script structure. see: Structured Legacy Scripts

Actions

An action is a simple string referring to a method

Conditional statements

Conditional statements consist of a dictionary with entries for the keys conditions and do (and optionally else.)

conditions

conditions consists of an array of tests to be performed. Each test checks whether the current status of one of a number of queriable states and mission_variables are equal, lessthan, greaterthan a given value or state, or oneof a list of comma separated states. Note: As of v1.69 also a notequal operator will be available for Legacy scripting.

Multiple conditions may be specified, a logical 'AND' is applied to determine whether the conditions are met or not.

If all the conditions are met then the do entry is executed, if any are not met then the else entry is executed (if it exists).

example: 

<key>conditions</key>
<dict> 
    <array>
        <string>shipsFound_number equal 0</string>
    </array>
</dict>

do

do consists of an array of actions (and further conditional statements if required), executed if the conditions are met.

Example: 

<key>do</key>
<dict>
    <array>
        <string>addShips: asp-cloaked 1</string>
        <string>addShips: pirate 12</string>
    </array>
</dict>

else

else consists of an array of actions (and further conditional statements if required), executed if the conditions are NOT met.

Example: 

<key>else</key>
<dict>
    <array>
        <string>addShips: super-pirate 1</string>
    </array>
</dict>


Examples

A few simple rendezvous scripts, to make ships appear in space, can be found in here.

Missions are offered with special commands. How to do this so you won't disturb other OXP missions is seen here.

Retrieved from "http://backup.witchspacewiki.org/index.php?title=Script.plist&oldid=68228"