Because the mission-file-docs.txt file in Artemis 2.4 did not include all of the uses of player_slot that Thom mentioned in his Change Log, I thought I would go in and add those corrections. In addition, I have found that Elite Special Abilities are now handled totally differently from 2.1. I am not sure if these changes were made in 2.3 or 2.2, I noticed that I was unable to change specials in a previous test. So specials may have been managed with the set_special command for a while now.
I'd like for our scripting experts to go over this and see if there is anything I forgot or left out. If not, then I'd like to offer it for inclusion (with updates, of course) in the next Artemis release. I recommend copy and pasting this into your own mission-file-docs.txt file, so it will be up to date.
-----------------------------------------------------------------------------
MISSION SCRIPT DOCS FOR ARTEMIS SBS V2.4
4/17/2016
rev 12.1
-----------------------------------------------------------------------------
GENERAL NOTES
The mission script system is designed to let anyone create, share, and play
game missions for Artemis. In the Artemis install folder, there's a subfolder
called 'Dat'. Inside that is another folder called 'Missions'.
Inside the Missions folder, each mission needs to have its own unique folder.
Each mission folder name must start with 'MISS_'.
Inside a mission folder must be 1 XML file. It must share the same exact name
as the folder it's inside, except for the .xml suffix. This file will contain
all the commands that make the mission happen. There may be other files in the
same folder. As a general rule, any sound, video, or image files that the
mission uses must be in the same folder as the XML file that references it.
When the Artemis game starts up, choose "Start Server". At that point, the
game will look inside the Missions subfolder and make a list of every folder
that starts with 'MISS_'. On the Server control screen you can select one of
those missions. If you do, you can still set the game difficulty. The diff
setting won't control the amount and type of enemies (the mission will do that),
but it will still control the enemy beam damage and the efficiency of the
Artemis' systems.
When you've chosen your mission (and other settings), click the 'Start Game'
button. As the game is initialized, the Artemis app will attempt to
open the chosen folder and read the XML file inside. It will read the entire
XML script into memory, and keep it in memory for the entire game.
The XML script should contain a single block. At the start of
the mission, the commands in the start block will be immediately followed.
The XML script should also contain blocks. These blocks should
contain both COMMAND and CONDITION blocks. For each event block, all
of its CONDITION blocks are checked. If they are all TRUE, then
all of the event's COMMAND blocks are immediately followed.
So, when you make a mission XML file, use one start block to create all
the initial conditions of the mission. Then use event blocks to trigger
parts of the story when they are supposed to occur.
-----------------------------------------------------------------------------
THE BRAIN STACK
Now, all enemies and neutrals have a "Brain Stack". AI blocks get appended to the stack (using the add_ai command), and
the AI resolves each block from top (first) to bottom (last), so each AI block can supersede the AI blocks above it.
{L"TRY_TO_BECOME_LEADER"},
if your fleet value is 0 to 99, you belong to a fleet (IF you're an enemy). The fleet doesn't have a chosen leader; instead, if there's no leader, each member tries to claim the role. This block does that.
{L"CHASE_PLAYER"},
if a player ship is closer than value1 (value2 if the player is in a nebula), this enemy turns to attack it. If this enemy is a fleet leader, the fleet follows.
{L"CHASE_AI_SHIP"},
If an enemy:
if a neutral ship is closer than value1 (value2 if the neutral ship is in a nebula), this enemy turns to attack it. If this enemy is a fleet leader, the fleet follows.
If a neutral ship:
if an enemy is closer than value1 (value2 if the enemy is in a nebula), this neutral turns to attack it.
{L"CHASE_STATION"},
if a station is closer than value1, this enemy turns to attack it. If this enemy is a fleet leader, the fleet follows.
{L"CHASE_WHALE"}, (Deprecated?)
if a whale is closer than value1, this enemy turns to attack it. If this enemy is a fleet leader, the fleet follows.
{L"AVOID_WHALE"}, (Deprecated?)
if a whale is closer than value1, this enemy turns to left to avoid it.
{L"AVOID_BLACK_HOLE"}, (Deprecated?)
if a black hole is closer than value1, this enemy turns to left to avoid it.
{L"CHASE_ANGER"},
If this enemy or fleet is smarting from a recent attack, turn to attack the source.
{L"CHASE_FLEET"},
if an enemy fleet is closer than value1, this enemy turns to follow it. If this enemy is a fleet leader, the fleet follows. This block is usually used to make an enemy "shadow" another enemy fleet.
{L"FOLLOW_LEADER"},
if your fleet value is 0 to 99, you belong to a fleet (IF you're an enemy). This block makes you follow its commands.
{L"FOLLOW_COMMS_ORDERS"},
without this block, a neutral will ignore comms.
{L"LEADER_LEADS"},
if your fleet value is 0 to 99, you belong to a fleet (IF you're an enemy). If you're the leader, you need to do a little housekeeping with this block.
{L"SPCL_AI"},
IF the enemy wants to use special abilities like cloaking and warping, it needs this block.
{L"DIR_THROTTLE"},
The script can add this block to force an AI brain to a specific heading (value1) and throttle(value2).
{L"POINT_THROTTLE"},
The script can add this block to force an AI brain to a specific location (value1=x, value2=y, value3=z) and throttle(value4).
{L"TARGET_THROTTLE"},
The script can add this block to force an AI brain to move towards a specific unit (targetName) and throttle(value1).
{L"ATTACK"},
The script can add this block to force a brain to move toward and act on a named object (targetName), moving at throttle (value1).
{L"DEFEND"},
Add this block to make a neutral that has been given the "Go Defend" command by Comms attack enemies that get within (value2), as long as the neutral is closer than (value1) to whatever it's defending.
{L"PROCEED_TO_EXIT"},
All neutrals start out with a position (off the map) that they are trying to go to. This block guides them there.
{L"FIGHTER_BINGO"},
This block (for fighters only) makes the fighter go back to its carrier when fuel is low.
{L"LAUNCH_FIGHTERS"}
This block (for carriers only) launches all of the fighters that are refueled when a player ship is closer than (value1).
{L"GUARD_STATION"},
Add this block to make an enemy remain within (value1) of the nearest enemy base. Used on only certain enemies in Deep Strike and Border War modes. The equivalent command for neutral ships is DEFEND.
Deprecated:
{L"CHASE_NEUTRAL"},
{L"CHASE_ENEMY"},
{L"ELITE_AI"},
-----------------------------------------------------------------------------
RACEKEYS and HULLKEYS
Creating ships and assigning 3D hulls to them is now more flexible. The old way was to use the hullID attribute to specify
the exact ID of the hull (from the vesselData.xml file). That way is still active, but no longer recommended.
ATTRIBUTE: raceKeys
VALID: text (corresponds to hullRace name and keys in vesselData.xml)
ATTRIBUTE: hullKeys
VALID: text (corresponds to vessel className and broadType in vesselData.xml)
Instead, when you create a ship using the 'create' command, use the raceKeys and hullKeys to pick the best hull indirectly. For instance
(using vesselData.xml 1.60 as a reference), if you want to create an enemy that's a Torgoth Battleship, you use
This will make an enemy Torgoth Battleship. BUT, what if your script is being played by someone who's modified the vesselData.xml, or
a later version of the game has changed vesselData.xml, or the player is playing a modded game? Your script might not find the Torgoth race
or its Battleship hull. So let's broaden the keys to allow for alternatives:
NOW, if the Torgoth race isn't found, a race with the "enemy" key will be. If a Battleship isn't found, the "medium" broadtype will be. Now
your script stands a much better chance of working, no matter what changes have happened to the vesselData.xml file.
-----------------------------------------------------------------------------
Starting with Version 1.69, literal number values have been replaced by an expression evaluator. Put simply,
anywhere you can type in a number, you can also type in a math expression (like 5 * 2 / 6.554). Most importantly,
you can use variable names in the expressions, too.
These are all valid commands:
<set_variable name="ds38ZVAL" value="93000"/>
<set_variable name="ds38ZVAL" value="9300*20 / 2"/>
<set_variable name="ds38ZVAL" value="targetRange * (3000/2.55)"/>
-----------------------------------------------------------------------------
COMMAND: create (the command that creates named objects in the game)
ATTRIBUTE: type
VALID: station, player, enemy, neutral, anomaly, blackHole, monster, genericMesh, whale
ATTRIBUTE: x
VALID: 0 to 100000
ATTRIBUTE: y
VALID: -100000 to 100000
ATTRIBUTE: z
VALID: 0 to 100000
ATTRIBUTE: use_gm_position
VALID: anything, just use this attribute to cause the x,y,z to be at the game master's selected position
ATTRIBUTE: name
VALID: text
ATTRIBUTE: hulltype
VALID: 0-? (corresponds to the unique hull ID in vesselData.xml)
ATTRIBUTE: raceKeys
VALID: text (corresponds to hullRace name and keys in vesselData.xml)
ATTRIBUTE: hullKeys
VALID: text (corresponds to vessel className and broadType in vesselData.xml)
ATTRIBUTE: angle
VALID: 0-360
ATTRIBUTE: fleetnumber
VALID: 1-99 (if not specified, a random fleetnumber will be assigned)
ATTRIBUTE: sideValue
VALID: 1-31 (default is 1=enemy, 2 = friendly and players, 3+=own side)
-- for players
ATTRIBUTE: player_slot
VALID: 0-7 (corresponds to the 8 player ships allowed in the game)
use this with or instead of a "name" attribute
ATTRIBUTE: accent_color
VALID: 0-99
ATTRIBUTE: warp
VALID: yes or no
ATTRIBUTE: jump
VALID: yes or no
-- for genericMeshs
ATTRIBUTE: meshFileName
VALID: text
ATTRIBUTE: textureFileName
VALID: text
ATTRIBUTE: hullRace
VALID: text
ATTRIBUTE: hullType
VALID: text
ATTRIBUTE: fakeShieldsFront
VALID: 1-1000
ATTRIBUTE: fakeShieldsRear
VALID: 1-1000
NOTE: the fake shields default to -1, which means no fake shields
if only the fakeShieldsFront is positive, the generic looks like a station
ATTRIBUTE: hasFakeShldFreq
VALID: 0 or 1
ATTRIBUTE: ColorRed
VALID: 0.0-1.0
ATTRIBUTE: ColorGreen
VALID: 0.0-1.0
ATTRIBUTE: ColorBlue
VALID: 0.0-1.0
-- for anomalys
ATTRIBUTE: pickupType
VALID: 0-7
0 = ITEMTYPE_ENERGY, //Anomaly
1 = ITEMTYPE_RESTORE_DAMCON,//Vigoranium Nodule
2 = ITEMTYPE_HEAT_BUFF, //Cetrocite Crystal
3 = ITEMTYPE_SCAN_BUFF,//Lateral Array
4 = ITEMTYPE_WEAP_BUFF,//Tauron Focusers
5 = ITEMTYPE_SPEED_BUFF,//Infusion P-Coils
6 = ITEMTYPE_SHIELD_BUFF,//Carapaction Coils
7 = ITEMTYPE_COMM_BUFF,// secret code case
-- for monsters
ATTRIBUTE: monsterType
VALID: 0-7
0 = GMMONSTER_CLASSIC,
1 = GMMONSTER_WHALE,
2 = GMMONSTER_SHARK,
3 = GMMONSTER_DRAGON,
4 = GMMONSTER_PIRANHA,
5 = GMMONSTER_TUBE,
6 = GMMONSTER_BUG,
7 = GMMONSTER_DERELICT,
-- for whales and piranhas
ATTRIBUTE: podnumber
VALID: 0-9
If you use a pod number that's illegal, crashes and wierd graphical glitches will occur.
-----------------------------------------------------------------------------
COMMAND: create (the command that creates UNnamed objects in the game)
ATTRIBUTE: type
VALID: nebulas, asteroids, mines
ATTRIBUTE: count
VALID: 0 to 500
ATTRIBUTE: radius
VALID: 0 to 100000
ATTRIBUTE: randomRange
VALID: 0 to 100000
ATTRIBUTE: startX
VALID: 0 to 100000
ATTRIBUTE: startY
VALID: -100000 to 100000
ATTRIBUTE: startZ
VALID: 0 to 100000
ATTRIBUTE: use_gm_position
VALID: anything, just use this attribute to cause the startX,startY,startZ to be at the game master's selected position
ATTRIBUTE: endX
VALID: 0 to 100000
ATTRIBUTE: endY
VALID: -100000 to 100000
ATTRIBUTE: endZ
VALID: 0 to 100000
ATTRIBUTE: randomSeed
VALID: 0 to big number
ATTRIBUTE: startAngle
VALID: 0 to 360
ATTRIBUTE: endAngle
VALID: 0 to 360
-----------------------------------------------------------------------------
COMMAND: destroy (the command that removes something named from the game)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name, player_slot OR use_gm_selection
-----------------------------------------------------------------------------
COMMAND: destroy_near (the command that removes unnamed objects from the game, if near a point)
ATTRIBUTE: type
VALID: nebulas, asteroids, mines, whales, drones, all
ATTRIBUTE: centerX
VALID: 0 to 100000
ATTRIBUTE: centerY
VALID: -100000 to 100000
ATTRIBUTE: centerZ
VALID: 0 to 100000
ATTRIBUTE: radius
VALID: 0 to 100000
ATTRIBUTE: name
VALID: text
ATTRIBUTE: use_gm_position
VALID: anything, just use this attribute to cause the center to be at the game master's selected position
use the "name" attribute to destroy things close to a named object. the "name" attribute will
override the "center" attributes with the location of the named object
-----------------------------------------------------------------------------
COMMAND: add_ai (the command that adds an AI decision to a neutral or enemy's brain stack)
ATTRIBUTE: name
VALID: text, the name of the object
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name OR use_gm_selection
ATTRIBUTE: targetName
VALID: text, the target object of SOME AI blocks (currently only meaningful for ATTACK and TARGET_THROTTLE)
ATTRIBUTE: type
VALID: text, one of a list of AI blocks:
TRY_TO_BECOME_LEADER
CHASE_PLAYER
CHASE_AI_SHIP
CHASE_STATION
CHASE_WHALE
AVOID_WHALE
AVOID_BLACK_HOLE
CHASE_ANGER
CHASE_FLEET
FOLLOW_LEADER
FOLLOW_COMMS_ORDERS
LEADER_LEADS
SPCL_AI
DIR_THROTTLE
POINT_THROTTLE
TARGET_THROTTLE
ATTACK
DEFEND
PROCEED_TO_EXIT
FIGHTER_BINGO
LAUNCH_FIGHTERS
GUARD_STATION
ATTRIBUTE: value1
VALID: -100000 to 100000, contextual to the type of the AI block
ATTRIBUTE: value2
VALID: -100000 to 100000, contextual to the type of the AI block
ATTRIBUTE: value3
VALID: -100000 to 100000, contextual to the type of the AI block
ATTRIBUTE: value4
VALID: -100000 to 100000, contextual to the type of the AI block
-----------------------------------------------------------------------------
COMMAND: clear_ai (removes all AI decision blocks from a neutral or enemy's brain stack)
ATTRIBUTE: name
VALID: text, the name of the object
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name OR use_gm_selection
-----------------------------------------------------------------------------
COMMAND: direct (the command that tells a non-player ship to go somewhere or fight something)
(also tells generics where to go)
(this command can no longer work with ANYTHING except non-player shielded ships and generics)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: targetName
VALID: text
ATTRIBUTE: pointX
VALID: 0 to 100000
ATTRIBUTE: pointY
VALID: -100000 to 100000
ATTRIBUTE: pointZ
VALID: 0 to 100000
ATTRIBUTE: scriptThrottle
VALID: 0.0 to 1.0
(for generics this is an absolute speed)
-----------------------------------------------------------------------------
COMMAND: set_variable (makes or sets a named value)
ATTRIBUTE: name
VALID: text
-EITHER-
ATTRIBUTE: value
VALID: 0 to big number
-OR-
ATTRIBUTE: randomIntHigh
VALID: number
ATTRIBUTE: randomIntLow
VALID: number lower than randomIntHigh
-OR-
ATTRIBUTE: randomFloatHigh
VALID: number
ATTRIBUTE: randomFloatLow
VALID: number lower than randomFloatHigh
-----------------------------------------------------------------------------
COMMAND: set_timer (makes or sets a named timer)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: seconds
VALID: 0 to big number
-----------------------------------------------------------------------------
COMMAND: incoming_message (creates a Comms button to play a media file on the main screen)
ATTRIBUTE: from
VALID: text
ATTRIBUTE: fileName (all media files belong in the mission subdirectory, alongside the mission script XML file)
VALID: text
ATTRIBUTE: mediaType
VALID: 0 (for OGG audio files)
-----------------------------------------------------------------------------
COMMAND: big_message (creates a chapter title on the main screen)
ATTRIBUTE: title
VALID: text
ATTRIBUTE: subtitle1
VALID: text
ATTRIBUTE: subtitle2
VALID: text
-----------------------------------------------------------------------------
COMMAND: end_mission (stops the mission)
-----------------------------------------------------------------------------
COMMAND: incoming_comms_text (sends a block of text to the Comms station)
ATTRIBUTE: from
VALID: text
ATTRIBUTE: side (default = 0)
VALID: 0-31, (this is only used to match player side, or 0=no side)
BODY:
VALID: multiple lines of text
-----------------------------------------------------------------------------
COMMAND: log (sends text to the mission's log file)
ATTRIBUTE: text
VALID: text
-----------------------------------------------------------------------------
COMMAND: set_object_property (sets a named space object's named property to a value)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name, player_slot OR use_gm_selection
ATTRIBUTE: property
VALID: text (check the big list at the bottom of this file)
ATTRIBUTE: value
VALID: signed floating point value
-----------------------------------------------------------------------------
COMMAND: set_fleet_property (sets a numbered enemy fleet's named property to a value)
ATTRIBUTE: fleetIndex
VALID: 0-99
ATTRIBUTE: property
VALID: text (fleetSpacing, fleetMaxRadius)
ATTRIBUTE: value
VALID: signed floating point value
fleetSpacing is normally 150 - 600
fleetMaxRadius is normally 1000
-----------------------------------------------------------------------------
COMMAND: addto_object_property (adds a value to a named space object's named property)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name, player_slot OR use_gm_selection
ATTRIBUTE: property
VALID: text (check the big list at the bottom of this file)
ATTRIBUTE: value
VALID: signed floating point value
-----------------------------------------------------------------------------
COMMAND: copy_object_property (copies a named property from one named space object to another, name1 to name2)
ATTRIBUTE: name1
VALID: text
- OR -
ATTRIBUTE: player_slot1
VALID: 0-7
ATTRIBUTE: name2
VALID: text
- OR -
ATTRIBUTE: player_slot2
VALID: 0-7
ATTRIBUTE: property
VALID: text (check the big list at the bottom of this file)
-----------------------------------------------------------------------------
COMMAND: set_relative_position (moves one named space object (name2) to a point near another (name1), relative to name1's heading)
ATTRIBUTE: name1
VALID: text
- OR -
ATTRIBUTE: player_slot1
VALID: o-7
ATTRIBUTE: name2
VALID: text
- OR -
ATTRIBUTE: player_slot2
VALID: 0-7
ATTRIBUTE: angle
VALID: 0 to 360
ATTRIBUTE: distance
VALID: 0 100000
-----------------------------------------------------------------------------
COMMAND: set_to_gm_position (moves one named space object (name) to the point specified by clicking on the game master console screen)
ATTRIBUTE: name
VALID: text, the name of the object
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name, player_slot OR use_gm_selection
ATTRIBUTE: angle
VALID: 0 to 360
ATTRIBUTE: distance
VALID: 0 100000
-----------------------------------------------------------------------------
COMMAND: set_skybox_index (sets the skybox of the main screen to 0-9)
ATTRIBUTE: index
VALID: 0-9
-----------------------------------------------------------------------------
COMMAND: warning_popup_message (sends a very short message to the screens specified)
ATTRIBUTE: player_slot
VALID: 0-7 (if not specified, defaults to ship 0 (all ships?))
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
You only need to use one, player_slot OR use_gm_selection
If none of these attributes are specified, defaults to ship 0 (all ships?)
ATTRIBUTE: message
VALID: text
ATTRIBUTE: consoles
VALID: text, a collection of the letters MHWESCO, defining which console the message appears on
-----------------------------------------------------------------------------
COMMAND: set_difficulty_level (overrides the difficulty level set on the server control screen)
ATTRIBUTE: value
VALID: 1-10
-----------------------------------------------------------------------------
COMMAND: set_player_grid_damage (changes the damage value of a ship system in the 3D grid)
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either player_slot OR use_gm_selection
if none of these attributes are specified, defaults to ship 0
ATTRIBUTE: systemType
systemBeam
systemTorpedo
systemTactical
systemTurning
systemImpulse
systemWarp
systemFrontShield
systemBackShield
ATTRIBUTE: value
VALID: 0.0-1.0 ( 0.0 is no damage, 1.0 is full damage)
ATTRIBUTE: countFrom
VALID: left, top, or front
ATTRIBUTE: index
VALID: 0-100 (you can't damage more systems than the ship has)
-----------------------------------------------------------------------------
COMMAND: play_sound_now
ATTRIBUTE: filename
VALID: text (name of the WAV file in the mission's directory)
-----------------------------------------------------------------------------
COMMAND: set_damcon_members (changes the count of team members in a specific damcon team)
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either player_slot OR use_gm_selection
if none of these attributes are specified, defaults to ship 0
ATTRIBUTE: team_index
VALID: 0-2
ATTRIBUTE: value
VALID: 0-6
-----------------------------------------------------------------------------
COMMAND: set_ship_text
ATTRIBUTE: name
VALID: text name of existing player, enemy or neutral
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name, player_slot OR use_gm_selection
-- if you don't include the following attributes, those attributes will not be changed
ATTRIBUTE: newname
VALID: text name to change it to
ATTRIBUTE: race
VALID: text of race
ATTRIBUTE: class
VALID: text of class
ATTRIBUTE: desc
VALID: description the science console sees after one scan
ATTRIBUTE: scan_desc
VALID: description the science console sees after two scans
ATTRIBUTE: hailtext
VALID: text this ship will reply with when comms "hails" them
-----------------------------------------------------------------------------
COMMAND: start_getting_keypresses_from (sets a client console to key-active; it sends key press messages to the server)
ATTRIBUTE: consoles
VALID: text, a collection of the letters MHWESCO, defining which console(s) we want
-----------------------------------------------------------------------------
COMMAND: end_getting_keypresses_from (sets a client console to NOT key-active)
ATTRIBUTE: consoles
VALID: text, a collection of the letters MHWESCO, defining which console(s) we want
-----------------------------------------------------------------------------
COMMAND: set_special (changes the "specialCaptainType" and "specialShipType" variables of an AIShip, and rebuilds the scan text for the ship; also adjusts the special abilities of an AIShip)
ATTRIBUTE: name
VALID: text name of existing NPC ship
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name OR use_gm_selection
-- if you don't include the following attributes, those attributes will not be changed
ATTRIBUTE: ship
VALID: -1 to 3
-1 = nothing
0=upgraded
1=overpowered
2=underpowered
ATTRIBUTE: captain
VALID: -1 to 5
-1 = nothing
0=cowardly
1=brave
2=bombastic
3=seething
4=duplicitous
5=exceptional
ATTRIBUTE: ability (you can only use this attribute once per "set_special" command)
VALID: text, consisting of one of the following:
Stealth
LowVis
Cloak
HET
Warp
Teleport
Tractor
Drones
AntiMine
AntiTorp
ShldDrain
ShldVamp
ATTRIBUTE: clear
VALID: anything
this switches the prior "ability" attribute, so instead of turning on the named special ability, it turns it off
-----------------------------------------------------------------------------
COMMAND: set_side_value (changes the sideValue of a game object)
ATTRIBUTE: name
VALID: text name of existing ship or station
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name, player_slot OR use_gm_selection
ATTRIBUTE: value
VALID: 1-31, 1 = enemy (normally), 2 = player side (normally), 3+ = own side
-----------------------------------------------------------------------------
COMMAND: set_gm_button (adds a button to the current GM console)
ATTRIBUTE: text
VALID: name of button. If this button doens't have a position set, it's a menu button, and can have sub-menus by adding / character to this text, such as "Create Enemy/Extras/Minefield arc"
ATTRIBUTE: x,y,w,h
VALID: 1-1000
these four attributes allow you to define the exact position and size of the button on the GM client screen.
ATTRIBUTE: menu_w
VALID: 1-1000
this attribute will set the pixel width of every menu button
set_gm_button, clear_gm_button, and if_gm_button let you add graphical buttons
to the GM console, and trigger events based on the GM clicking those buttons.
-----------------------------------------------------------------------------
COMMAND: clear_gm_button (removes a button from the current GM console)
ATTRIBUTE: text
VALID: name of existing button. Use the exact text you used to create the button (with set_gm_button).
set_gm_button, clear_gm_button, and if_gm_button let you add graphical buttons
to the GM console, and trigger events based on the GM clicking those buttons.
-----------------------------------------------------------------------------
CONDITION: if_inside_box (tests if named object is inside a rectangle in space)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
you only need to use one, either name OR player_slot
ATTRIBUTE: leastX
VALID: 0 to 100000
ATTRIBUTE: leastZ
VALID: 0 to 100000
ATTRIBUTE: mostX
VALID: 0 to 100000
ATTRIBUTE: mostZ
VALID: 0 to 100000
-----------------------------------------------------------------------------
CONDITION: if_outside_box (tests if named object is outside a rectangle in space)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
you only need to use one, either name OR player_slot
ATTRIBUTE: leastX
VALID: 0 to 100000
ATTRIBUTE: leastZ
VALID: 0 to 100000
ATTRIBUTE: mostX
VALID: 0 to 100000
ATTRIBUTE: mostZ
VALID: 0 to 100000
-----------------------------------------------------------------------------
CONDITION: if_inside_sphere (tests if named object is inside a sphere in space)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
you only need to use one, either name OR player_slot
ATTRIBUTE: centerX
VALID: 0 to 100000
ATTRIBUTE: centerY
VALID: -100000 to 100000
ATTRIBUTE: centerZ
VALID: 0 to 100000
ATTRIBUTE: radius
VALID: 0 to 100000
-----------------------------------------------------------------------------
CONDITION: if_outside_sphere (tests if named object is outside a sphere in space)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
you only need to use one, either name OR player_slot
ATTRIBUTE: centerX
VALID: 0 to 100000
ATTRIBUTE: centerY
VALID: -100000 to 100000
ATTRIBUTE: centerZ
VALID: 0 to 100000
ATTRIBUTE: radius
VALID: 0 to 100000
-----------------------------------------------------------------------------
CONDITION: if_distance (tests the distance between two named objects against a condition)
ATTRIBUTE: name1
VALID: text
ATTRIBUTE: name2
VALID: text
ATTRIBUTE: pointX
VALID: 0 to 100000
ATTRIBUTE: pointY
VALID: -100000 to 100000
ATTRIBUTE: pointZ
VALID: 0 to 100000
ATTRIBUTE: comparator
VALID: =, !=, <, >, <=, >=, EQUALS, NOT, GREATER, LESS, GREATER_EQUAL, LESS_EQUAL
ATTRIBUTE: value
VALID: signed floating point value
-----------------------------------------------------------------------------
CONDITION: if_variable (tests a named variable against a condition)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: comparator
VALID: =, !=, <, >, <=, >=, EQUALS, NOT, GREATER, LESS, GREATER_EQUAL, LESS_EQUAL
ATTRIBUTE: value
VALID: signed floating point value
-----------------------------------------------------------------------------
CONDITION: if_damcon_members (tests the count of team members in a specific damcon team against a condition)
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either player_slot OR use_gm_selection
if none of these attributes are specified, defaults to ship 0
ATTRIBUTE: team_index
VALID: 0, 1, or 2
ATTRIBUTE: comparator
VALID: =, !=, <, >, <=, >=, EQUALS, NOT, GREATER, LESS, GREATER_EQUAL, LESS_EQUAL
ATTRIBUTE: value
VALID: signed floating point value
-----------------------------------------------------------------------------
CONDITION: if_fleet_count (tests an indexed fleet's membership count against a condition)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: comparator
VALID: =, !=, <, >, <=, >=, EQUALS, NOT, GREATER, LESS, GREATER_EQUAL, LESS_EQUAL
ATTRIBUTE: value
VALID: signed floating point value
ATTRIBUTE: fleetnumber
VALID: 0-99
ATTRIBUTE: sideValue (optional)
VALID: 0-30,
ATTRIBUTE: countSurrendered (optional)
VALID: 0-99 normally this doesn't include surrendered ships in the count. Setting "countSurrendered" to 1 includes them in the count
if you omit the fleetnumber, this command will count every enemy in the game
-----------------------------------------------------------------------------
CONDITION: if_difficulty (tests the current game's difficulty level against a condition)
ATTRIBUTE: comparator
VALID: =, !=, <, >, <=, >=, EQUALS, NOT, GREATER, LESS, GREATER_EQUAL, LESS_EQUAL
ATTRIBUTE: value
VALID: signed floating point value
-----------------------------------------------------------------------------
CONDITION: if_docked (tests if a player is docked with a named station)
ATTRIBUTE: player_name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either player_name, player_slot OR use_gm_selection
if none of these attributes are specified, defaults to ship 0
ATTRIBUTE: name
VALID: text
-----------------------------------------------------------------------------
CONDITION: if_player_is_targeting (tests if the Artemis's weapons officer has a lock on the named object)
ATTRIBUTE: player_name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either player_name, player_slot OR use_gm_selection
if none of these attributes are specified, defaults to ship 0
ATTRIBUTE: name
VALID: text
-----------------------------------------------------------------------------
CONDITION: if_timer_finished (tests if a timer has counted down to zero yet)
ATTRIBUTE: name
VALID: text
-----------------------------------------------------------------------------
CONDITION: if_exists (tests if named object exists right now)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
you only need to use one, either name OR player_slot
-----------------------------------------------------------------------------
CONDITION: if_not_exists (tests if named object does NOT exist right now)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
you only need to use one, either name OR player_slot
-----------------------------------------------------------------------------
CONDITION: if_object_property (tests a named space object's named property against a condition)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: player_slot
VALID: 0-7
ATTRIBUTE: use_gm_selection
VALID: anything, just use this attribute to use the game master's selected object
you only need to use one, either name, player_slot OR use_gm_selection
ATTRIBUTE: property
VALID: property (check the big list at the bottom of this file)
ATTRIBUTE: comparator
VALID: =, !=, <, >, <=, >=, EQUALS, NOT, GREATER, LESS, GREATER_EQUAL, LESS_EQUAL
ATTRIBUTE: value
VALID: signed floating point value
-----------------------------------------------------------------------------
CONDITION: if_gm_key (triggers when a key is pressed on a game master console)
ATTRIBUTE: keyText
VALID: text, single letter (usually upper case)
ATTRIBUTE: value
VALID: 0-128 (raw key scan code)
you only need to use one, either keyText OR value
-----------------------------------------------------------------------------
CONDITION: if_client_key (triggers when a key is pressed on a key-activated console)
ATTRIBUTE: keyText
VALID: text, single letter (usually upper case)
ATTRIBUTE: value
VALID: 0-128 (raw key scan code)
you only need to use one, either keyText OR value
NOTE: use start_getting_keypresses_from and end_getting_keypresses_from to key-activate a console.
-----------------------------------------------------------------------------
CONDITION: if_gm_button (triggers when a button from the current GM console is clicked)
ATTRIBUTE: text
VALID: name of existing button. Use the exact text you used to create the button (with set_gm_button).
set_gm_button, clear_gm_button, and if_gm_button let you add graphical buttons
to the GM console, and trigger events based on the GM clicking those buttons.
-----------------------------------------------------------------------------
NOTE: Properties you can set, add, or test against:
// values that are in the game, not actually attached to an object. To use these, do not name the object when using "if_object_property" or similar commands.
nebulaIsOpaque
sensorSetting
gameTimeLimit
networkTickSpeed
nonPlayerSpeed
nonPlayerShield
nonPlayerWeapon
playerWeapon
playerShields
coopAdjustmentValue
// values for everything
positionX
positionY
positionZ
deltaX
deltaY
deltaZ
angle --these 3 values will be in radians (0-2*PI), NOT degrees like every other angle in the scripting parser
pitch
roll
sideValue 1 = enemy (normally), 2 = player side (normally), 3+ = other sides
// values for GenericMeshs
blocksShotFlag
pushRadius
pitchDelta
rollDelta
angleDelta
artScale
// values for Stations
shieldState
canBuild
missileStoresHoming
missileStoresNuke
missileStoresMine
missileStoresECM
missileStoresPShock
// values for ShieldedShips
throttle
steering
topSpeed
turnRate
shieldStateFront
shieldMaxStateFront
shieldStateBack
shieldMaxStateBack
shieldsOn
triggersMines
systemDamageBeam
systemDamageTorpedo
systemDamageTactical
systemDamageTurning
systemDamageImpulse
systemDamageWarp
systemDamageFrontShield
systemDamageBackShield
shieldBandStrength0
shieldBandStrength1
shieldBandStrength2
shieldBandStrength3
shieldBandStrength4
// values for Enemys
targetPointX
targetPointY
targetPointZ
hasSurrendered
surrenderChance (0-100)
tauntImmunityIndex (0,1, or 2)
// values for Neutrals
exitPointX
exitPointY
exitPointZ
// values for Players
countHoming
countNuke
countMine
countECM
energy
warpState
currentRealSpeed (read only)
totalCoolant
// eliteAbilityBits, eliteAbilityState and eliteAIType have been deprecated
// eliteAbilityBits has been replaced by set_special
For each ability you want an elite enemy to have, create a separate set_special command, with that ability.
For example, given a ship created with the name "A21":
<set_special name="A21" ability="Warp"/>
<set_special name="A21" ability="Drones"/>
will give that ship both Warp and Drones. Note this does not have to be a Skaraan ship, it can apply to any enemy. (All the Skaraan tag "hasspecials" does is give Skaraans specials automatically in Invasion mode)
You can use "clear" to remove specials. For instance, if you want to simulate A21 losing Warp drive after taking several hits, you could call the following:
<set_special name="A21" clear="Warp"/>
Don't forget that a ship must have its SPCL_AI block set in the AI stack to use special abilities.
Category: Mission Scripting