How to create a PAK ruleset and installer for distribution

[joshuha]

One of the new features in the newest patch is that PAK files can work without requiring clients to have the PAK files actually installed. This makes distribution of rulesets much easier IF we can get everyone to start releasing rulesets in an installer format. To further that goal I am releasing a NSIS script that will install a PAK file and the appropiate registry entries to make this much easier for new players and GMs.

First, let's clear up what exactly a PAK file is.

A PAK file is just a zipped up version of your ruleset with the .zip extension renamed to .PAK much like the d20.pak file included with Fantasy Grounds. Note you don't include the top level folder, just the ruleset contents.
The PAK file needs to be placed in the same directory as the Fantasy Grounds EXE.
PAK files need registry entries for Fantasy Grounds to be aware they exist. These are at HKCU\SOFTWARE\Fantasy Grounds\Rulesets\[ruleset name]" "Name" "[rulesetname]" and HKCU\SOFTWARE\Fantasy Grounds\Rulesets\[ruleset name]" "Package" "[filename].pak"
PAK files makes use of a logo.png and license.txt file in the main ruleset directory when looking at the ruleset from the main Fantasy Grounds front end loader.
PAK files when installed on a lite license allow for easier offline character creation without all the database errors. The only thing unclear in the new patch is after the first time the PAK file is stream where it is installed and if it behaves like a full PAK file. Another benefit is traditonally a PAK file installed on a host and client machine will mean no ruleset download, even when starting new campaigns.


Now that we understand what a PAK file is, lets discuss creating an installer for it. I highly recommend NSIS, an open source installer that builds install packages from scripts. NSIS is used by a lot of installers out there, you may just not notice.
https://nsis.sourceforge.net/Main_Page

Along with NSIS I like to use HM NIS Edit which is a nice graphical interface to NSIS that I think makes it easier to test and build out the installer scripts.
https://hmne.sourceforge.net/

Below is an example script for a ruleset I am calling test. The assumptions here are in the same folder you are build this script is you have a test.pak file of your ruleset (and remember this is a renamed .zip with the ruleset files and no top level folder), a file called license.txt which shows text you want displayed in the installer, and also a couple of .mod file for your ruleset which will get placed in the FG module direcotry. I try to make sure my code is well commented but feel free to ask question on how the logic works. Once you understand how it works, changing it for new rulesets and building a new install package is literally seconds worth of work.



;NSIS Modern User Interface
;Written by Joshuha OWen

;--------------------------------
;Include Modern UI

!include "MUI.nsh"

;--------------------------------
;General

;Name and file
Name "Test Ruleset - Demo Installer Program"
OutFile "TestRulesetInstaller.exe"

;Default installation folder
InstallDir "$PROGRAMFILES\Fantasy Grounds II"

;Get installation folder from registry if available, in case different than default
InstallDirRegKey HKCU "Software\Fantasy Grounds\2.0" "InstallDir"

;Vista redirects $SMPROGRAMS to all users without this
RequestExecutionLevel admin

;--------------------------------
;Interface Settings

!define MUI_ABORTWARNING

;--------------------------------
;Pages

;Display license.txt file while installing
!insertmacro MUI_PAGE_LICENSE "License.txt"
!insertmacro MUI_PAGE_DIRECTORY
!insertmacro MUI_PAGE_INSTFILES

!insertmacro MUI_UNPAGE_CONFIRM
!insertmacro MUI_UNPAGE_INSTFILES

;--------------------------------
;Languages

!insertmacro MUI_LANGUAGE "English"

;--------------------------------
;Installer Sections

Section "Default Section" SecDefault

SetOutPath "$INSTDIR"
;Put is same folder where compliling this script
File "test.pak"

;Get FG data folder for modules
ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
SetOutPath "$1\Modules"
File "rules-gm.mod"
File "rules-player.mod"

;Register the ruleset package
WriteRegStr HKCU "SOFTWARE\Fantasy Grounds\Rulesets\TestRuleset" "Name" "Test Ruleset"
WriteRegStr HKCU "SOFTWARE\Fantasy Grounds\Rulesets\TestRuleset" "Package" "test.pak"

