View source for Version-specific commenting

'''Version-specific commenting''' is a FSO feature, added in version 3.6.8, that can be used in missions and tables.  This feature allows text data to be enabled or disabled depending on the version of FSO being run.

==Standard Usage==
Standard comments in text files parsed by FSO are prefixed with a semicolon <code>;</code> or two slashes <code>//</code>, and multiline comments are surrounded by C-style tokens <code>/* */</code> or a similar <code>!* *!</code>.  But comments adhering to the version-specific format are handled differently.


A comment with the format <code>;;FSO 3.6.8;;</code>, where 3.6.8 is any version number, will cause the rest of the line to be ignored in versions below the specified one, but allowed in versions above the specified one.  Also, since a single semicolon is a regular comment in retail FS2, version-specific comments will automatically be ignored in retail.

Here is an example from Axem's PromptBox script:
<pre>;;FSO 3.8.0;; self.SDL2 = true</pre>
In version 3.8.0 and later, this line will be treated as if it said
<pre>self.SDL2 = true</pre>
while in versions prior to 3.8.0, this line will be treated as if it were a comment.


The version string can accept from one to four numbers.  Here is another example from PromptBox with all four:
<pre>;;FSO 3.8.1.20180119;; mn.LuaSEXPs["lua-clear-prompt"].Action = function(reference) PromptBox:ResetRef(reference) end</pre>
Scripted SEXPs were added in the 20180119 nightly build, so this line connects the <code>PromptBox:ResetRef</code> function to the scripted SEXP starting with that build.


Any number of lines can be prefixed with a version-specific comment to enable features only available in certain builds.  This example from "Eve of Destruction" in the FreeSpace Port enables a ship nameplate in versions starting with 3.6.8:
<pre>;;FSO 3.6.8;; $Texture Replace:
;;FSO 3.6.8;; +old: nameplate
;;FSO 3.6.8;; +new: GTC_Orff</pre>

==Advanced Usage==
As of version 3.7.2 RC1, version-specific comments can be used in combination with <code>!* *!</code> block comments to ''disable'' a feature starting from a certain version.  This works because the regular block comment is enabled or ignored depending on the preceding standard version-specific comment.

Here is an example from "Expedition" in ''The Scroll of Atankharzim'' that uses the newer <code>jettison-cargo</code> SEXP operator on builds that support it and the original <code>jettison-cargo-delay</code> operator on builds that don't:
<pre>;;FSO 3.8.0;;   ( jettison-cargo "Molech" ) 
;;FSO 3.8.0;;   ( jettison-cargo "Ba'al" ) 
;;FSO 3.8.0;; !*
   ( jettison-cargo-delay "Molech" 0 ) 
   ( jettison-cargo-delay "Ba'al" 0 ) 
;;FSO 3.8.0;; *!</pre>

==Here Be Dragons==
The "Here Be Dragons" save format in FRED will save a mission in a format that can be loaded by retail'''*''', with the FSO-specific features guarded by version-specific comments.  The FreeSpace Port makes extensive use of this technique to allow missions to be loaded by retail FS2, while still retaining features (such as FS1 music and wing-specific squadron logos) that require FSO.

'''*''' Approximately.  Lines in the mission file that are unambiguously written by FRED_Open but not written by retail FRED will be controlled as expected; but more subtle differences will not.  For example, SEXP operators that are only available in FSO will still be written, because the general SEXP format is compatible with retail FS2, even though specific SEXP operators are not.

==Important Note==
FRED's support for version-specific comments is limited to what it specifically knows about.  If version-specific comments are used in any place other than the Here Be Dragons lines, the mission will be scrambled if it is loaded in FRED and saved again.  The feature can be useful to enable or disable events depending on the FSO version -- see the "Expedition" example above, or the FreeSpace Port version of "Playing Judas" -- but this requires the version-specific comments to be added in a text editor, and any future mission edits must also be done in a text editor.

==Related Links==
*'''Forum thread: [https://www.hard-light.net/forums/index.php?topic=38294.0 New mini-feature: Version-specific commenting]'''

[[Category:Tables]]