Members | Sign In
All Forums > Mission Scripting
avatar

Mission SCript ref V1.40

posted Apr 15, 2011 22:10:22 by ThomRobertson
-----------------------------------------------------------------------------
MISSION SCRIPT DOCS FOR ARTEMIS SBS V1.36
4/13/2011
rev 2

-----------------------------------------------------------------------------
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 <start> block. At the start of
the mission, the commands in the start block will be immediately followed.

The XML script should also contain <event> 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.



-----------------------------------------------------------------------------
COMMAND: create (the command that creates everything you can think of in the game)
ATTRIBUTE: type
VALID: station, player, enemy, neutral, nebulas, asteroids, mines, anomaly
ATTRIBUTE: x
VALID: 0 to 100000
ATTRIBUTE: y
VALID: -100000 to 100000
ATTRIBUTE: z
VALID: 0 to 100000
ATTRIBUTE: name
VALID: text
ATTRIBUTE: hulltype
VALID: 0-? (corresponds to the unique hull ID in vesselData.xml)
ATTRIBUTE: angle
VALID: 0-360
ATTRIBUTE: fleetnumber
VALID: 1-99

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: 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 from the game)
ATTRIBUTE: name
VALID: text


-----------------------------------------------------------------------------
COMMAND: destroy_near (the command that removes unnamed objects from the game, if near a point)
ATTRIBUTE: type
VALID: nebulas, asteroids, mines
ATTRIBUTE: centerX
VALID: 0 to 100000
ATTRIBUTE: centerY
VALID: -100000 to 100000
ATTRIBUTE: centerZ
VALID: 0 to 100000
ATTRIBUTE: radius
VALID: 0 to 100000


-----------------------------------------------------------------------------
COMMAND: direct (the command that tells a neutral or enemy to go somewhere or fight something)
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


-----------------------------------------------------------------------------
COMMAND: set_variable (makes or sets a named value)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: value
VALID: 0 to big number

-----------------------------------------------------------------------------
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
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: property
VALID: text
ATTRIBUTE: value
VALID: signed floating point value

NOTE: Properties you can set:
// values for everything
positionX
positionY
positionZ

// values for Stations
shieldState
canBuild
missileStoresHoming
missileStoresNuke
missileStoresMine

// values for ShieldedShips
throttle
steering
topSpeed
turnRate
shieldStateFront
shieldMaxStateFront
shieldStateBack
shieldMaxStateBack
shieldsOn
hullDamageFront
hullDamageBack
systemDamageBeam
systemDamageTorpedo
systemDamageTactical
systemDamageTurning
systemDamageImpulse
systemDamageWarp
systemDamageFrontShield
systemDamageBackShield
shieldBandStrength0
shieldBandStrength1
shieldBandStrength2
shieldBandStrength3
shieldBandStrength4

// values for Enemys
targetPointX
targetPointY
targetPointZ
hasSurrendered
eliteAIType
eliteAbilityBits
eliteAbilityState

// values for Neutrals
willAcceptCommsOrders







-----------------------------------------------------------------------------
CONDITION: if_inside_box (tests if named object is inside a rectangle in space)
ATTRIBUTE: name
VALID: text

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: 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: 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: 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_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


-----------------------------------------------------------------------------
CONDITION: if_docked (tests if a player is docked with a named station)
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