;Create uninstaller to remove the pak file and registry entries
WriteUninstaller "$INSTDIR\TestRuleset-Uninstall.exe"


SectionEnd

;--------------------------------
;Descriptions

;Language strings
LangString DESC_SecDefault ${LANG_ENGLISH} "Main"

;Assign language strings to sections
!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
!insertmacro MUI_DESCRIPTION_TEXT ${SecDefault} $(DESC_SecDefault)
!insertmacro MUI_FUNCTION_DESCRIPTION_END

;--------------------------------

;--------------------------------
;Uninstaller Section

Section "Uninstall"

;delete pak file
Delete "$INSTDIR\test.pak"

;Get FG data folder for modules, delete modules
ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
SetOutPath "$1\Modules"
Delete "$1\Modules\rules-gm.mod"
Delete "$1\Modules\rules-player.mod"

;Delete uninstaller
Delete "$INSTDIR\TestRuleset-Uninstall.exe"

;Remove registry entries
DeleteRegKey HKCU "Software\Fantasy Grounds\Rulesets\TestRuleset"

SectionEnd

[Griogre]

Joshuha, how does NSIS compare to the Inno Setup (https://www.innosetup.com/isinfo.php) program? Do you know? While not open source, it is free for any type of use and Inno is very stable and - has a wizard for making the setup program. The ruleset creator would only have to add a few lines to the script for the registry entry after he ran the wizard and we could give him the lines to copy and paste.

[Spyke]

Thanks Joshuha, I need to get my head round this.

[Moon Wizard]

I tried renaming the d20.pak file in the FG directory to d20.pak.zip, so that I could see an example of a pak file in action. However, Windows is tells me that d20.pak.zip is an invalid compressed file.

Any ideas on why the d20.pak file is not accessible as a ZIP on Windows? Or any examples of a ruleset built as a PAK file that you can point me to?

Thanks,
JPG

[joshuha]

The d20.pak is a special case because its encrypted and thus why you have to use the d20unpak utility for it. I don't have an example I can easily share yet but I can package my Earthdawn ruleset release in one soon. I plan on releasing that one within a few days.

[Griogre]

OK, I commented out the adding and deleting modules and also the unmatching deleting a DA key from the uninstaller which I assume is an error. The installer compiled and put in the keys and put a pak file where it should have. FG doesn't run the pak though, what's the next step or did I screw up somewhere? Or is it the ruleset? It gives the standard "Could not load ruleset root base.xml".



;NSIS Modern User Interface
;Written by Joshuha OWen

;--------------------------------
;Include Modern UI

!include "MUI.nsh"

;--------------------------------
;General

;Name and file
Name "d20_JPG Ruleset - Demo Installer Program"
OutFile "d20_JPGInstaller.exe"

;Default installation folder
InstallDir "$PROGRAMFILES\Fantasy Grounds II"

;Get installation folder from registry if available, in case different than default
InstallDirRegKey HKCU "Software\Fantasy Grounds\2.0" "InstallDir"

;Vista redirects $SMPROGRAMS to all users without this
RequestExecutionLevel admin

;--------------------------------
;Interface Settings

!define MUI_ABORTWARNING

;--------------------------------
;Pages

;Display license.txt file while installing
!insertmacro MUI_PAGE_LICENSE "License.txt"
!insertmacro MUI_PAGE_DIRECTORY
!insertmacro MUI_PAGE_INSTFILES

!insertmacro MUI_UNPAGE_CONFIRM
!insertmacro MUI_UNPAGE_INSTFILES

;--------------------------------
;Languages

!insertmacro MUI_LANGUAGE "English"

;--------------------------------
;Installer Sections

Section "Default Section" SecDefault

SetOutPath "$INSTDIR"
;Put is same folder where compliling this script
File "d20_JPG.pak"

;Get FG data folder for modules
;ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
;SetOutPath "$1\Modules"
;File "rules-gm.mod"
;File "rules-player.mod"

;Register the ruleset package
WriteRegStr HKCU "SOFTWARE\Fantasy Grounds\Rulesets\d20_JPG" "Name" "d20_JPG"
WriteRegStr HKCU "SOFTWARE\Fantasy Grounds\Rulesets\d20_JPG" "Package" "d20_JPG.pak"

;Create uninstaller to remove the pak file and registry entries
WriteUninstaller "$INSTDIR\d20_JPG-Uninstall.exe"


SectionEnd

;--------------------------------
;Descriptions

;Language strings
LangString DESC_SecDefault ${LANG_ENGLISH} "Main"

;Assign language strings to sections
!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
!insertmacro MUI_DESCRIPTION_TEXT ${SecDefault} $(DESC_SecDefault)
!insertmacro MUI_FUNCTION_DESCRIPTION_END

;--------------------------------

;--------------------------------
;Uninstaller Section

Section "Uninstall"

;delete pak file
Delete "$INSTDIR\d20_JPG.pak"

;Get FG data folder for modules, delete modules
;ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
;SetOutPath "$1\Modules"
;Delete "$1\Modules\rules-gm.mod"
;Delete "$1\Modules\rules-player.mod"

;Delete uninstaller
Delete "$INSTDIR\d20_JPG-Uninstall.exe"

;Remove registry entries
DeleteRegKey HKCU "Software\Fantasy Grounds\Rulesets\d20_JPG"
;DeleteRegKey HKCU "Software\DigitalAdventures\TestRuleset"

SectionEnd

[joshuha]

You are sure you put the base xml and all the top level ruleset files right in the .pak root? No subfolder like you would have in the rulesets dir except for frames, scripts, etc.?

[Griogre]

I could have sworn I did, I tried it twice earlier - but maybe not. *shrug* I just did it again and rebuilt the installer and it worked. Magic. ;) Thanks for the help.

