Difference between revisions of "FSO Installer Text Files"

From FreeSpace Wiki
Jump to: navigation, search
(→‎MULTIURL: random order)
m (→‎PATCH: clarification)
 
(11 intermediate revisions by the same user not shown)
Line 8: Line 8:
  
 
You can use the FreeSpace Open Installer itself to validate the text file for any syntactical errors.  Just run the following command at the command prompt, and select the text file with the dialog that appears:
 
You can use the FreeSpace Open Installer itself to validate the text file for any syntactical errors.  Just run the following command at the command prompt, and select the text file with the dialog that appears:
−
<pre>java -jar FreeSpaceOpenInstaller.jar validate</pre>
+
<pre>java -jar FreeSpaceOpenInstaller.jar validate [file]</pre>
 +
 
 +
You can specify the file to validate on the command line, or you can omit the file and the Installer will prompt you using a standard GUI file dialog.  You can also specify "test" instead of "validate" and the Installer will launch a special session that loads the mod repository from your file.
  
 
==Text File Specifications==
 
==Text File Specifications==
Line 30: Line 32:
 
   NAME
 
   NAME
 
   Awesome Mod
 
   Awesome Mod
 +
 
===DESC===
 
===DESC===
 
*Takes unlimited parameters.
 
*Takes unlimited parameters.
Line 38: Line 41:
 
   This mod is so awesome that it will make you weep blood.
 
   This mod is so awesome that it will make you weep blood.
 
   ENDDESC
 
   ENDDESC
 +
 
===ENDDESC===
 
===ENDDESC===
 
*Takes no parameters.
 
*Takes no parameters.
 
