modding:xml:missiontype
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
modding:xml:missiontype [2013/02/10 01:23] – gpm | modding:xml:missiontype [2017/02/07 01:26] (current) – [Mission Lifecycle] 0xabcdef | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | NOTE: MissionType elements were introduced in preview form in 1.08g; they will be improved an modified in 1.08h. | ||
- | |||
=====Overview===== | =====Overview===== | ||
- | < | + | < |
A mission object contains all of the state for a mission, including the goals of the mission, the player' | A mission object contains all of the state for a mission, including the goals of the mission, the player' | ||
==== Mission Lifecycle ==== | ==== Mission Lifecycle ==== | ||
- | 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]] and [[msnAddRecurringTimerEvent]]. | + | To create a mission, the developer should call [[modding: |
- | 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: | + | 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 [[modding: |
(msnFind gSource " | (msnFind gSource " | ||
Line 17: | Line 15: | ||
(scrShowScreen gScreen & | (scrShowScreen gScreen & | ||
- | Where // | + | Where // |
If the player accepts the mission, the mission' | If the player accepts the mission, the mission' | ||
- | 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, | + | In certain cases you may want a mission to proceed without the player. In that case, you may call [[modding: |
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. | 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. | ||
Line 27: | Line 25: | ||
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. | 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 | + | If a mission succeeds (e.g., the target was destroyed) you should call the [[modding: |
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. | 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. | ||
Line 37: | Line 35: | ||
**name=** The name of the mission. This is used for development purposes to identify the mission type; it is not displayed to players. | **name=** The name of the mission. This is used for development purposes to identify the mission type; it is not displayed to players. | ||
- | |||
- | **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]** | ||
=====Options===== | =====Options===== | ||
+ | |||
+ | **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]** | **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' | **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' | ||
+ | |||
+ | **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., " | ||
+ | |||
+ | **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 " | ||
+ | |||
+ | **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. | **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]** | ||
===== Events ===== | ===== Events ===== | ||
Line 56: | Line 68: | ||
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. | 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**: | ||
+ | * **aDockTarget**: | ||
+ | |||
+ | This is called when the player undocks from the station after accepting a mission. **[apiVersion 22]** | ||
+ | |||
+ | ===< | ||
+ | |||
+ | * **gSource**: | ||
+ | |||
+ | This event is called after the mission is complete (with a call to msnSuccess or msnFailure), | ||
+ | |||
+ | 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]** | ||
===< | ===< | ||
Line 74: | Line 101: | ||
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. | 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 < | ||
+ | |||
+ | ===< | ||
+ | |||
+ | * **gSource**: | ||
+ | |||
+ | This event is called after the player debriefs and then undocks. **[apiVersion 22]** | ||
===< | ===< | ||
Line 86: | Line 121: | ||
Called when the mission is destroyed. | Called when the mission is destroyed. | ||
+ | |||
+ | ===< | ||
+ | |||
+ | * **gSource**: | ||
+ | * **aScreenType**: | ||
+ | |||
+ | 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: | ||
+ | |||
+ | * // | ||
+ | * // | ||
+ | * // | ||
+ | * // | ||
+ | |||
+ | This event is implemented in **[apiVersion 23]** and above. | ||
+ | |||
+ | ===< | ||
+ | |||
+ | * **gSource**: | ||
+ | |||
+ | This is called right before generating the " | ||
+ | |||
+ | ===< | ||
+ | |||
+ | * **gSource**: | ||
+ | |||
+ | This event is called after gets the InProgress text and after the player undocks. **[apiVersion 22]** | ||
===< | ===< | ||
Line 92: | Line 155: | ||
* **gData**: Arbitrary data passed in to **msnReward**. | * **gData**: Arbitrary data passed in to **msnReward**. | ||
- | Called after a successful mission to reward the player. | + | Called after a successful mission to reward the player |
===< | ===< | ||
Line 120: | Line 183: | ||
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: | 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=" | + | |
+ | | ||
* id=" | * id=" | ||
* id=" | * id=" | ||
Line 132: | Line 196: | ||
* id=" | * id=" | ||
* id=" | * id=" | ||
+ | |||
+ | |||
+ | ==== See Also ==== | ||
+ | |||
+ | [[modding: | ||
+ | |||
+ | [[Modding: |
modding/xml/missiontype.txt · Last modified: 2017/02/07 01:26 by 0xabcdef