How to Write Installation Instructions

These scripts will determine how your mod is going to be installed

Auto   Manual   Examples   Testing   Changelog


Auto Installation

Simply paste the link to the file and the installator will figure out what to do on its own.

ftp://ftp.armedassault.info/ofpd/unofaddons2/ww4mod25rel.rar

This has to be a direct link to the file (no Google Drive, Mediafire, Mega etc. - for those you have to use Ask_Get command).

If you have more than one then paste each link in a new line.

ftp://ftp.armedassault.info/ofpd/unofaddons2/ww4mod25rel.rar
ftp://ftp.armedassault.info/ofpd/unofaddons2/ww4mod25patch1.rar

If the link has spaces then replace them with %20.

Add /password: switch if an archive is locked

http://example.com/locked.rar  /password:123

How does it work?

Installer checks the extension of the downloaded file:

  • If it's .rar, .zip, .7z, .ace or .exe then it will extract archive contents to a temporary directory
  • If an .exe couldn't be unpacked then it will ask the user to run it
  • If it's .pbo then program will move it to the addons directory in the modfolder.
  • If it's .pbo but with more than one dot in its name (aka mission file) then it will be moved to the Missions directory in the modfolder.
  • Other types of files are ignored

Then the program repeats this process for each file extracted from the archive.

