FSO Installer Text Files

From FreeSpace Wiki
Revision as of 06:59, 9 June 2014 by Goober5000 (talk | contribs) (DEPENDENCIES: clarification)
Jump to: navigation, search

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.

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

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 (.) 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.

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