Transcendence Community Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
Discuss this page on this pages [[shpOrder Talk Page|TalkPage]]

=== shpOrder ===

See [[http://xelerus.de/index.php?s=functions&function=208|shpOrder at Xelerus]]

^ Syntax | (shpOrder ship string [expression]) |
^ Arguments | ship: The ship that you want to order. |
^ | string: A string representing the order. |
^ | expression: The optional arguments if needed by the order. Multiple arguments possible|
^ Returns | condition: True if successful, Nil otherwise. |
^ Category | [[orders]], [[ship]] |
^ Description | Gives the ship the order. |

  * **shpOrder**
    * **ship**
      * **order**
        * **"guard"**: Ship docks with a target and fights enemies that attack or come near the target. Ship gives up attacking an enemy if it is no longer detectable to the target. Ship is considered a subordinate of **target**. Order ends if **target** is destroyed.
          * SpaceObject: **target**
        * **"sentry"**: Similar to **guard** but makes the ship hold at its current position and has a duration. Usually given to ships that rotate but do not thrust (such as turrets). Ship is considered a subordinate of **target**. Order ends if **target** is destroyed.
          * SpaceObject: **target**
          * Integer: Duration in seconds; indefinite by default.
        * **"dock"**: Ship attempts to dock with a target. If no docking ports are available, ship will move back and forth over the target until a port is available.
          * SpaceObject: **target**
        * **"attack"**: Ship fires its weapons against a target for a specified duration or until the target is destroyed.
          * SpaceObject: **target**
          * [Integer]: Duration in seconds; indefinite by default
        * **"wait"**: Ship does absolutely nothing for a specified duration.
          * [Integer]: Duration in seconds; indefinite by default
        * **"gate"**: Ship attempts to leave the system through an object (typically a stargate).
          * SpaceObject (does not need to be a stargate): **target**
        * **"gateOnThreat"**: Ship **wait**s until it is attacked and then attempts to leave the system. This order usually comes after a **dock** order. Ship is considered a subordinate of the object it is docked at.
        * **"gateOnStationDestroyed"**: Ship **wait**s until a station is destroyed and then attempts to leave the system. This order usually comes after a **dock** order. Ship is considered a subordinate of the object it is docked at.
        * **"patrol"**: Ship **orbit**s the target at a specified distance and fights enemies that attack or come near the target. Ship gives up fighting an enemy if it is no longer detectable by the target. Ship is considered a subordinate of **target**. Order ends if the **target** is destroyed.
          * SpaceObject: **target**
          * [Integer]: **distance** in light-seconds at which to orbit the target.
        * **"escort"**: Ship **follow**s a target, fighting enemies that attack or come near the target.  Ship gives up fighting an enemy if it is no longer detectable by the target.
          * SpaceObject: **target**
          * [Integer]: **angle** or **formation**
          * [Integer]: **distance**
        * **"scavenge"**: Ship **wanders** around system until there is a wreck with items in it, at which point the ship will **loot** the wreck. Does not retaliate if the wreck is destroyed.
        * **"followPlayerThroughGate"**: Cannot be given by **shpOrder**; returned by the event **OnPlayerLeftSystem** as **"followPlayer"**. Ship follows the player through the nearest gate.
          * SpaceObject: **target**
        * **"attackNearestEnemy"**: Attack the nearest enemy at the time that this order is assigned.
        * **"tradeRoute"**
        * **"wander"**: Ship follows a diamond-like path around the system, fighting enemies that attack it
        * **"loot"**: Ship takes all items from the target after a few seconds, ignoring cargo space. Ship does not retaliate to attacks while looting. Does not retaliate if target is destroyed.
          * SpaceObject: **target**
        * **"hold"**: Ship brakes and attempts to stay at its current position, attacking nearby enemies
          * Integer: **duration** in seconds
        * **"mine"**: Ship mines asteroids in the system. Ship is considered a subordinate of the **base**.
          * SpaceObject: **base** object that the ship is working for.
        * **"waitForPlayer"**: Cannot be given by **shpOrder**; returned by the event **OnPlayerLeftSystem**. Ship waits for the player to return to the system.
        * **"attackPlayerOnReturn"**: Usually given during the **OnPlayerLeftSystem** event. Ship will attack player upon gating back into the system.
        * **"follow"**: Ship follows a target, staying at a position relative to the target and matching the target's direction.
          * SpaceObject: **target**
          * Integer: Angle in degrees
          * Integer: Distance in light-seconds
        * **"navPath"**
          * ?: **navID**
        * **"goto"**: 
          * SpaceObject: **destination**
          * Integer: **distance**
        * **"waitForTarget"**: Ship waits until a target approaches a certain distance or until a certain amount of time passes.
          * SpaceObject: **target** to wait for.
          * Integer: **distance** from the target in light-seconds, defaults to detection range.
          * Integer: **duration** in seconds until the wait ends; indefinite by default.
        * **"waitForEnemy"**: Ship waits until it detects an enemy
          * Integer: **duration** in seconds until the wait ends; indefinite by default.
        * **"bombard"**: Orders a ship to **attack** a station
          * SpaceObject (must be a station): **target**
          * Integer: **duration** in seconds that the ship will spend bombarding
        * **"approach"**: Ship approaches a target until a certain distance
          * SpaceObject: **target**
          * Integer: **distance** in light-seconds
        * **"aim"**: Ship aims at a target without firing weapons
          * SpaceObject: **target**
        * **"orbit"**: Ship moves clockwise in a circular path around the target at a specified distance for a specified duration
          * SpaceObject: **target**
          * Integer: **distance** in light-seconds
          * Integer: **duration** in seconds
        * **"holdCourse"**: Ship travels in a specified direction for a specified distance.
          * Integer: **angle** (absolute) in degrees
          * Integer: **distance** in light-seconds
        * **"turnTo"**: Ship turns until its rotation matches a given angle.
          * Distance: **angle** (absolute) in degrees
        * **"attackHold"**: Ship attacks a specified target for a specified duration while trying to stay at its current position.
          * SpaceObject: **target**
          * Integer: **duration** in seconds; indefinite by default.
        * **"attackStation"**:
          * SpaceObject: **target**
          * [?]: **unknown**
        * **"fireEvent"**: Fires the event on the target's event handler. **aShipObj** is the ship that fired it.
          * SpaceObject: **target**
          * String: **event** to fire
        * **"waitForUndock"**: Ship waits until the **target** undocks or the **duration** passes.
          * SpaceObject: **target**
          * Integer: **duration** in seconds
        * **"sendMessage"**: Ship sends a **message** to a **target**. If the **target** is the player ship, then the message displays on the screen. Otherwise, nothing useful happens.
          * SpaceObject: **target**
          * String: **message**
        * **"attackArea"**: Ship attacks all enemies that are within a specified distance of a specified object for a specified time, probably in random order<sup>verify</sup>
          * SpaceObject: **target**
          * Integer: **distance** in light-seconds
          * [Integer]: **time** in seconds; indefinite by default.
        * **"holdAndAttack"**: Same as **attackHold**
          * SpaceObject: **target** to attack
          * Integer: **duration** in seconds
        * **"gotoPos"**: Ship moves to the specified position.
          * Position: **destination**
        * **"waitForThreat"**: Ship waits until it detects an enemy or the **duration** passes.
          * Integer: **duration** in seconds
=== Example ===

<code lisp>
	(shpOrder
		(random (sysFindObject Nil "s A"))
		'gate
		(random (sysFindObject Nil "G A"))
		)
</code>

Orders a random ship in the system to exit through a random gate as soon as all its orders are done.

Return to [[:Functions]] list