[Spyke]

I've just tried it and it worked beautifully. I'll distribute the next version of the GURPS ruleset in this way. :)

Many thanks,
Spyke

[Tarostar]

Wonderful. Thank you joshuha, this will make distributing ruleset updates much easier!

I've tested it and it worked great. I got one warning, but that doesn't seem to cause a problem but I thought I'd mention it. Know what it is?

"Variable "MUI_TEXT" not referenced or never set, wasting memory!"

[Spyke]

"Variable "MUI_TEXT" not referenced or never set, wasting memory!"
I saw this too, but haven't sat down to figure out where the warning was coming from yet.

Spyke

[Griogre]

I got the same warning. I'm guessing it is coming from the


!insertmacro MUI_DESCRIPTION_TEXT ${SecDefault} $(DESC_SecDefault)
but I never bothered to read the docs. :p I'm guessing that macro declares a variable that is never used. Given the indentation of the line - it might have been commented out in the past.

[Moon Wizard]

With the latest version of FG (v2.6.4), you can simply install the PAK file in the FG program directory (not data directory), and you don't need to set registry keys any longer.

Cheers,
JPG

[Foen]

That is good news indeed!

[Bidmaron]

Doesn't installing something in the program directory bring up the host of problems in Vista regarding modification of the program files directory?

If no registry editing is needed, is there a version of the script that just handles the install without registry editing?

[drahkar]

Doesn't installing something in the program directory bring up the host of problems in Vista regarding modification of the program files directory?

If no registry editing is needed, is there a version of the script that just handles the install without registry editing?

This is an updated version of the original script with all registry updates removed. I've left all of the original test ruleset variables. But I went ahead and put the things you should change to match your ruleset in bold.

Let me know if you run into any problems and I'll update to address it.



;NSIS Modern User Interface
;Written by Joshuha OWen
;Updated by: Drahkar
;Update Date: 1/10/2010

;--------------------------------
;Include Modern UI

!include "MUI.nsh"

;--------------------------------
;General

;Name and file
Name "Test Ruleset - Demo Installer Program"
OutFile "TestRulesetInstaller.exe"

;Default installation folder
InstallDir "$PROGRAMFILES\Fantasy Grounds II"

