# Action Editor

## Standard Actions

### Create Object

Creates one or more objects of any type. If the new object's auto target attribute flag is set, the object will be created at the angle facing the current target of the subject.

> #### Which Base Type

> Specifies which type of object to create.

> #### How Many Min

> The minimum number of objects to create. Usually 1. Can be negative; for example if the how many min value is set to -1 and the how many range value is set to 3 (a random value from 0 to 2) then there's a 1 in 3 chance that executing this action will create one object.

> #### How Many Range

> A random additional value added to the how many min value, from 0 to the the value specified minus 1.

> #### Velocity Relative

> If checked, then the object being created will be created at the subject object's vector.

> #### Direction Relative

> If checked, then the new objected will be created facing the same direction as the subject object (unless the new object's auto target attribute flag is checked).

> #### Distance Range

> A value greater than or equal to 0. Specifies a random X and Y offset to the new object being created.

### Play Sound

Plays an 'snd ' resource.

> #### Priority

> Ares has just four channels of sound -- only four sounds can be playing at any given time. To make the best use of those four channels, commands to play sound are given priority.

> The higher the priority, the more likely it is that a sound will be played. Sounds played with the highest priority, must play, will be played no matter what.

> #### Persistence

> How long, in 1/60ths of a second, the sound should play before a sound of equal or lower priority can use the sound channel.

> #### Absolute

> Whether or not the sound should be played at a volume relative to the distance of the direct object from the player. If not checked, the sound will be played louder the closer the direct object is to the player. If checked, the sound will play as loud as if the direct object was right next to the player.

> #### Volume Minimum

> The minimum volume, from 0 to 255, at which to play the sound. 0 is silent, 255 is as loud as possible. The actual volume of the sound will depend on the distance of the direct object from the player if the absolute option is not checked.

> #### Volume Range

> A random additional value to add to the volume of the sound.

> #### Sound Resource ID

> The ID of the 'snd ' to be played. [NLB -- there really should be a choose button, perhaps an entire sound importer]

> #### Sound Resource ID Range

> To play a random sound out of a set of sounds, they must have sequential resource ids, such as 500, 501, 502. 503. This value is zero based. To randomly play either sound 500, 501, 502, or 503, the sound resource id would be 500 and the sound resource id range would be 4.

### Make Sparks

A special effect which creates single-pixel "sparks." Sparks are always created at random angles.

> #### How Many

> The number of sparks to create. Use small values (there can only be 25 sparks existing at one time).

> #### Velocity

> The minimum velocity of the new sparks.

> #### Velocity Range

> A random additional value added to the sparks' velocities.

> #### Color

> The color of the new sparks.

### Release Energy

Not implemented.

> #### Percent

> Not implemented.

### Land At

Causes the source object to shrink into nothingness at the center of the direct object. Used by transports landing on planets. Also used by ships going through jumpgates. Once an object has reached its minimum apparent size, it executes its expire action sequence, if any.

> #### Landing Speed

> An arbitrary speed value. Higher values are faster. Transports have a landing speed of 32.

### Enter Warp

Causes the source object to travel at superlight speed, if it's capable of doing so.

This action may cause unpredictable results -- it was not used in the shipping version of Ares.

> #### Warp Speed

> Ignored.

### Display Message

Causes a text message to appear -- may have unpredictable results in net scenarios (will probably appear on both player's screens).

> #### "Text' Resource ID

> The 'TEXT' id of the text to show.

> #### Number of Pages

> If the message is long, it should be broken down into several pages. This value is 1-based, so if there is only one page of text, enter 1.

> Each page must be a 'TEXT' resource with sequential ids; for example, if the first page had an id of 5000, the next page should have an id of 5001 and the third page an id of 5002.

### Change Score

Alters the score, or counter, for a given player.

> #### Which Player

> The player number who's score you want to change. 0-based. Enter 0 for player one or 1 for player 2.

> #### Which Score

> The index of the score to change. 0-based. Enter 0 for the first score, 1 for the second, or 2 for the third score.

> #### Amount

> The value to add to the specified score. Enter negative values to subtract from the score.

### Declare Winner

Ends the scenario and either returns to the main menu or advances to the specified scenario.

> #### Which Player

> Which player wins. If the next level value is not negative, should be the human player. For net games can be either net player.

> #### Next Level

> For single player games only. Specifies what scenario number to play next. Use -1 to end the game.

> #### Result 'TEXT' Resource ID

> The id of the 'TEXT' resource to display in the result box. If the player lost, it should say why. If the player won, it should congratulate him.

### Die

Causes an object to cease to exist. If an object's health goes below 0, or it reaches its maximum age (for objects with an age), or it plays through its animation (for self-animating, non-cycling sprite objects), or an object completes a land at action, it dies on its own. You don't need to use the die action explicitly.

However, for missiles that should cease to exist when they collide with ships, you do need to explicitly cause them to die. Otherwise, they will continue to travel through the ship they are colliding with.

> #### Death Type

> ##### None

> Direct object will simply cease to exist. No further action will be taken.

> ##### Expire

> Before direct object ceases to exist, will execute its expire action sequence, if any.

> ##### Destroy

> Before direct object cease to exist, will execute its destroy action sequence, if any.

### Set Destination

Sets the direct object to be the assigned target of the subject object. Usually used only on initial objects. For example, in the chapter "Easy Street," when a specific transport is destroyed, two enemy cruisers, specified by their initial object indexes, are given the human player's ship, specified by its initial index, as a destination.

### Activate Special

Causes the subject object to activate its special device.

### Activate Pulse

Not implemented.

### Activate Beam

Not implemented.

### Color Flash

Causes the entire screen to partially fade to the specified color.

> #### Length of Flash

> How long, in 1/20ths of a second, to partially fade to the specified color.

> #### Color

> The color of the fade.

> #### Shade

> The brightness of the color.

### Create Obj Inherit Dest

Exactly the same as the create object action, except that the created object automatically are given the subject object as their destination. Created to allow carriers to produce fighters with the carriers as the fighter's destination (not the player's current target).

### Nil Target

Causes an object to forget whatever ship it had automatically targeted. Used to prevent strange behavior when ships are moved "unnaturally."

### Disable Keys

For the tutorial only. Turns keys off so that player cannot use them.

> #### Which Keys

> Which keys to disable.

### Enable Keys

For the tutorial only. Turns keys on the the player can use them.

> #### Which Keys

> Which keys to enable.

### Set Zoom Level

For the tutorial only. Sets the zoom level.

> #### Zoom Level

> Which zoom level.

### Set Computer Selection

For the tutorial only. Automatically selects a page and line number on the ship's computer.

> #### Computer Screen

> Which screen to select.

> #### Line Number

> Which line to select.

### Assume Initial

Causes an arbitrary direct object which was not originally an initial object to assume an initial object index. Created for the tutorial, but may have other applications.

> #### Initial Object Number

> The initial object index to assume.