Rewards: Difference between revisions

From FSDeveloper Wiki
Jump to navigationJump to search
m (Replaced Applicable-FSVersion for MSFS with MSFS2020, added MSFS2024)
 
(21 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Infobox-Applicable-FSVersion
| MSFS2024 = unknown
| MSFS2020 = unknown
| FSXI = unknown
| P3D5 = unknown
| P3D4 = unknown
| P3D3 = unknown
| P3D2 = unknown
| P3D = unknown
| FSW = unknown
| FSXSE = true
| FSXA = true
| FSX = true
| FS2004 = unknown
| FS2002 = unknown
| XP11 = unknown
| XP10 = unknown
| XP9 = unknown
}}
Pilots earn Rewards for completing various missions, and reaching specific accomplishments throughout the game, (in 'Free Flight').
Pilots earn Rewards for completing various missions, and reaching specific accomplishments throughout the game, (in 'Free Flight').


Line 11: Line 31:


=== Missions ===
=== Missions ===
In a mission, a reward can be granted explicitly using a [[Function_Reference#Grant_Reward_Action|GrantRewardAction]]. This gives you fine control over exactly what requirements the reward has. For mission-based rewards you shouldn't define Criteria because FSX will pick that up and possibly grant the reward outside the mission.
In a mission, a reward can be granted explicitly using a [[Function_Reference#Grant_Reward_Action|GrantRewardAction]]. This gives you fine control over exactly what requirements the reward has.  
 
For mission-based rewards you shouldn't define Criteria because FSX will pick that up and possibly grant the reward outside the mission, (unless that criteria is for having completed another mission).


== Creation ==
== Creation ==
Like the other mission elements, Rewards are created as an XML file. Unlike the others, they must be [[Compiling|compiled]] before they can be used.  
Like the other mission elements, Rewards are created as an XML file. Unlike the others, they must be [[Compiling|compiled]] before they can be used.  
'''Notes'''
<br>
To create/edit an XML file, you must use a ''pure'' text-editor, e.g. Notepad
You '''must not''' use a wordprocessor, e.g. Wordpad, Word, etc., as these insert control/formatting characters into the xml.
See Tools section below.


=== Example XML ===
=== Example XML ===
Line 34: Line 64:


As with all other XML, it is very sensitive and removing any symbols, or changing the case of the keywords, will break it. You should be able to see which bits have to be changed though.
As with all other XML, it is very sensitive and removing any symbols, or changing the case of the keywords, will break it. You should be able to see which bits have to be changed though.
'''Notes'''
<br>
Field values are wrapped in double-quote characters.
<br>
Field values must not include -
* Additional double-quote " characters within your text. Instead use single-quotes ' characters.
** Incorrect - description="Thank you for visiting the home town of Virgil '''"'''Gus'''"''' Grissom, Mitchell, IN, 6.5 NM south of KBFR".
** Correct &nbsp;&nbsp;- description="Thank you for visiting the home town of Virgil 'Gus' Grissom, Mitchell, IN, 6.5 NM south of KBFR".
* The ampersand character &amp;. Instead use the word 'and'.
** Incorrect - name="Ben &amp; Jerry's"
** Correct &nbsp;&nbsp;- name="Ben and Jerry's"
* Extra spaces prefixing or suffixing filenames.
** Incorrect - rewardDetailBitmap=" Grissom_large.bmp "
** Correct &nbsp;&nbsp;- rewardDetailBitmap="Grissom_large.bmp"
* Extra characters in ICAO fields.
** Incorrect - RewardAirport ident="(KBFM)"
** Correct &nbsp;&nbsp;- RewardAirport ident="KBFM"


=== GUID ===
=== GUID ===
The rewardID is a GUID (unique identifier) which you will need to generate using GUIDGen.exe or at http://www.guidgen.com . <code>name</code> and <code>description</code> are free text.  
The <code>rewardId</code> is a GUID (unique identifier), <code>name</code> and <code>description</code> are free text.
 
Create the GUID using -
* [[http://www.guidgen.com GuidGen.com]] - An online GUID generator.
* [[http://www.microsoft.com/downloads/details.aspx?familyid=94551f58-484f-4a8c-bb39-adb270833afc&displaylang=en GUIDGen.EXE]] - A downloadable GUID generator.
Recommend the latter, it's part of several MS SDKs, but available standalone for Exchange.


=== Type ===
=== Type ===
Line 48: Line 101:


=== Bitmaps ===
=== Bitmaps ===
Finally, the two <code>bitmap</code> elements must point to images, either JPG or BMP, which show small and detailed icons for your new reward. The <code>bitmap</code> image is the small icon, at 100x80 pixels; the <code>rewardDetailBitmap</code> image is larger at 300x370, and is shown as part of the more detailed information.
Finally, the two <code>bitmap</code> elements must point to images, either JPG or BMP, which show small and detailed icons for your new reward.  
<br>
The <code>bitmap</code> image is the small icon, at 100 x 80 pixels, (wide x high),
<br>
the <code>rewardDetailBitmap</code> image is larger at 300 x 370 pixels, (wide x high), and is shown as part of the more detailed information.
 
If creating a large number of rewards, recommend using jpgs rather than bmps.
<br>
Example - For a file comprising 250 rewards, the resulting compiled reward file for -
* BMPs - Was a ludicrously large 91 MB.
* JPGs - Was less than 4 MB.


=== Criteria ===
=== Criteria ===
There are a few different criteria you can set. Filtering by the number of hours the player has flown in a particular aircraft type is done with a <code>RewardHours</code> element and can be one of the following:
There are a few different criteria you can set.  
 
==== RewardHours ====
Filtering by the number of hours the player has flown in a particular aircraft type is done with a <code>RewardHours</code> element and can be one of the following:
* ANY
* ANY
* DAY
* DAY
Line 68: Line 134:
</pre>
</pre>


==== RewardAirport ====
Filtering by the airports the player has been to is done using a <code>RewardAirport</code> element. You need to specify the four-letter airport code rather than the name.
Filtering by the airports the player has been to is done using a <code>RewardAirport</code> element. You need to specify the four-letter airport code rather than the name.


This would allow FSX to grant the reward after the player has visited Heathrow:
This would allow FSX to grant the reward after the player has landed at Heathrow:
<pre>
<pre>
<RewardAirport ident="EGLL" />
<RewardAirport ident="EGLL" />
</pre>
</pre>


==== DependantRewardId  ====
Finally, you can make a reward dependent on the player having already achieved another reward.
Finally, you can make a reward dependent on the player having already achieved another reward.
<pre>
<pre>
Line 88: Line 156:
   >
   >
</pre>
</pre>
... which would mean that FSX would automatically grant this reward after the player has been to Heathrow, has flown for five hours at night, has already been granted another reward with a specific GUID and has made at least three landings at two different airports.
... which would mean that FSX would automatically grant this reward after the player has -
* landed at Heathrow
AND
* flown for five hours at night,  
AND
* already been granted another reward with a specific GUID  
AND
* made at least three landings at two different airports.
 
You don't need to specify all the types of criteria, only the ones you want to use.  


You don't need to specify all the types of criteria, only the ones you want to use. If you're using the reward as part of a mission, don't leave the Criteria section there, even empty, or FSX will grant the rewards automatically because it will see it has having a criteria of "0 landings at 0 different airports" - which is achieved just by running the sim.
==== NOTE ====
If you're using the reward as part of a mission, don't leave the Criteria section there, even empty,  
<br>
otherwise FSX will grant the rewards automatically because it will see it has having a criteria of "0 landings at 0 different airports" -  
<br>
which is achieved just by running the sim.
 
== To Sort ==
Data type & size to be incorporated
<pre>
    <xs:attribute name="rewardId" form="unqualified" type="stGuid" use="required" />
    <xs:attribute name="type" form="unqualified" type="stReward" use="required" />
    <xs:attribute name="name" form="unqualified" type="stString48" />
    <xs:attribute name="description" form="unqualified" type="stString1024" />
    <xs:attribute name="bitmap" form="unqualified" type="stString1024" use="required" />
    <xs:attribute name="rewardDetailBitmap" form="unqualified" type="stString1024" use="optional" />
    <xs:attribute name="rewardDetailDescription" form="unqualified" type="stString1024" use="optional" />
</pre>
 
It's not the logbook file, it's grantedrewards.bin
<br>
Both are re-read on flight completion.
 
 
No GrantReward call is required.
 
 
The GUID is essential,
<br>
it's whats stored in the grantedrewards.bin,
<br>
this is compared against the content of rewards folder.
 
 
Achieved reward's images are held within the .rwd file,
<br>
and displayed conditional to GUIDs stored in grantedrewards.bin.
<br>
Removing a .rwd file will cause non-display of that image.
 
 
Recompiling the reward with a different GUID, will allow you to re-earn the reward.
 
 
CRITERIA are AND only.
<br>
OR can be achieved within mission logic goals.


== Tools ==
== Tools ==
Line 164: Line 287:
=== Internal ===
=== Internal ===
[[Compiling#Running_the_Reward_Compiler|Compiling Rewards]] - Compilation of a reward xml file.
[[Compiling#Running_the_Reward_Compiler|Compiling Rewards]] - Compilation of a reward xml file.
{{Template:Navbox-Missions-ObjRef}}


=== External ===
=== External ===
{{:Transclusion-Missions-Links-External-Common}}
{{:Transclusion-Missions-Links-External-Common}}


== Reference ==
=== Reference ===


[[Category:Missions]]
[[Category:Missions]]

Latest revision as of 15:18, 25 May 2024

Pilots earn Rewards for completing various missions, and reaching specific accomplishments throughout the game, (in 'Free Flight').

Some of these rewards exist as hidden Easter Eggs to be discovered by pilots. Some missions have multiple and hidden rewards, receipt being dependent on performing additional actions.

Achieved rewards are viewable in the user's pilot records.

Available In

Free Flight

FSX comes with some rewards which you've probably seen, for things like your first landing and first ten landings. These rewards are obviously not granted explicitly by a mission action, so how do they work?

Each 'free flight' reward needs to have an additional section added to it's definition, the 'Criteria'. These are detailed in the SDK and cover things like the number of landings, types of aircraft flown and airports landed at. You can combine these in any way you like to come up with your specific criteria. When the sim detects that each of the requirements has been met, your reward is granted.

Missions

In a mission, a reward can be granted explicitly using a GrantRewardAction. This gives you fine control over exactly what requirements the reward has.

For mission-based rewards you shouldn't define Criteria because FSX will pick that up and possibly grant the reward outside the mission, (unless that criteria is for having completed another mission).

Creation

Like the other mission elements, Rewards are created as an XML file. Unlike the others, they must be compiled before they can be used.

Notes
To create/edit an XML file, you must use a pure text-editor, e.g. Notepad

You must not use a wordprocessor, e.g. Wordpad, Word, etc., as these insert control/formatting characters into the xml.

See Tools section below.

Example XML

The XML file looks like this: 

<FSData version="9.0">
  <Reward    rewardId = "{00000000-0000-0000-0000-000000000000}"
                 name = "Demo Reward"
          description = "Postcard for doing something right"
                 type = "POSTCARD"
               bitmap = "Images\small-1.jpg" 
   rewardDetailBitmap = "Images\big-1.jpg"
  >
   <Criteria landings="3" differentAirports="2"/>
  </Reward>
</FSData>

As with all other XML, it is very sensitive and removing any symbols, or changing the case of the keywords, will break it. You should be able to see which bits have to be changed though.

Notes
Field values are wrapped in double-quote characters.
Field values must not include -

  • Additional double-quote " characters within your text. Instead use single-quotes ' characters.
    • Incorrect - description="Thank you for visiting the home town of Virgil "Gus" Grissom, Mitchell, IN, 6.5 NM south of KBFR".
    • Correct   - description="Thank you for visiting the home town of Virgil 'Gus' Grissom, Mitchell, IN, 6.5 NM south of KBFR".
  • The ampersand character &. Instead use the word 'and'.
    • Incorrect - name="Ben & Jerry's"
    • Correct   - name="Ben and Jerry's"
  • Extra spaces prefixing or suffixing filenames.
    • Incorrect - rewardDetailBitmap=" Grissom_large.bmp "
    • Correct   - rewardDetailBitmap="Grissom_large.bmp"
  • Extra characters in ICAO fields.
    • Incorrect - RewardAirport ident="(KBFM)"
    • Correct   - RewardAirport ident="KBFM"

GUID

The rewardId is a GUID (unique identifier), name and description are free text.

Create the GUID using -

Recommend the latter, it's part of several MS SDKs, but available standalone for Exchange.

Type

The type element must be one of this list:

  • TROPHY
  • BADGE
  • CERTIFICATE
  • MEDAL
  • POSTCARD
  • SPECIAL_ITEM

Bitmaps

Finally, the two bitmap elements must point to images, either JPG or BMP, which show small and detailed icons for your new reward.
The bitmap image is the small icon, at 100 x 80 pixels, (wide x high),
the rewardDetailBitmap image is larger at 300 x 370 pixels, (wide x high), and is shown as part of the more detailed information.

If creating a large number of rewards, recommend using jpgs rather than bmps.
Example - For a file comprising 250 rewards, the resulting compiled reward file for -

  • BMPs - Was a ludicrously large 91 MB.
  • JPGs - Was less than 4 MB.

Criteria

There are a few different criteria you can set.

RewardHours

Filtering by the number of hours the player has flown in a particular aircraft type is done with a RewardHours element and can be one of the following:

  • ANY
  • DAY
  • NIGHT
  • VFR
  • IFR
  • SAILPLANE
  • LANDPLANE
  • SEAPLANE
  • ROTORCRAFT
  • MULTI_ENGINE

For example, to grant a reward after the player has flown five hours at night: 

<RewardHours hoursType="NIGHT" hours="5.0" />

RewardAirport

Filtering by the airports the player has been to is done using a RewardAirport element. You need to specify the four-letter airport code rather than the name.

This would allow FSX to grant the reward after the player has landed at Heathrow: 

<RewardAirport ident="EGLL" />

DependantRewardId

Finally, you can make a reward dependent on the player having already achieved another reward. 

<DependantRewardId rewardId="{a guid}" />

An entire Criteria section may look something like this: 

  <Criteria landings="3" differentAirports="2"
    <RewardHours hoursType="NIGHT" hours="5.0" />
    <RewardAirport ident="EGLL" />
    <DependantRewardId rewardId="{a guid}" />
  >

... which would mean that FSX would automatically grant this reward after the player has -

  • landed at Heathrow

AND

  • flown for five hours at night,

AND

  • already been granted another reward with a specific GUID

AND

  • made at least three landings at two different airports.

You don't need to specify all the types of criteria, only the ones you want to use.

NOTE

If you're using the reward as part of a mission, don't leave the Criteria section there, even empty,
otherwise FSX will grant the rewards automatically because it will see it has having a criteria of "0 landings at 0 different airports" -
which is achieved just by running the sim.

To Sort

Data type & size to be incorporated 

    <xs:attribute name="rewardId" form="unqualified" type="stGuid" use="required" />
    <xs:attribute name="type" form="unqualified" type="stReward" use="required" />
    <xs:attribute name="name" form="unqualified" type="stString48" />
    <xs:attribute name="description" form="unqualified" type="stString1024" />
    <xs:attribute name="bitmap" form="unqualified" type="stString1024" use="required" />
    <xs:attribute name="rewardDetailBitmap" form="unqualified" type="stString1024" use="optional" />
    <xs:attribute name="rewardDetailDescription" form="unqualified" type="stString1024" use="optional" />

It's not the logbook file, it's grantedrewards.bin
Both are re-read on flight completion.


No GrantReward call is required.


The GUID is essential,
it's whats stored in the grantedrewards.bin,
this is compared against the content of rewards folder.


Achieved reward's images are held within the .rwd file,
and displayed conditional to GUIDs stored in grantedrewards.bin.
Removing a .rwd file will cause non-display of that image.


Recompiling the reward with a different GUID, will allow you to re-earn the reward.


CRITERIA are AND only.
OR can be achieved within mission logic goals.

Tools

Tools overview blurb.

OS Tools

Available with the OS.

Tool Description Rating OS
Tool Name Descriptive blurb * * * * * XP
Tool Name Descriptive blurb * * * * * Vista
Tool Name Descriptive blurb * * * * * XP
Tool Name Descriptive blurb * * * * * Vista

3rd Party Tools

From 3rd party sources.

Tool Description Rating Availability URL
Tool Name Descriptive blurb * * * * * Payware Download Page (SizeMb)
Tool Name Descriptive blurb * * * * * Freeware Download Page (SizeMb)
Tool Name Descriptive blurb * * * * * Payware Download (SizeMb)
Tool Name Descriptive blurb * * * * * Freeware Download Page (SizeMb)

Related

Internal

Compiling Rewards - Compilation of a reward xml file.

External

If you haven't found what you're looking for here, then we'd recommend, (in order of preference) -

  • AVSIM - Mission downloads (newest first).

Reference

Retrieved from ‘http://www.fsdeveloper.com/wiki/index.php?title=Rewards&oldid=11950’