If it encounters a directory then it will read its name:

  • If it matches modfolder name then it will be moved to the game directory. Other modfolders will be ignored
  • If it matches addons, bin, campaigns, dta, worlds, Missions, MPMissions then it will be moved to the modfolder
  • If it has a dot in its name (aka it's an unpacked mission) then it will be moved to the Missions directory in the modfolder

In any other case it will go through the contents of a directory and follow the same behaviour for each file and sub-directory there.

Existing files will be overwritten. Destination directories that don't exist will be created.

Installer will handle only the first encountered executable and ignore all others.

To make use of missions located in the modfolders start Fwatch with -sortmissions parameter.


Manual Installation

There's a bunch of commands to make installer do exactly what you want

Some commands have aliases so remove and delete are the same.

I recommend to capitalize command names for readability.

Invalid command names will be ignored.

Leading and trailing spaces will be ignored.

Write each command in a separate line.

Commands usually require arguments. Separate them by spaces. If argument contains space then put it in quotation marks.

Any URL must be a direct link to the file and spaces must be replaced with %20.

You can combine both manual and auto installation.


Unpack, Extract

UNPACK <url or file> /password:<text>

Downloads file to the fwatch\tmp\directory and extracts it to the _extracted subfolder (its previous contents are wiped).



Example:

UNPACK  ftp://ftp.armedassault.info/ofpd/mods/fdfmod13_installer.exe

How to handle nested archives:

UNPACK  www.example.com/first.rar
UNPACK  _extracted\second.rar
UNPACK  _extracted\_extracted\third.rar

Add /password: switch if an archive is locked

UNPACK  first.rar  /password:123

Move, Copy

MOVE <url or file> <destination> <new name> /no_overwrite /match_dir

Program will move or copy selected file or folder from the fwatch\tmp\_extracted directory to the modfolder.

Overwrites files.

Sub-directories in the destination path that don't exist will be created.



Example:

MOVE  "FDFmod Readme.html"

This will move
<game folder>\fwatch\tmp\_extracted\FDFmod Readme.html
to the
<game folder>\<modfolder>\



MOVE  example.pbo  addons

This will move
<game folder>\fwatch\tmp\_extracted\example.pbo
to the
<game folder>\<modfolder>\addons\



Exception: if the directory you want to move has the same name as the modfolder you’re installing then the destination path is changed to the game folder.

MOVE  finmod

This will move
<game folder>\fwatch\tmp\_extracted\finmod
to the
<game folder>\

This won't work with wildcards.

You can cancel this behaviour by specifying destination argument.



Wildcard can be used to match multiple files.

MOVE  *.pbo  addons

To match both files and folders add /match_dir switch.

MOVE  *  /match_dir


To rename a file write new name as the third argument.

MOVE  readme.txt  docs  readme_old.txt

Use dot if you don’t want to change location.

MOVE  documentation.pdf  .  readme.pdf


Add /no_overwrite switch to disable overwriting files.

MOVE  *.pbo  addons  /no_overwrite


If url was passed then the file will be downloaded.

MOVE  http://ofp-faguss.com/files/dummyBullet.pbo  addons


To access modfolder files start first argument with <mod>.

MOVE  <mod>\addons\example.pbo  obsolete


Command Copy can take files from any game location if the path starts with <game>.

COPY  <game>\bin\Resource.cpp  bin

Ask_get, Ask_download

ASK_GET  <file name>  <url>

Use this command for links that do not lead directly to the file.

Requests the user to manually download given file.

Installation is paused until user decides to continue or abort.



Example:

ASK_GET  ww4mod25rel.rar  https://www.moddb.com/mods/sanctuary1/downloads/ww4-modpack-25


To access this file use use unpack, ask_run commands without any arguments and move, copy with <download> or <dl> as the source argument.
UNPACK
ASK_RUN
MOVE  <dl>  addons

Ask_run, Ask_execute

ASK_RUN  <url or file>

Use this command for executables that cannot be extracted.

Requests the user to manually launch selected file from the fwatch\tmp\ directory

Installation is paused until user decides to continue or abort.



Examples:

ASK_RUN  ftp://ftp.armedassault.info/ofpd/mods/ECP%20v1.085%20(Full%20Installer).exe
ASK_RUN  _extracted\example.exe


If the file is in the modfolder then start the path with <mod>.
ASK_RUN  <mod>\Install_win2k_XP.bat

Makedir, Newfolder

MAKEDIR  <path>

Creates a folder and its parents (if they don't exist).



Example:

MAKEDIR  addons
MAKEDIR  dta\hwtl

This will create:

<game folder>\<modfolder>
<game folder>\<modfolder>\addons
<game folder>\<modfolder>\dta
<game folder>\<modfolder>\dta\hwtl

Delete, Remove

DELETE  <file> /match_dir

Program will delete selected file or directory from the modfolder.



Example:

DELETE  Install_win98_ME.bat


Wildcards can be used to match multiple files.

DELETE  addons\*.txt

To match both files and folders add /match_dir switch.

DELETE  temp\*  /match_dir


Use this command without any arguments to remove last downloaded file.

DELETE

Rename

RENAME  <file>  <new name>  /match_dir

Program will rename selected file or directory from the modfolder.



Example:

RENAME  addons\lo_res_tex.pbo  lo_res_tex.pbx


Wildcard can be used to match multiple files.

RENAME  addons\*.pbo  *.pbx
RENAME  addons\*.pbo  ??????????????????_OLD*

To match both files and folders add /match_dir switch.

RENAME  *  old_*  /match_dir

UnpackPBO, ExtractPBO

UNPACKPBO  <file>  <destination>

Program will unpack selected PBO file from the modfolder directory.

Overwrites existing files.



Example:

UNPACKPBO  addons\ww4_fx.pbo


Optionally you can specify where to extract files. Sub‐directories in the destination path that don’t exist will be created.

UNPACKPBO  addons\ww4_fx.pbo  temp


To access files from any game location start the path with <game>. If destination wasn’t specified then the addon will be unpacked to the modfolder.

UNPACKPBO  <game>\addons\kozl.pbo  addons

MakePBO

MAKEPBO  <folder>  /no_delete

Program will create a PBO file (no compression) out of the selected folder from the modfolder and then remove the former.



Example:

MAKEPBO  addons\ww4_fx


Add switch /no_delete to keep the source folder.

MAKEPBO  addons\ww4_fx  /no_delete


Use this command without file name to pack last addon unpacked with unpackpbo.

MAKEPBO

If_version, else, endif

if_version <operator> <number>
else
endif

Compares game version and given number.

If it’s correct then following instructions are executed until end of the script or until program encounters endif command. Content between else and endif will be ignored.

If condition wasn’t correct then program will skip commands until end of script or until it encounters else or endif.

Allowed comparison operators are: =, ==, <, <=, >, >=, <>, !=. If there’s no operator then equality is assumed.

Conditions can be nested.



Example:

IF_VERSION <= 1.96
	ASK_GET "WW4 Extended OFP patch v111.zip" https://www.mediafire.com/file/86d97zspupnjk9c
	UNPACK
	MOVE v196_patch\ww4ext_inf_cfg.pbo.OFP addons ww4ext_inf_cfg.pbo
ENDIF
IF_VERSION 1.99
	COPY <game>\bin\Config.cpp bin
ELSE
	COPY <game>\Res\bin\Config.cpp bin
ENDIF

Edit

EDIT  <file name>  <line number>  <text>  /insert

Replaces text line in selected file from the modfolder directory.



Example:

EDIT addons\FDF_Suursaari\config.cpp - 58 - cutscenes[]      = {"..\finmod\addons\suursaari_anim\intro"};


To access downloaded file use <download> or <dl>.

Add switch /insert to add a new line instead of replacing.


Manual Installation - examples

This is a script for installing WW4 mod v2.5

UNPACK ftp://ftp.armedassault.info/ofpd/unofaddons2/ww4mod25rel.rar
MOVE  @ww4mod25
MOVE * /match_dir

UNPACK  ftp://ftp.armedassault.info/ofpd/unofaddons2/ww4mod25patch1.rar
MOVE  *  addons  /match_dir

UNPACK  http://ofp-faguss.com/fwatch/download/ofp_aspect_ratio206.rar
MOVE  Files\WW4mod25\Resource.cpp  bin

UNPACK  http://ofp-faguss.com/fwatch/download/anims_fwatch.rar
MOVE  Files\WW4mod25\Anims.pbo  dta

UNPACK  http://ofp-faguss.com/files/ww4_binoculars.zip
UNPACKPBO  dta\scripts.pbo
MOVE  ww4_fwatch_binoc.sqs  dta\scripts
MAKEPBO
MOVE  replacement\Config.cpp  bin

This is a script for installing FDF mod 1.4

UNPACK  ftp://ftp.armedassault.info/ofpd/mods/fdfmod13_installer.exe
MOVE  finmod
MOVE  "Missions\FDF MOD\*"  Missions
MOVE  MPMissions\*  MPMissions
MOVE  *
DELETE

UNPACK  ftp://ftp.armedassault.info/ofpd/mods/fdfmod14_ww2.rar
MOVE  finmod
MOVE  "Missions\FDF WW2\*.pbo"  Missions
MOVE  MPMissions\*  MPMissions
DELETE

UNPACK  ftp://ftp.armedassault.info/ofpd/mods/FDF_desert_pack.rar
MOVE  finmod
MOVE  "Missions\FDF MOD\*"  Missions
MOVE  MPMissions\*  MPMissions
MOVE  *
DELETE

UNPACK  ftp://ftp.armedassault.info/ofpd/islands/Suursaari_release_v10.zip
MOVE  FDF_Suursaari.pbo  addons
MOVE  Suursaari_anim  addons
MOVE  *
DELETE

UNPACKPBO  addons\FDF_Suursaari.pbo
EDIT addons\FDF_Suursaari\config.cpp 58 "cutscenes[]      = {"..\finmod\addons\suursaari_anim\intro"};"
MAKEPBO

UNPACK  http://ofp-faguss.com/fwatch/download/ofp_aspect_ratio206.rar
MOVE  Files\FDF\Resource.cpp  bin

UNPACK  http://ofp-faguss.com/fwatch/download/anims_fwatch.rar
MOVE  Files\FDF\Anims.pbo  dta

UNPACK  http://pulverizer.pp.fi/ewe/missions/finmodmpmissions.7z
MOVE  mpmissions

This is a script for installing WGL 5.12 mod

ftp://ftp.armedassault.info/ofpd/unofaddons2/WGL5.1_Setup.exe
http://pulverizer.pp.fi/ewe/mods/wgl512_2006-11-12.rar

IF_VERSION  <=  1.96
	UNPACKPBO  <game>\Res\Dta\HWTL\data.pbo  dta\HWTL
	COPY <mod>\newdata\*.pa?  dta\HWTL\Data
	MAKEPBO
	
	UNPACKPBO  <game>\Res\Dta\HWTL\data3d.pbo  dta\HTWL
	COPY  <mod>\newdata\*.p3d  dta\HWTL\data3d
	MAKEPBO
ELSE
	UNPACKPBO  <game>\DTA\Data.pbo  dta
	COPY  <mod>\newdata\*.pa?  dta\Data
	MAKEPBO
	
	UNPACKPBO  <game>\DTA\Data3D.pbo  dta
	COPY  <mod>\newdata\*.p3d  dta\Data3D
	MAKEPBO
ENDIF

UNPACK  http://ofp-faguss.com/fwatch/download/ofp_aspect_ratio206.rar
MOVE  Files\WGL\Resource.cpp  bin

UNPACK  http://ofp-faguss.com/fwatch/download/anims_fwatch.rar
MOVE  Files\WGL\Anims.pbo  dta

UNPACK  http://pulverizer.pp.fi/ewe/missions/wglmiss.7z
MOVE  *  mpmissions

This is a script for installing Tupas mod

ASK_GET "TuPaS MOD-1a.bin" https://drive.google.com/open?id=1hLVE07MZ6XDGxkMCMeHrP57CwIBddu9t
ASK_GET "TuPaS MOD-1b.bin" https://drive.google.com/open?id=1KVC1qlH-gnkhdSp9yT5ER_ngKq4fEzOa
ASK_GET "TuPaS MOD.exe" https://drive.google.com/open?id=1VLkVLiwQ6CfblXpa-sLBzaHti_7Nk86g
ASK_RUN

This is a script for installing Llaumax sky replacement

UNPACK  ftp://ftp.armedassault.info/ofpd/unofaddons2/OFPR_Addon_LlauMaxSkyPackV12.zip
IF_VERSION  <=  1.96
	UNPACKPBO  <game>\Res\Dta\HWTL\data.pbo  dta\HWTL
	MOVE  llaumax\newdata\*.pa?  dta\HWTL\Data
	MAKEPBO
	
	UNPACKPBO  <game>\Res\Dta\HWTL\data3d.pbo  dta\HTWL
	MOVE  llaumax\newdata\*.p3d  dta\HWTL\data3d
	MAKEPBO
ELSE
	UNPACKPBO  <game>\DTA\Data.pbo  dta
	MOVE  llaumax\newdata\*.pa?  dta\Data
	MAKEPBO
	
	UNPACKPBO  <game>\DTA\Data3D.pbo  dta
	MOVE  llaumax\newdata\*.p3d  dta\Data3D
	MAKEPBO
ENDIF

Testing scripts
  • Write your installation script in fwatch\data\addonInstaller_test.txt
  • Run addonInstaller.exe with parameter -testmod=<name>

Where <name> is the name of a modfolder. For example: -testmod=@test.

Don't update existing mods that way. Make a backup copy and then experiment on it.

Review fwatch\data\addonInstallerLog.txt to see how installation process went.

Add parameter -gameversion=<number> for testing conditions.


In testing mode downloaded files won't be removed so you won't have to redownload them every time you run installator.


Version history
0.1 (03.03.17)
First release.


0.2 (11.03.19)
  • added commands: Ask_Download, Delete, Rename, If_version, else, endif, Makepbo, UnpackPBO, Edit
  • renamed command Execute to Ask_Execute
  • renamed command Mdir to Makedir

  • Move – now overwrites by default, added /no_overwrite switch
  • Move – can access modfolder files with >mod> macro
  • Move – can now rename files
  • Move – wildcards will not match folders unless /match_dir switch was added
  • Move – renamed macro DOWNLOADED_FILENAME to <download> and <dl>
  • Move – now source argument can be url

  • Copy – can access game root directory with <game> macro

  • Makedir – could be used to create custom folders in the game root directory – fixed
  • Makedir – now creates modfolder if it’s missing

  • Unpack, Ask_Execute – will work on downloaded file if no argument given
  • Unpack, Ask_Execute – now source argument can be url
  • Unpack – archive within archive was unpacked to the wrong folder – fixed
  • Unpack – added /password: switch

  • Auto Installation – added /password: switch

  • Download – now considered obsolete