Transcendence Community Wiki

<MissionType> defines the properties and behavior of a type of mission, represented as a mission object. The relationship between a MissionType and a mission object is similar to that between a StationType and a station object. A MissionType is like a template for a mission object; multiple mission objects may be instantiated per MissionType.

A mission object contains all of the state for a mission, including the goals of the mission, the player's state with respect to the mission, and any temporary data needed about the mission. For example, imagine a mission to destroy an enemy station. The mission object stores a reference to the station to be destroyed, the state of the player (such as whether he or she has accepted the mission), and data such as the reward to offer if the player completes the mission.

To create a mission, the developer should call msnCreate with the UNID of the MissionType to create and the owner object. Missions are generally associated with an owner object (such as a station) which gives the mission and the reward on completion. When created, the OnCreate event is called on the MissionType. The event should gather all the information necessary to describe the mission (for example, it may pick a target for the mission) and store information as data in the mission object. If for some reason, the mission cannot be created (e.g., imagine that a proper target could not be found), the code should call msnDestroy inside of OnCreate. You may also register notification events with functions such as msnRegisterForEvents, msnAddTimerEvent, and msnAddRecurringTimerEvent. These functions work on any mission, even on those that are already completed.

When first created, a mission is open. An open mission is a mission that has been defined (e.g., a target has been chosen) and is available for the player to accept. You may obtain a list of open mission with the msnFind function. For example:

(msnFind gSource "oS") -> list of all open mission objects owned by gSource.

To show an open mission to the player, show the mission screen with the following code:

(scrShowScreen gScreen &dsRPGMission; { missionObj: theMission })

Where theMission is a mission object returned by msnFind or by msnCreate. The screen will describe the mission to the player and ask them to Accept or Decline the mission. The screen will call msnAccept if the player accepts the mission and msnDecline is the player declines it.

If the player accepts the mission, the mission's OnAccepted event is called, followed by OnStarted. If the player declines the mission, the OnDeclined event is called (but not OnStarted). The player may decline the mission any number of times. Once the mission is accepted, however, the player cannot decline it.

In certain cases you may want a mission to proceed without the player. In that case, you may call msnSetUnavailable. msnSetUnavailable may only be called when a mission is open; it calls OnStarted and removes it from the list of open missions. Once unavailable, a mission cannot be accepted by the player.

Use the OnStarted event to begin mission actions that should only happen after the mission is running (either because the player accepted or because the mission started without the player). For example, in an escort mission, a freighter might leave the station in the OnStarted event.

The OnSetPlayerTarget event is called at various points to allow the mission to set ship orders for the player. The event is called when the player accepts a mission, when the player completes a mission, and after the player is debriefed (to allow you to cancel orders). This event is also called when the player enters a system.

If a mission succeeds (e.g., the target was destroyed) you should call the msnSuccess function. This will call the OnCompleted event, which you may use to clean up the mission, if necessary. If a mission fails, you should call the msnFailure function, which also calls OnCompleted. Note that the engine automatically unregisters all events and timers after a mission has completed.

If a mission has completed but the player has not yet been debriefed, docking with the mission owner station will automatically bring up the dsRPGMission screen and debrief the player. The OnReward event will be triggered, which allows you to (e.g.) pay the player for completing the mission.

Unlike other kinds of objects, mission objects are not tied to a system. They are valid and can be accessed in any system. Because of this, you must exercise caution in storing system objects in mission objects. Note that missions objects that have been accepted by the player are never destroyed. They are kept around as a record of missions completed.

UNID= The UNID of this type.

name= The name of the mission. This is used for development purposes to identify the mission type; it is not displayed to players.

debriefAfterOutOfSystem= If set to true then the mission completes if the player leaves the original system. [apiVersion 14]

expireTime= The optional parameter specifies the time (in ticks) that the mission should be remain open before it is accepted. If the time expires without the mission being accepted, then the mission is destroyed. By default there is no expiration time. [apiVersion 13]

failureAfterOutOfSystem= This optional parameter specifies that the mission should fail after the given number of ticks spent outside the original mission system. For example, specifying 1,800 for this parameter causes the mission to fail if the player leaves the system and doesn't return for 1,800 ticks (one real minute). By default, a mission does not fail when leaving the system. [apiVersion 13]

forceUndockAfterDebrief= Optional, false by default. If set to true, the player is forced to undock after the debrief screen is shown.

level= If present, this represents the system level(s) for which the mission is appropriate. You may specify either a single number or a range (e.g., “1-5”). This value is used when looking for missions using typFind; that is, you may use level queries in typFind to select missions of a given level. [apiVersion 23]

maxAppearing= If present, this is a dice range indicating the maximum number of times the mission can be encountered by the player. For example, a value of “1” means that the mission is unique in a game. If omitted, there is no limit to the number of times the mission may be created. [apiVersion 14]

noDebrief= If set to true then the mission completes after a call to msnSuccess or msnFailure. That is, there is no need to call msnReward or msnSetProperty (to set the debriefed flag). Use this option when the player does not need to return to the original station that gave out the mission. [apiVersion 13]

NoDecline= If set to true then the player cannot decline the mission.

noFailureOnOwnerDestroyed= If set to true then the mission continues even if the object that issued the mission is destroyed.

noStats= If set to true then the mission is not included in global counts (such as the number of missions completed). [apiVersion 14]