*Must follow the last parameter specified in a [[#DESC|DESC]].
 
*Must follow the last parameter specified in a [[#DESC|DESC]].
−
===NOTE===
 
−
*Takes unlimited parameters.
 
−
*The last parameter must be followed by an [[#ENDNOTE|ENDNOTE]].
 
−
*Is displayed to the user in the post-installation section of the installer.
 
−
'''Example'''
 
−
  NOTE
 
−
  This mod requires FSO 3.6.54
 
−
  ENDNOTE
 
  
−
===ENDNOTE===
 
−
*Takes no parameters.
 
−
*Must follow the last parameter specified in a [[#NOTE|NOTE]].
 
 
===FOLDER===
 
===FOLDER===
 
*Takes one parameter.
 
*Takes one parameter.
Line 63: Line 56:
 
   FOLDER
 
   FOLDER
 
   awesomemod_1
 
   awesomemod_1
 +
 +
===DELETE===
 +
*Takes one parameter.
 +
*Deletes a file.
 +
*Files listed must be listed in subfolders as necessary relating to the [[#FOLDER|FOLDER]] parameter specified.
 +
*Is the name of the file to delete.
 +
'''Example:''' If the [[#FOLDER|FOLDER]] is \
 +
  DELETE
 +
  awesomemod_1\awesomeOLDgraphics.vp
 +
 +
===RENAME===
 +
*Takes two parameters.
 +
*Allows renaming or moving of files.
 +
*The first parameter is the file to be renamed or moved.
 +
*The second parameter is the destination location and filename.
 +
*Only works if the destination file doesn't already exist.
 +
*Files listed must be listed in subfolders as necessary relating to the [[#FOLDER|FOLDER]] parameter specified.
 +
'''Example:''' If the [[#FOLDER|FOLDER]] is \
 +
  RENAME
 +
  awesomemod_1\awesomegraphics.vp
 +
  awesomemod_1\awesomeOLDgraphics.vp
 +
 +
===COPY===
 +
*Takes two parameters.
 +
*Allows copying files from one place to another.
 +
*The first parameter is the file to be copied.
 +
*The second parameter is the destination location and filename.
 +
*Only works if the destination file doesn't already exist.
 +
*Files listed must be listed in subfolders as necessary relating to the [[#FOLDER|FOLDER]] parameter specified.
 +
'''Example:''' If the [[#FOLDER|FOLDER]] is \
 +
  COPY
 +
  awesomemod_1\awesomegraphics.vp
 +
  awesomemod_1\awesomeOLDgraphics.vp
  
 
===URL===
 
===URL===
Line 74: Line 100:
 
   URL
 
   URL
 
   http://www.games.com/Freespace2/AwesomeModMirror
 
   http://www.games.com/Freespace2/AwesomeModMirror
 +
 
===MULTIURL===
 
===MULTIURL===
 
*Takes unlimited parameters.
 
*Takes unlimited parameters.
Line 93: Line 120:
 
*Takes no parameters.
 
*Takes no parameters.
 
*Must follow the last parameter specified in a [[#MULTIURL|MULTIURL]].
 
*Must follow the last parameter specified in a [[#MULTIURL|MULTIURL]].
−
===VERSION===
+
 
−
*Takes one parameter.
 
−
*Must be listed directly before [[#END|END]] and after all other commands and files in the section.
 
−
*Is a string that represents the version of the files in that section.
 
−
**If this parameter is changed, the installer will flag that section as outdated.
 
−
===END===
 
−
*Takes no parameters.
 
−
*Must include this command for every [[#NAME|NAME]] command.
 
−
*Signifies the end of a section.
 
 
===HASH===
 
===HASH===
 
*Takes three parameters.
 
*Takes three parameters.
Line 107: Line 126:
 
*The first parameter is the type of hash to use.
 
*The first parameter is the type of hash to use.
 
**Accepted hash types are MD5, SHA-1, or SHA-256.
 
**Accepted hash types are MD5, SHA-1, or SHA-256.
−
**This parameter must be all caps.
 
 
*The second parameter is the file to check.
 
*The second parameter is the file to check.
 
*The third parameter is the actual hash to check the file against.
 
*The third parameter is the actual hash to check the file against.
 +
**It can be upper- or lower-case.
 
*Files listed must be listed in subfolders as necessary relating to the [[#FOLDER|FOLDER]] parameter specified.
 
*Files listed must be listed in subfolders as necessary relating to the [[#FOLDER|FOLDER]] parameter specified.
 
'''Example:''' If the [[#FOLDER|FOLDER]] is \
 
'''Example:''' If the [[#FOLDER|FOLDER]] is \
Line 116: Line 135:
 
   awesomemod_1\awesomegraphics.vp
 
   awesomemod_1\awesomegraphics.vp
 
   A49767C6CD9D9A5AB157F9FF75A4D5FA
 
   A49767C6CD9D9A5AB157F9FF75A4D5FA
−
===RENAME===
+
 
−
*Takes two parameters.
+
===PATCH===
−
*Allows renaming or moving of files.
+
*Takes nine parameters, formatted like three consecutive HASH tokens.
−
*The first parameter is the file to be renamed or moved.
+
*Allows the installer to download a small binary diff and patch a mod file instead of downloading a new full version.
−
*The second parameter is the destination location and filename.
+
*The first, fourth, and seventh parameters are the type of hash to use.  (These can be different for each triplet.)
−
*Only works if the destination file doesn't already exist.
+
**Accepted hash types are MD5, SHA-1, or SHA-256.
 +
*The third, sixth, and ninth parameters are the actual hashes to check the files against.
 +
**They can be upper- or lower-case.
 +
*The second parameter is the old version of the mod file.
 +
*The fifth parameter is the binary diff file.
 +
*The eighth parameter is the new version of the mod file.
 
*Files listed must be listed in subfolders as necessary relating to the [[#FOLDER|FOLDER]] parameter specified.
 
*Files listed must be listed in subfolders as necessary relating to the [[#FOLDER|FOLDER]] parameter specified.
−
'''Example:''' If the [[#FOLDER|FOLDER]] is \
+
'''Example:'''
−
   RENAME
+
  PATCH
−
   awesomemod_1\awesomegraphics.vp
+
  MD5
−
   awesomemod_1\awesomeOLDgraphics.vp
+
  oldfile.vp
−
===DELETE===
+
  0F0F0F0F0F0F0F0F00F0F0F0F0F00F0F
 +
  SHA-1
 +
  patchFile
 +
  A49767C6CD9D9A5AB157F9FF75A4D5FA
 +
  SHA-1
 +
  newfile.vp
 +
  1A1A1A1A1A1A1A1AA1A1A1A1A1AA11A1
 +
 
 +
Binary diff files can be created using the Installer itself:
 +
<pre>java -jar FreeSpaceOpenInstaller.jar diff [algorithm] [old file] [new file]</pre>
 +
 
 +
The patch functionality can also be tested using the Installer:
 +
<pre>java -jar FreeSpaceOpenInstaller.jar patch [old file] [diff file]</pre>
 +
 
 +
If any of the "diff" or "patch" command-line parameters are not supplied, the Installer will prompt you for them using standard GUI dialogs.
 +
 
 +
===NOTE===
 +
*Takes unlimited parameters.
 +
*The last parameter must be followed by an [[#ENDNOTE|ENDNOTE]].
 +
*Is displayed to the user in the post-installation section of the installer.
 +
'''Example'''
 +
  NOTE
 +
  This mod requires FSO 3.6.54
 +
  ENDNOTE
 +
 
 +
===ENDNOTE===
 +
*Takes no parameters.
 +
*Must follow the last parameter specified in a [[#NOTE|NOTE]].
 +
 
 +
===DEPENDENCIES===
 +
*Takes unlimited parameters.
 +
*The last parameter must be followed by an [[#ENDDEPENDENCIES|ENDDEPENDENCIES]].
 +
*Contains prerequisites for the mod that are outside of the direct mod tree.  (Mods that are in a tree already require all of their ancestor mods.)
 +
*Each parameter should be the fully-qualified tree path of another mod.  A tree path is constructed by concatenating mod names in order from parent to child, with a dot or period between each mod name.
 +
*Make sure you double-check your tree path!  If the installer cannot find a dependency, it assumes all mirrors for that dependency have failed and suggests that the user not install the mod.
 +
'''Example'''
 +
  DEPENDENCIES
 +
  FSU MediaVPs, version 3.6.12
 +
   FSU MediaVPs, version 3.6.12.MV_Assets
 +
   FSU MediaVPs, version 3.6.12.MV_Effects
 +
  ENDDEPENDENCIES
 +
 
 +
===ENDDEPENDENCIES===
 +
*Takes no parameters.
 +
*Must follow the last parameter specified in a [[#DEPENDENCIES|DEPENDENCIES]].
 +
 
 +
===FLAGS===
 +
*Takes unlimited parameters, though only recognized flags are stored and duplicate flags are only stored once.
 +
*The last parameter must be followed by an [[#ENDFLAGS|ENDFLAGS]].
 +
*Contains flags for the mod that allow tweaking of installation behavior.  These are listed below.  (Currently only one flag is implemented.)
 +
*Flags are not case-sensitive.  Internally they are converted to upper-case before being stored.
 +
*'''EXCLUDE-FROM-COMPLETE-INSTALLATION''': Prevents a mod from being selected when the "Complete" installation option is chosen.  This is for mods that shouldn't be installed without the user's explicit intent, such as language packs.
 +
'''Example'''
 +
  FLAGS
 +
  EXCLUDE-FROM-COMPLETE-INSTALLATION
 +
   ENDFLAGS
 +
 
 +
===ENDFLAGS===
 +
*Takes no parameters.
 +
*Must follow the last parameter specified in a [[#FLAGS|FLAGS]].
 +
 
 +
===VERSION===
 
*Takes one parameter.
 
*Takes one parameter.
−
*Deletes a file.
+
*Is a string that represents the version of the files in that section.
−
*Files listed must be listed in subfolders as necessary relating to the [[#FOLDER|FOLDER]] parameter specified.
+
**If this parameter is changed, the installer will flag that section as outdated.
−
*Is the name of the file to delete.
+
 
−
'''Example:''' If the [[#FOLDER|FOLDER]] is \
+
===END===
−
  DELETE
+
*Takes no parameters.
−
  awesomemod_1\awesomeOLDgraphics.vp
+
*Must include this command for every [[#NAME|NAME]] command.
 +
*Signifies the end of a section.
  
 
==Example Install.txt File==
 
==Example Install.txt File==
Line 142: Line 228:
 
   This mod requires MediaVPs 3.6.12!
 
   This mod requires MediaVPs 3.6.12!
 
    
 
    
−
   The day is August 3, 2335. Thirteen months have passed since the Lucifer was destroyed, mysteriously locking the Sol system away. It's barely been two months since the Hades    superdestroyer was destroyed in orbit of Deneb, and the rogue GTI reduced to silence. There are many wounds to lick for the GTA, as the weakened fleet struggles to maintain order    in its systems. Although the cease-fire treaty with their new Vasudan allies is still holding, the PVE is still busy dealing with the terrorist HoL faction.
+
   The day is August 3, 2335. Thirteen months have passed since the Lucifer was destroyed, mysteriously locking the Sol system away. It's barely been two months since the Hades  
 +
   superdestroyer was destroyed in orbit of Deneb, and the rogue GTI reduced to silence. There are many wounds to lick for the GTA, as the weakened fleet struggles to maintain order  
 +
   in its systems. Although the cease-fire treaty with their new Vasudan allies is still holding, the PVE is still busy dealing with the terrorist HoL faction.
 
    
 
    
 
   Now is our chance to get past them. We no longer need to so carefully hide. Now we can make our deal with the devil.
 
   Now is our chance to get past them. We no longer need to so carefully hide. Now we can make our deal with the devil.

Latest revision as of 18:11, 19 September 2017

If you have a mod or campaign that you wish to be included in the FSO Installer, this is where you start.

Quick Steps

  1. Upload all of the mod's files to a server that allows direct links. Many archive formats are supported, including any format that works with 7zip.
  2. Upload an install.txt file, using the specifications from below, to a location where the mod leader has access and can change it later if necessary.
  3. Post a link to the text file in this thread or PM it to Goober5000.


You can use the FreeSpace Open Installer itself to validate the text file for any syntactical errors. Just run the following command at the command prompt, and select the text file with the dialog that appears: 

java -jar FreeSpaceOpenInstaller.jar validate [file]

You can specify the file to validate on the command line, or you can omit the file and the Installer will prompt you using a standard GUI file dialog. You can also specify "test" instead of "validate" and the Installer will launch a special session that loads the mod repository from your file.

Text File Specifications

Every line in the text file falls into one of three categories: Commands, Parameters, and Files. (Blank lines and tabs are ignored.) See below for an example.

  • Commands
    • Commands are specific words that do special operations during the installation. Commands are in all caps, and are limited to the words listed under the Syntax section of this page.
  • Parameters
    • Parameters can only come after commands. Parameters must come directly after a command. Empty lines are not permited, but tabs are acceptable. Each parameter is specified on a separate line from the command and all other parameters.
  • Files
    • Files are specified by the name of the file to download. Each file goes on its own line.

Syntax

NAME

  • Takes one parameter.
  • Must be the first line in the text file.
  • Is the name of the section as listed to the end user in the 'mods to install' list within the installer.
  • If encountered within a section, it creates a new sub-section. This is shown to the user as a sub option under the first mod section.
  • This command must be paired with an END command at the end of the section.

Example 

  NAME
  Awesome Mod

DESC

  • Takes unlimited parameters.
  • The last parameter must be followed by an ENDDESC.
  • Is the description of the section that is displayed with the user clicks on More Info within the installer.

Example 

  DESC
  This mod is so awesome that it will make you weep blood.
  ENDDESC

ENDDESC

  • Takes no parameters.
  • Must follow the last parameter specified in a DESC.

FOLDER

  • Takes one parameter.
  • Must be listed at least once in each section before any files are listed in that section.
  • Only one FOLDER is allowed. If more than one appears in a section, only the last FOLDER is used for that section.
  • Is the subfolder of the Freespace2 folder to download the files to.
  • A parameter of \ will download files to the root Freespace2 directory.
    • Only use this if your archives already include subfolders!

Example: This will install to Freespace2\awesomemod_1 

  FOLDER
  awesomemod_1

DELETE

  • Takes one parameter.
  • Deletes a file.
  • Files listed must be listed in subfolders as necessary relating to the FOLDER parameter specified.
  • Is the name of the file to delete.

Example: If the FOLDER is \ 

  DELETE
  awesomemod_1\awesomeOLDgraphics.vp

RENAME

  • Takes two parameters.
  • Allows renaming or moving of files.
  • The first parameter is the file to be renamed or moved.
  • The second parameter is the destination location and filename.
  • Only works if the destination file doesn't already exist.
  • Files listed must be listed in subfolders as necessary relating to the FOLDER parameter specified.

Example: If the FOLDER is \ 

  RENAME
  awesomemod_1\awesomegraphics.vp
  awesomemod_1\awesomeOLDgraphics.vp

COPY

  • Takes two parameters.
  • Allows copying files from one place to another.
  • The first parameter is the file to be copied.
  • The second parameter is the destination location and filename.
  • Only works if the destination file doesn't already exist.
  • Files listed must be listed in subfolders as necessary relating to the FOLDER parameter specified.

Example: If the FOLDER is \ 

  COPY
  awesomemod_1\awesomegraphics.vp
  awesomemod_1\awesomeOLDgraphics.vp

URL

Example 

  URL
  http://www.games.com/Freespace2/AwesomeModMirror

MULTIURL

  • Takes unlimited parameters.
  • Must be listed at least once in each section before any files are listed in that section if URL is not used.
  • The last parameter must be followed by an ENDMULTI.
  • Contains possible URLs to the files to be downloaded.
  • The installer tries each URL listed in random order to get a successful download.

Example 

  MULTIURL
  http://www.games.com/Freespace2/AwesomeModMirror1
  http://www.games.com/Freespace2/AwesomeModMirror2
  http://www.games.com/Freespace2/AwesomeModMirror3
  ENDMULTI

ENDMULTI

  • Takes no parameters.
  • Must follow the last parameter specified in a MULTIURL.

HASH

  • Takes three parameters.
  • Allows the installer to check file hashes to ensure successful downloads.
  • The first parameter is the type of hash to use.
    • Accepted hash types are MD5, SHA-1, or SHA-256.
  • The second parameter is the file to check.
  • The third parameter is the actual hash to check the file against.
    • It can be upper- or lower-case.
  • Files listed must be listed in subfolders as necessary relating to the FOLDER parameter specified.

Example: If the FOLDER is \ 

  HASH
  MD5
  awesomemod_1\awesomegraphics.vp
  A49767C6CD9D9A5AB157F9FF75A4D5FA

PATCH

  • Takes nine parameters, formatted like three consecutive HASH tokens.
  • Allows the installer to download a small binary diff and patch a mod file instead of downloading a new full version.
  • The first, fourth, and seventh parameters are the type of hash to use. (These can be different for each triplet.)
    • Accepted hash types are MD5, SHA-1, or SHA-256.
  • The third, sixth, and ninth parameters are the actual hashes to check the files against.
    • They can be upper- or lower-case.
  • The second parameter is the old version of the mod file.
  • The fifth parameter is the binary diff file.
  • The eighth parameter is the new version of the mod file.
  • Files listed must be listed in subfolders as necessary relating to the FOLDER parameter specified.

Example: 

  PATCH
  MD5
  oldfile.vp
  0F0F0F0F0F0F0F0F00F0F0F0F0F00F0F
  SHA-1
  patchFile
  A49767C6CD9D9A5AB157F9FF75A4D5FA
  SHA-1
  newfile.vp
  1A1A1A1A1A1A1A1AA1A1A1A1A1AA11A1

Binary diff files can be created using the Installer itself: 

java -jar FreeSpaceOpenInstaller.jar diff [algorithm] [old file] [new file]

The patch functionality can also be tested using the Installer: 

java -jar FreeSpaceOpenInstaller.jar patch [old file] [diff file]

If any of the "diff" or "patch" command-line parameters are not supplied, the Installer will prompt you for them using standard GUI dialogs.

NOTE

  • Takes unlimited parameters.
  • The last parameter must be followed by an ENDNOTE.
  • Is displayed to the user in the post-installation section of the installer.

Example 

  NOTE
  This mod requires FSO 3.6.54
  ENDNOTE

ENDNOTE

  • Takes no parameters.
  • Must follow the last parameter specified in a NOTE.

DEPENDENCIES

  • Takes unlimited parameters.
  • The last parameter must be followed by an ENDDEPENDENCIES.
  • Contains prerequisites for the mod that are outside of the direct mod tree. (Mods that are in a tree already require all of their ancestor mods.)
  • Each parameter should be the fully-qualified tree path of another mod. A tree path is constructed by concatenating mod names in order from parent to child, with a dot or period between each mod name.
  • Make sure you double-check your tree path! If the installer cannot find a dependency, it assumes all mirrors for that dependency have failed and suggests that the user not install the mod.

Example 

  DEPENDENCIES
  FSU MediaVPs, version 3.6.12
  FSU MediaVPs, version 3.6.12.MV_Assets
  FSU MediaVPs, version 3.6.12.MV_Effects
  ENDDEPENDENCIES

ENDDEPENDENCIES

  • Takes no parameters.
  • Must follow the last parameter specified in a DEPENDENCIES.

FLAGS

  • Takes unlimited parameters, though only recognized flags are stored and duplicate flags are only stored once.
  • The last parameter must be followed by an ENDFLAGS.
  • Contains flags for the mod that allow tweaking of installation behavior. These are listed below. (Currently only one flag is implemented.)
  • Flags are not case-sensitive. Internally they are converted to upper-case before being stored.
  • EXCLUDE-FROM-COMPLETE-INSTALLATION: Prevents a mod from being selected when the "Complete" installation option is chosen. This is for mods that shouldn't be installed without the user's explicit intent, such as language packs.

Example 

  FLAGS
  EXCLUDE-FROM-COMPLETE-INSTALLATION
  ENDFLAGS

ENDFLAGS

  • Takes no parameters.
  • Must follow the last parameter specified in a FLAGS.

VERSION

  • Takes one parameter.
  • Is a string that represents the version of the files in that section.
    • If this parameter is changed, the installer will flag that section as outdated.

END

  • Takes no parameters.
  • Must include this command for every NAME command.
  • Signifies the end of a section.

Example Install.txt File

  NAME
  Between the Ashes: Mefistofele
  DESC
  This mod requires MediaVPs 3.6.12!
  
  The day is August 3, 2335. Thirteen months have passed since the Lucifer was destroyed, mysteriously locking the Sol system away. It's barely been two months since the Hades 
  superdestroyer was destroyed in orbit of Deneb, and the rogue GTI reduced to silence. There are many wounds to lick for the GTA, as the weakened fleet struggles to maintain order 
  in its systems. Although the cease-fire treaty with their new Vasudan allies is still holding, the PVE is still busy dealing with the terrorist HoL faction.
  
  Now is our chance to get past them. We no longer need to so carefully hide. Now we can make our deal with the devil.
  ENDDESC
  FOLDER
  \
  DELETE
  BtA Demo\BTA_Mainhall.vp
  RENAME
  BtA Demo\BTA_Main.vp
  BtA Demo\BTA_Interface.vp
  URL
  http://www.lunardigitalproductions.com/bta/downloads/demo/installer/
  BTA_DEMO_Root.zip
  BTA_DEMO_Assets1.zip
  BTA_DEMO_Assets2.zip
  HASH
  MD5
  BtA Demo\BTA_DEMO_Root.vp
  706eebd0c2711d850af414b115013248
  HASH
  MD5
  BtA Demo\BTA_DEMO_Assets1.vp
  52cfa540167d280df846daea0e273d86
  HASH
  MD5
  BtA Demo\BTA_DEMO_Assets2.vp
  c719cd92e6ca441c13d900b2ee87203b
  NOTE
  This is a test note!
  ENDNOTE
  
  	NAME
  	Low-End Compatibility
  	DESC
  	This VP replaces the Mainhall menu and cutscenes with versions that will work more smoothly on low-end machines.
  	ENDDESC
  	URL
  	http://www.lunardigitalproductions.com/bta/downloads/demo/installer/
  	BTA_DEMO_00LowEnd.zip
  	HASH
  	MD5
  	BtA Demo\BTA_DEMO_00LowEnd.vp
  	e500623ed6ee6e4b6f5d943bf4023e18
  	VERSION
  	Version 1.1
  	END
  	
  VERSION
  Version 1.1
  END
Retrieved from "https://wiki.hard-light.net/index.php?title=FSO_Installer_Text_Files&oldid=46211"