;Get installation folder from registry if available, in case different than default
InstallDirRegKey HKCU "Software\Fantasy Grounds\2.0" "InstallDir"

;Vista redirects $SMPROGRAMS to all users without this
RequestExecutionLevel admin

;--------------------------------
;Interface Settings

!define MUI_ABORTWARNING

;--------------------------------
;Pages

;Display license.txt file while installing
;This will throw an error if you don't have a license.txt to include.
!insertmacro MUI_PAGE_LICENSE "License.txt"
!insertmacro MUI_PAGE_DIRECTORY
!insertmacro MUI_PAGE_INSTFILES

!insertmacro MUI_UNPAGE_CONFIRM
!insertmacro MUI_UNPAGE_INSTFILES

;--------------------------------
;Languages

!insertmacro MUI_LANGUAGE "English"

;--------------------------------
;Installer Sections

Section "Default Section" SecDefault

SetOutPath "$INSTDIR"
;Put is same folder where compliling this script
File "test.pak"

;Get FG data folder for modules
;The following is only required if you have modules to include with the installation.
ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
SetOutPath "$1\Modules"
File "rules-gm.mod"
File "rules-player.mod"

;Create uninstaller to remove the pak file and registry entries
WriteUninstaller "$INSTDIR\TestRuleset-Uninstall.exe"


SectionEnd

;--------------------------------
;Descriptions

;Language strings
LangString DESC_SecDefault ${LANG_ENGLISH} "Main"

;Assign language strings to sections
!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
!insertmacro MUI_DESCRIPTION_TEXT ${SecDefault} $(DESC_SecDefault)
!insertmacro MUI_FUNCTION_DESCRIPTION_END

;--------------------------------

;--------------------------------
;Uninstaller Section

Section "Uninstall"

;delete pak file
Delete "$INSTDIR\test.pak"

;The following is only required if you have modules to include with the installation.

;Get FG data folder for modules, delete modules
ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
SetOutPath "$1\Modules"
Delete "$1\Modules\rules-gm.mod"
Delete "$1\Modules\rules-player.mod"

;Delete uninstaller
Delete "$INSTDIR\TestRuleset-Uninstall.exe"

SectionEnd

[Zeus]

Does anyone know what the additions to the script would be to include the installation of an extension file?

I would like the installer to install the ruleset, extension and some modules.

[drahkar]

Does anyone know what the additions to the script would be to include the installation of an extension file?

I would like the installer to install the ruleset, extension and some modules.

You would add modules to this section:


;Get FG data folder for modules
;The following is only required if you have modules to include with the installation.
ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
SetOutPath "$1\Modules"
File "rules-gm.mod"
File "rules-player.mod"

Adding and removing entries needed there. Make sure to duplicate the modules in the uninstall section here:


;Get FG data folder for modules, delete modules
ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
SetOutPath "$1\Modules"
Delete "$1\Modules\rules-gm.mod"
Delete "$1\Modules\rules-player.mod"

Finally, for extensions, just after the install module section in the script, add the following:


SetOutPath "$1\extensions"
File "nameofextension1.ext"
File "nameofextension2.ext"

And just after the uninstall module section add the following:


Delete "$1\extensions\nameofextension1.ext"
Delete "$1\extensions\nameofextension2.ext"

Does that make sense?

[Zeus]

It does indeed. Thank you for the information.

[drahkar]

Glad I could help!

[drahkar]

Also if you are wanting to add a splash screen to your installer here is the process.

First you need to create the image. Once you have the image created, remember that you need to save it as a Windows BMP and if you want it to have a transparency to it you need to set the matte to some color completely different than the rest of the image. Be sure to document the Hex Color Code of the color. You will need that later.

Paste the following just after the 'General' section of the above script.



;--------------------------------
;Splash Screen

XPStyle on

Function .onInit
# the plugins dir is automatically deleted when the installer exits InitPluginsDir
File /oname=$PLUGINSDIR\splash.bmp "arm4logo.bmp"
#optional
#File /oname=$PLUGINSDIR\splash.wav "sound.wav"

advsplash::show 3000 600 400 0x6dbe45 $PLUGINSDIR\splash

