Transcendence Community Wiki

User Tools

Site Tools

Trace:
modding:xml:missiontype

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
modding:xml:missiontype [2014/12/27 04:40] – external edit 127.0.0.1modding: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=====
-<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.+<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. 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.
  
 ==== 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:function:msncreate|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 [[modding:function:msnRegisterForEvents]], [[modding:function:msnAddTimerEvent]], and [[modding:function: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:+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:function:msnFind]] function. For example:
  
   (msnFind gSource "oS") -> list of all open mission objects owned by gSource.   (msnFind gSource "oS") -> list of all open mission objects owned by gSource.
Line 17: Line 15:
   (scrShowScreen gScreen &dsRPGMission; { missionObj: theMission })   (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.+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 [[modding:function:msnAccept]] if the player accepts the mission and [[modding:function: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. 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.+In certain cases you may want a mission to proceed without the player. In that case, you may call [[modding:function: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. 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  all events and timers after a mission has completed.+If a mission succeeds (e.g., the target was destroyed) you should call the [[modding:function: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 [[modding:function: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. 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 45: Line 43:
  
 **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]** **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]** **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]**
Line 51: Line 51:
  
 **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]** **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.
Line 194: Line 196:
   * id="**AlreadyDebriefed** : This text is shown if the player returns after a mission has already been debriefed.   * 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.   * id="**Unavailable** : This text is shown if the player requests a mission after it has already started without the player.
 +
 +
 +==== See Also ====
 +
 +[[modding:function:mission_functions|Mission Functions]]
 +
 +[[Modding:XML:designtype:|Design Types]]
modding/xml/missiontype.1419655256.txt.gz · Last modified: 2017/01/31 22:22 (external edit)