-----------------------------------------------------------------------------
CONDITION: if_object_property (tests a named space object's named property against a condition)
ATTRIBUTE: name
VALID: text
ATTRIBUTE: name
VALID: property
ATTRIBUTE: comparator
VALID: =, !=, <, >, <=, >=, EQUALS, NOT, GREATER, LESS, GREATER_EQUAL, LESS_EQUAL
ATTRIBUTE: value
VALID: signed floating point value

NOTE: Properties you can test against:
// values for everything
positionX
positionY
positionZ

// values for Stations
shieldState
canBuild
missileStoresHoming
missileStoresNuke
missileStoresMine

// values for ShieldedShips
throttle
steering
topSpeed
turnRate
shieldStateFront
shieldMaxStateFront
shieldStateBack
shieldMaxStateBack
shieldsOn
hullDamageFront
hullDamageBack
systemDamageBeam
systemDamageTorpedo
systemDamageTactical
systemDamageTurning
systemDamageImpulse
systemDamageWarp
systemDamageFrontShield
systemDamageBackShield
shieldBandStrength0
shieldBandStrength1
shieldBandStrength2
shieldBandStrength3
shieldBandStrength4

// values for Enemys
targetPointX
targetPointY
targetPointZ
hasSurrendered
eliteAIType
eliteAbilityBits
eliteAbilityState

// values for Neutrals
willAcceptCommsOrders
Creator of Artemis
page   first prev 1 2 3 4
58 replies
avatar
Mike_Substelny said May 10, 2011 17:44:13
Thom, I didn't try to change the Artemis's throttle or top speed. I tried to poll the Atremis's throttle position, but come to think of it I didn't do anything with the value so I have no idea if it worked.

The following, however, did not work as of Sunday. Transport_1 flew right past DS04. Could it be the underscore? Are some characters illegal for named objects?


<event>
<if_exists name="Transport_1">
<if_distance name1="Transport_1" name2="DS04" comparator="<=" value="1000"/>
<if_variable name="lesson" comparator="=" value="4"/>
<incoming_comms_text from="Transport_1">
We made it safely to DS04.^
Thanks for your protection, Artemis.^
-
</incoming_comms_text>
<destroy name="Transport_1"/>
</event>
"Damn the torpedoes! Four bells, Captain Drayton!"

(Likely actual words of Admiral David Farragut, USN, at the battle of Mobile Bay. Four bells was the signal for the engine room to make full steam ahead).
avatar
ThomRobertson said May 13, 2011 03:22:29
I'm sure there ARE some illegal characters; computer text is full of 'em. But I THINK underscores are okay. I'll look again.
Creator of Artemis
avatar
Mike_Substelny said May 13, 2011 13:27:11
Thanks. The character had been a space before and that didn't work. In the mission scripts that you have written object names seem to contain neither spaces nor underscores, but that does not mean they are illegal. Either way, it will be good to document the rules for object names.

For the record, I was able to create the ship as both "Transport 1" and "Transport_1." Both times it behaved correctly in all ways, except that the above event was not triggered when it came within 1000 meters of DS01.
"Damn the torpedoes! Four bells, Captain Drayton!"

(Likely actual words of Admiral David Farragut, USN, at the battle of Mobile Bay. Four bells was the signal for the engine room to make full steam ahead).
avatar
Mike_Substelny said May 14, 2011 01:03:28
I found an explanation but do not understand the cause. The problem is that this is far down in the physical XML file. Tonight I discovered that nothing in the file executes after line 666. If I move the event above line 666 it will execute, but then some other event will stop working.

I started the "Numerology" thread to address this concern.
"Damn the torpedoes! Four bells, Captain Drayton!"

(Likely actual words of Admiral David Farragut, USN, at the battle of Mobile Bay. Four bells was the signal for the engine room to make full steam ahead).
avatar
Eric said May 14, 2011 02:21:40
Is there a way to check if weapons are fired? I was thinking of having an of highly ionized particles or something (think of the Bad Lands) that would damage the Artemis if you fired inside it. You could lure bad guys in there and let them fire at you while you pump all your energy into shields, or if you get jumped inside of it you'd have to decide whether or not to fight back or cut and run.

For that matter, can we use an "if" to check if shields are up or warp is engaged?
avatar
David said May 15, 2011 05:40:00
I'm having trouble getting my missions to end - I fulfil all the conditions, but the simulation doesn't end.

Not sure why - using identical text, one of my missions completes when the enemy are destroyed, but the next won't end.
avatar
Mike_Substelny said May 17, 2011 20:10:05
Eric, I believe that you can set a bunch of conditions on shield level that can tell if shields are up or even if enemy ships have fired. You would need a large number of events and variables, but you could determine that Artemis's shield level had dropped any. If so, it must have been due to enemy fire or mine/nuke blast. In that case execute your consequences.
"Damn the torpedoes! Four bells, Captain Drayton!"

(Likely actual words of Admiral David Farragut, USN, at the battle of Mobile Bay. Four bells was the signal for the engine room to make full steam ahead).
avatar
Mike_Substelny said May 17, 2011 20:10:21
BTW on the problem I posted above Thom found the syntax error in my XML file. The problem was of my own making.
"Damn the torpedoes! Four bells, Captain Drayton!"

(Likely actual words of Admiral David Farragut, USN, at the battle of Mobile Bay. Four bells was the signal for the engine room to make full steam ahead).
avatar
Mike_Substelny said May 18, 2011 13:51:14
Fleet AI is opaque to me. In my Shakedown Cruise I have several moments when I drop enemy formations onto the map and have them attack Artemis. This works, the fleets appear at the right moment in exactly the formation I want facing Artemis and poised to attack. But *before* they attack Artemis they do a little dance and rearrange themselves into a different formation. The time spent rearranging themselves gives Artemis a 2-3 minute grace period to swoop in and go for the jugular.

Is there a way to get them to stay in the formations that I wanted, at least until combat starts? Or can I predict how their AI will react to being placed in a formation shaped like a V, A, X, C, Y, or box?
"Damn the torpedoes! Four bells, Captain Drayton!"

(Likely actual words of Admiral David Farragut, USN, at the battle of Mobile Bay. Four bells was the signal for the engine room to make full steam ahead).
avatar
ThomRobertson said May 20, 2011 01:26:28
do a little dance and rearrange themselves


Fleets are designed to stay together. They have a simple AI that detects if one of them is further away from the center of the fleet than is permissible. If so, they all head towards the current center of the fleet. However, they all still avoid each other too, and that radius is variable, and I don't currently expose it. I'll look into it.

Creator of Artemis
avatar
Mike_Substelny said May 20, 2011 03:28:29
Thanks. The radius may not need to be exposed, but it should be predictable. If it is random then mission scripts can play out differently based on luck. An enemy admiral who is supposed to be a feared strategic genius may maneuver his fleet like a moron some days. :)
"Damn the torpedoes! Four bells, Captain Drayton!"