Pop $0 ; $0 has '1' if the user closed the splash screen early,
; '0' if everything closed normally, and '-1' if some error occurred.
FunctionEnd


Calling format
advsplash::show Delay FadeIn FadeOut KeyColor FileName

Delay - length to show the screen for (in milliseconds)
FadeIn - length to show the fadein scene (in ms) (not included in Delay)
FadeOut - length to show the fadeout scene (in ms) (not included in Delay)
KeyColor - color used for transparency, could be any RGB value (for ex. R=255 G=100 B=16 -> KeyColor=0xFF6410), use KeyColor=-1 if there is no transparent color at your image.
FileName - splash bitmap filename (without the .bmp).

This should give you the initial information you need to add a splash screen. The final Script should look something like:



;NSIS Modern User Interface
;Written by Joshuha OWen
;Updated by: Drahkar
;Update Date: 1/10/2010

;--------------------------------
;Include Modern UI

!include "MUI.nsh"

;--------------------------------
;General

;Name and file
Name "Test Ruleset - Demo Installer Program"
OutFile "TestRulesetInstaller.exe"

;Default installation folder
InstallDir "$PROGRAMFILES\Fantasy Grounds II"

;Get installation folder from registry if available, in case different than default
InstallDirRegKey HKCU "Software\Fantasy Grounds\2.0" "InstallDir"

;Vista redirects $SMPROGRAMS to all users without this
RequestExecutionLevel admin

;--------------------------------
;Splash Screen

XPStyle on

Function .onInit
# the plugins dir is automatically deleted when the installer exits InitPluginsDir
File /oname=$PLUGINSDIR\splash.bmp "logo.bmp"
#optional
#File /oname=$PLUGINSDIR\splash.wav "sound.wav"

advsplash::show 3000 600 400 0x6dbe45 $PLUGINSDIR\splash

Pop $0 ; $0 has '1' if the user closed the splash screen early,
; '0' if everything closed normally, and '-1' if some error occurred.
FunctionEnd

;--------------------------------
;Interface Settings

!define MUI_ABORTWARNING

;--------------------------------
;Pages

;Display license.txt file while installing
;This will throw an error if you don't have a license.txt to include.
!insertmacro MUI_PAGE_LICENSE "License.txt"
!insertmacro MUI_PAGE_DIRECTORY
!insertmacro MUI_PAGE_INSTFILES

!insertmacro MUI_UNPAGE_CONFIRM
!insertmacro MUI_UNPAGE_INSTFILES

;--------------------------------
;Languages

!insertmacro MUI_LANGUAGE "English"

;--------------------------------
;Installer Sections

Section "Default Section" SecDefault

SetOutPath "$INSTDIR"
;Put is same folder where compliling this script
File "test.pak"

;Get FG data folder for modules
;The following is only required if you have modules to include with the installation.
ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
SetOutPath "$1\Modules"
File "rules-gm.mod"
File "rules-player.mod"

;Create uninstaller to remove the pak file and registry entries
WriteUninstaller "$INSTDIR\TestRuleset-Uninstall.exe"


SectionEnd

;--------------------------------
;Descriptions

;Language strings
LangString DESC_SecDefault ${LANG_ENGLISH} "Main"

;Assign language strings to sections
!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
!insertmacro MUI_DESCRIPTION_TEXT ${SecDefault} $(DESC_SecDefault)
!insertmacro MUI_FUNCTION_DESCRIPTION_END

;--------------------------------

;--------------------------------
;Uninstaller Section

Section "Uninstall"

;delete pak file
Delete "$INSTDIR\test.pak"

;The following is only required if you have modules to include with the installation.

;Get FG data folder for modules, delete modules
ReadRegStr $1 HKCU "SOFTWARE\Fantasy Grounds\2.0" "DataDir"
SetOutPath "$1\Modules"
Delete "$1\Modules\rules-gm.mod"
Delete "$1\Modules\rules-player.mod"

;Delete uninstaller
Delete "$INSTDIR\TestRuleset-Uninstall.exe"

SectionEnd