priority= The priority of the mission relative to other missions. When creating a new mission with msnCreate, the list of missions is ordered by priority, so that higher priority missions are considered first. Missions with the same priority are randomly ordered. The default priority is 1. [apiVersion 13]

A mission object has the following events:

• gSource: The mission object.

This is called when the player accepts a mission, generally through a call to msnAccept. The mission is already running (OnStarted has already been called) by the time this event is called.

• gSource: The mission object.
• aDockTarget: The object that we were docked with.

This is called when the player undocks from the station after accepting a mission. [apiVersion 22]

• gSource: The misison object.

This event is called after the mission is complete (with a call to msnSuccess or msnFailure), when the player returns to the original station to get a debrief on the mission. The event may return Nil, in which case the debrief proceeds as normal.

If the event returns a string, the string is display to the user in a dock screen and the player is forced to undock. This is useful in cases where something else has to happen before a debrief can happen (e.g., maybe we need to wait for a ship to reach a certain point). [apiVersion 22]

• gSource: The mission object.
• gData: Arbitrary data passed in to msnSuccess or msnFailure.
• aReason: A reason code. Either success or failure.

This is called when a mission completes (either successfully or otherwise).

• gSource: The mission object.
• gData: Arbitrary data passed in from msnCreate.
• aOwnerObj: The object that issued the mission (may be Nil).

OnCreate is called when the mission object is created. This adds the mission to the list of available (open) missions but it does not necessarily start the mission.

The script inside OnCreate may call msnDestroy to abort creation of the mission, for example, if the mission is no longer available for some reason.

NOTE: The semantics of this event are that the mission is available; the mission has not necessarily started. For example, in a timed mission (in which the player has a certain amount of time to complete the mission) the clock should not start until <OnStarted>.

• gSource: The mission object.

This event is called after the player debriefs and then undocks. [apiVersion 22]

• gSource: The mission object.

OnDeclined is called when the mission is declined by the player.

• gSource: The mission object.

Called when the mission is destroyed.

• gSource: The mission object.
• aScreenType: The screen that we are asking about.

This event allows a mission to override certain screens with dsRPGMission. For a given screen type, the even should return a structure containing a nextScreen field, indicated the screen UNID to show. An optional nextScreenData field can be used to pass data to the new screen.

The following screen types are defined:

• AcceptFollowUp: After the player accepts the mission, we can optionally show a screen (instead of undocking).
• DeclineFollowUp: After the player declines the mission, we can optionally show a screen.
• FailureFollowUp: After the mission failure debrief, we can optionally show a screen.
• SuccessFollowUp: After the mission success debrief, we can optionally show a screen.

This event is implemented in [apiVersion 23] and above.

• gSource: The mission object.

This is called right before generating the “InProgress” language text. This allows you to modify some state, if necessary before generating the text. [apiVersion 22]

• gSource: The mission object.

This event is called after gets the InProgress text and after the player undocks. [apiVersion 22]

• gSource: The mission object.
• gData: Arbitrary data passed in to msnReward.

Called after a successful mission to reward the player (via msnReward).

• gSource: The mission object.
• aReason: A code indicating why this event was raised.

This is called to refresh the player's target. It is always called right after the player accepts a mission, but it may be called at other times.

Valid reason codes are:

• accepted: The mission has been accepted by the player. We should set the target appropriately.
• debriefed: The player has been debriefed; we can clear the target.
• failure: The mission has failed. We can clear the target or set it to the debriefing point.
• inProgress: The player visited the original mission station while the mission is in progress. It's a good idea to refresh the target at this point, in case the player lost it.
• newSystem: The player has entered a new system. We can clear the target (or perhaps set the target to the proper stargate).
• success: The mission has succeeded. We can clear the target or set it to the debriefing point.

• gSource: The mission object.

This is called when a mission starts running, either because the player accepted the mission or because the mission started without the player (by calling msnSetUnavailable).

The text used to describe a mission and to brief and debrief the player is contained in Language elements in the mission type. The following language IDs are used:

• id=“Name” : This should return the name of the mission. This is evaluated when the mission is accepted.
• id=“Summary” : This should return a string summarizing the mission. This is evaluated when the mission is accepted.
• id=“Intro” : This text is displayed the first time the player hears about the mission. The language element may be a single string or a list of string. In the latter case, each string in the list is shown in its own page.
• id=“Briefing” : This text is displayed after the Intro and any subsequent time that the player requests the mission. Like Intro, this may also return a list of strings.
• id=“AcceptReply : This is the text to show when the player accepts the mission.
• id=“DeclineReply : This is the text to show when the player declines the mission.
• id=“InProgress : This text is shown if the player docks with the owner while the mission is in progress.
• id=“SuccessMsg : This is the message shown on the HUD when the mission succeeds. It defaults to “Mission complete!”
• id=“FailureMsg : This message is shown on the HUD if the mission fails. It default to “Mission failure”
• id=“SuccessDebrief : This text is shown to debrief a successful mission.
• id=“FailureDebrief : This text is shown to debrief a failed mission.
• id=“AlreadyDebriefed : This text is shown if the player returns after a mission has already been debriefed.
• id=“Unavailable : This text is shown if the player requests a mission after it has already started without the player.

Mission Functions

Design Types