(Likely actual words of Admiral David Farragut, USN, at the battle of Mobile Bay. Four bells was the signal for the engine room to make full steam ahead).
avatar
Mike_Substelny said May 27, 2011 20:55:48
I may have discovered a humorous bug. Stations prefer to be created at the beginning of a mission; if you create them mid-mission they misbehave. The station I have created mid-mission will refuel and re-arm Artemis and it appears on the front screen as well as tactical. But it does not appear on the helm or weapons screen, which makes docking a bit more challenging. The helmsman needs to use the forward viewscreen to dock. Also, the enemies treat this base strangely. A squadron of Argonian battleships fired at it for a while, then got bored and left before it was destroyed. They went in a random direction not toward any target I specified, or Artemis, or another base. They just left for no reason.
"Damn the torpedoes! Four bells, Captain Drayton!"

(Likely actual words of Admiral David Farragut, USN, at the battle of Mobile Bay. Four bells was the signal for the engine room to make full steam ahead).
avatar
Mike_Substelny said Jun 06, 2011 14:22:06
Details: I have posted the mission script to which I was referring: SHAKEDOWN. In SHAKEDOWN if stations DS3 or DS4 are destroyed they re-appear 30 seconds later. Both original stations behave fine, but the re-created DS3 or DS4 only appear on the Main Screen. They are invisible on all of the consoles. The re-created stations function properly (Artemis can dock to get energy and weapons, enemies will hunt and attack them) but somehow both are invisible to all five consoles.

I have tried it in release 1.46 and I observe the same thing. It might be possible that this is a problem with my network; maybe the consoles aren't updated fast enough or something. If anyone else plays SHAKEDOWN and DS3 or DS4 are destroyed please let me know if they become invisible.
"Damn the torpedoes! Four bells, Captain Drayton!"

(Likely actual words of Admiral David Farragut, USN, at the battle of Mobile Bay. Four bells was the signal for the engine room to make full steam ahead).
Login below to reply: