6A - Script Engine

• • • Script Constants
    • Datatypes
    • Tables
    • Parameter Definitions
    • Diplomacy Tasks
    • Advanced Hotkeys
    • Script Commands

There have been large number of changes to the Script Engine and Editor.

The Editor itself has had some improvements to hopefully make it a bit easier and quicker to work with.

• More categories and sub menus have been added for the commands to make it easier to find the commands you need
• Some of the commands have been move to different menus where it makes sense
• The Search Filter can be used to filter the list of available commands so you can just type in what you are looking for
• An 'All Commands' section has been added that shows all the commands in a single list, useful when using the search filter
• The parameter/variable menu has tabs added and split up the various selection so you don't need to scroll a lot to find things
• The parameter/variable menu also works with the search filter to quickly find things
• The Search filter also works in the script listing, and the various selection menus.

Script Constants

The script constants have been expanded with a large number of new constants.
The constants have also been grouped in collapsible groups rather than a single large list.
The search filter is also available to search by text

List Script Constants

Datatypes

There are a number of new datatypes available. Some related to the new features, others are useful for general scripting.

New Datatypes

• DATATYPE_AGENT - This is an agent object for use with diplomacy
• DATATYPE_AGENTCOMMAND - This is a diplomacy task use by agents in diplomacy, similar to ship/station commands
• DATATYPE_TABLE - See below for Table Info
• DATATYPE_LOADOUTRET - This is a return value from the ship loadout script commands
• DATATYPE_MERCHANT - This is for the merchant objects (Barter Menu) for use with script commands to control the barter system
• DATATYPE_DEALER - Similar to Merchant, but used on the Black Market instead of Barter, most commands can use either merchant or dealer
• DATATYPE_CARRIERROLE - This is the ship role for use with the carrier management, i.e. Fighter, Defender, Drone, etc
• DATATYPE_COMMANDMENU - This is one of the sub menus in the ship command menu, i.e. Trade, Combat, General, etc. For use with script commands dealing with command menu changes
• DATATYPE_GSUBTYPE - This is the Global Subtype class of objects, used by some ship/station information commands
• DATATYPE_MAINTYPE - This is the main type of a variable in the script engine
• DATATYPE_TIME - This is a time variable for using ms timing, there are various commands allowing you to manipulate time values
• DATATYPE_XMLDATA - This stores a parsed xml data structure, for use with reading and writing xml files

Tables

Tables will store data based on keys, previously, you had some limited table support by using the global/local variables to store data in string keys, which used tables internally to store this. Now you have more access to the table system, and can use them locally within your scripts. Like arrays, tables are stored by reference, so passing tables between scripts, or storing them in local/global variables will store the pointer to the table, so the same table can be modified across multiple scripts.

The key can be any data type, and you can mix data types within the same table. There are a few exceptions, any datatype where the sub value could be 0 will not function correctly in a table, for example the relation/neutral, most datatype will work fine however.

The main advantage with tables, is that you don't need to set the size of the table, or resize it, it will grow/shrink as needed and is generally quicker at this than arrays. Checking if a key is in the table is also quicker than checking in an array.
However, you cant control the order things will be in a table, so if your data needs to be in a set order, i.e. a sorted list of ships, then it will need to be in an array instead.

To use tables, you first need to allocate one

then you add/set data using the normal array commands

To iterate through a table list you use the get table next command
The key value is the previous key, use null to get the first key in the list.

NOTE: if you need to remove an item from the table while iterating through, make sure you get the next key before removing, IE:

You can also get all the keys as an array, and iterate through that array instead, this can also allow you to sort the table

NOTE: some of the new script commands will use tables as arguments or return values

Parameter Definitions

There have been a number of Parameter Definitions added.
These are the selection list types for various things, used in the arguments of scripts to get input of a certain type, or for use with the get user input command.
Script commands themselves also use these to limit the parameter selection

Some are related to the new features, others allow more filtering of the existing lists

• Var/Agent Command
• Var/Agent
• Var/Table
• Var/Array/Table
• Var/LoadoutRet
• Var/Merchant
• Var/Dealer
• Var/Merchant/Dealer
• Var/CarrierRole
• Var/CommandMenu
• Var/Galaxy SubType
• Var/Main Type
• Var/Available Ware
• Var/Space Object
• Var/Player Station Type
• Var/Property Group
• Var/Turret Command
• Var/Object/Turret Command
• Var/HSAP
• Var/Time
• Var/Retired Agents
• Var/Laser
• Var/Shield
• Var/Missile Type
• Var/Goods
• Var/Equipment
• Var/XMLData
• Var/Ship Command
• Var/Custom Wing

Diplomacy Tasks

With the new diplomacy system, you can add your own tasks, this works similar to the command console custom commands where you first register a new command, then set the global map, to map that command with a script. To get input for the script, you can also assign a menu script, this will run the menu using the new input system then send the final arguments onto the diplomacy script. Diplomacy command scripts have the first argument as the Diplomat object that's running the command.

To add a new command, you use:

The return value is the id of the command that's added, with the text and page id of the command. The menu script is the event script to create a menu for input.

The cmdcheck boolean will send the "cmdcheck" event to the menu script, which allows you to determine if the command should be available or not.
You will need to add 3 text entries for the agent command, the Command name, the Command Short Description, and the Command Long Description. These are the text id, text id + 1 and text id + 2.

The diplomacy menu event scripts have a few additional states that control how the command is displayed in the diplomacy menu

The cmdcheck event is sent when the menu is displayed, this works the same as the command console cmdcheck scripts you can use, returning one of the CmdConCheck constants. This event is only sent if the cmdcheck boolean value was set when creating the command, otherwise it will be set to CmdConCheck.Available.

The event "influence" displays the amount of influence need for the command. You can return a value, or you can use one of the script commands for creating the return value, these allow you to specify a range or a minimum amount.
The event "isspy" determines if its a espionage mission, these are displayed in a separate section in the diplomacy menu. Simply return TRUE.
The event "allowmultiple" determines if the command can stack multiple tasks, the return should be a string. This string is displayed as a description in the command menu.

There are also some script commands available to display the status of the current agent.

This displays the current task progress, the number is the percentage of the bar to display

This displays a status string for the agent (what the agent is currently doing)

This displays a timer instead of the progress bar (use this for commands that run permanently)

Advanced Hotkeys

The hotkey system has been updated to allow customisation, 4 new script commands have been added:

The <type> argument is used to specify the type of hotkey it is, this determines where it will appear in the controls menu.
The <menu> boolean determines if its a menu hotkey. Menu hotkeys can be used in custom menus, but wont work while in space, setting it to FALSE will be a normal space hotkey
The event hotkeys work slightly differently, where they will send a number of events to the script, instead of just being run when the hotkey is pressed. For the event script, the first argument is the hotkey ID, and the second is a string which is the event.

The events can be:

"pressed" - This is sent when the hotkey is first pressed (doesn't repeat if you hold down the key)
"released" - This is sent when you release the hotkey
"short" - This is sent after "released" and indicates it was pressed for a short time
"long" - This is send after "released" and indicates it was pressed for a longer time
"double" - This is sent instead of a second "pressed" event when a hotkey is pressed twice in a short period of time

Script Commands

A large amount of new script commands has also been added, including some changes to existing ones

List of New Script Commands