gtkradiant/setup/win32/HOWTO

Howto add new game packs to the InstallShield setup
---------------------------------------------------

Background Info
---------------
The files that IS uses are pretty much all text files, in the template/ directory
we have a special copy of these files that make up the IS project.

The copy in the template/ directory has files which contain string like
<<GTK_DIR>> which are replaced with actual values whenever the setup.pl script
is used.


TTimo
8/5/2002

Disclaimer: I'm writing that as I am building the RTCW game pack. It is possible
that it is fairly outdated when you read it, but my guess is it can be a useful
reference document.
Update: using this for JKII support, made sure everything is still valid

Hydra
5/6/2002
 - Updating for Halflife build, added a bit more info in places.

NOTE: you need cygwin installed (http://www.cygwin.com) to run setup.pl tools
(Base installation + perl)

You also need UUIDGEN.exe in your path.  It's normally in the 
"Visual Studio .NET\Common7\Tools" directory

Some experience with IS and our particular way of handling it is expected.
The following information is DENSE, read everything

- select a base name for the pack (which we will use in various variables):
WOLF
- make a RELEASE build of GtkRadiant.
- run setup.pl to generate the IS directories
  e.g. ./setup.pl 'c:\\my documents\\Source\\GtkRadiant' q3.cf
  (the directory contains GtkRadiant, Src, etc..)
- start WorkDir/GtkRadiant.ipr, this is an half-templated setup we can
easily work on to add new stuff

- go to file groups and start adding new groups:
Wolf Executable Files
  will hold the editor modules and binaries (map compiler, bspc)
Wolf Media Files
  will hold sample files and editor files:
  maps, models, additional textures, shader scripts, entities.def, project template
set the destination directory for those files:
Wolf Executable Files
  goes in the game pack directory: DIR_GAMETOOLS_WOLF
Wolf Media Files
  goes straight into the Wolf path: DIR_GAME_WOLF

- start feeding stuff in those file groups
  make sure all those files start from the prefix we are working with
  (C:\home\Id in my case)

- add a component:
  Wolf (Wolf Executable Files)
    -- Wolf editing media (Wolf Media Files)
  NOTE: make sure that you put the file groups in those components you created!

- go to add the pack to setup.rul:
add new globals
// Wolf
NUMBER DO_GAME_WOLF_BOOL;
STRING szDIR_GAME_WOLF, szDIR_GAMETOOLS_WOLF;

- in OnFirstUIBefore
define any strings you use, e.g. szJKII and DEFAULTJKIIDIR;
add template for wolf pack inclusion
DO_GAME_WOLF_BOOL = <<DO_GAME_WOLF_BOOL>>;

- copy 'game pack #1' code and paste is as a 'game pack #2'
start renaming the code and updating it
(use the registry key for default path lookup if possible)
Wolf setup doesn't leave an install path, we will hardcode to
C:\\Program Files\\Return To Castle Wolfenstein
and look for the binary
(note, this is by far the part with the most things to do,
read carefully the game pack code, replace everywhere it's needed,
put the right 'BACK' code etc.)

NOTE: the 'if (nResult = BACK) then' code gets more complicated as new packs are added
sadly, it's not possible to store labels into variables for jumps
the next 'nResult = BACK' in non-gamepack code needs to be updated too

- in Dlg_SdStartCopy, add summary for Wolf operations
    if (DO_GAME_WOLF_BOOL == 1) then
      ListAddString(listStartCopy,"Return To Castle Wolfenstein folder:",AFTER);
      ListAddString(listStartCopy,"		" + szDIR_GAME_WOLF,AFTER);
      ListAddString(listStartCopy,"Return To Castle Wolfenstein mapping package folder:",AFTER);
      ListAddString(listStartCopy,"		" + szDIR_GAMETOOLS_WOLF,AFTER);
    endif;

- in OnMoved, add generation of the game file for Wolf
  if (DO_GAME_WOLF_BOOL == 1) then
    if (CreateDir(TARGETDIR ^ "games")< 0) then
       // Report the error; then abort.
       MessageBox ("Unable to create directory " + TARGETDIR ^ "games", SEVERE);
       abort;
    endif;
    if (CreateFile(nvFileHandle, TARGETDIR ^ "games", "wolf.game")< 0) then
      // Report the error.
      MessageBox ("CreateFile " + TARGETDIR ^ "games" + "\\wolf.game failed.", SEVERE);
      abort;
    endif;
    WriteLine(nvFileHandle, "<?xml version=\"1.0\" encoding=\"iso-8859-1\" standalone=\"yes\"?>");
    WriteLine(nvFileHandle, "<!-- generated by Radiant setup, modify at your own risks -->");
    WriteLine(nvFileHandle, "<game name=\"Return To Castle Wolfenstein\" gametools=\"" + szDIR_GAMETOOLS_WOLF + "/\"/>");
    WriteLine(nvFileHandle, "  gamename=\"wolf\"");
    WriteLine(nvFileHandle, "  enginename=\"quake3\"");
    CloseFile(nvFileHandle);
  endif;

- configure the setup so that the new components are installed by default:
  in 'Setup Types' tab, check the new components
  NOTE: do that in BOTH types, specially Custom

- once all those changes are done, we are gonna validate the update..
save and exit IS
make a backup copy of setup/win32/WorkDir ($ cp -R WorkDir/ WorkDir-backup)

- templatize WorkDir/ with the setup.pl
$ ./setup.pl 'c:\\home\\Id' -template template-gen
Configured for base GtkRadiant directory: 'C:\\home\\Id'
Building a template version of WorkDir into template-gen/
Copy files...
Templating UUID...
Processing 'C:\\home\\Id' into '<<GTKRAD_DIR>>'

- check with a recursive diff that it's all good (Araxis Merge!)
Files template/Component Definitions/Default.cdf and template-gen/Component Definitions/Default.cdf differ
Files template/Component Definitions/Default.fgl and template-gen/Component Definitions/Default.fgl differ
Files template/File Groups/Default.fdf and template-gen/File Groups/Default.fdf differ
Files template/Script Files/Setup.rul and template-gen/Script Files/Setup.rul differ
Files template/Text Substitutions/Setup.tsb and template-gen/Text Substitutions/Setup.tsb differ

newly added, the file groups files

- copy over template-gen/ into template/
$ cp -R template-gen/* template/

- cvs update in the template dir, add new files etc.



- edit template/Component Definitions/Default.cdf in a text editor to configure the 'include in build' templates
  search for [Wolf] and change the line:
  INCLUDEINBUILD=NO
  to:
  INCLUDEINBUILD=<<DO_GAME_WOLF_BOOL_YESNO>>
  
  search for [Wolf\Wolf Editing Media] and change the line:
  INCLUDEINBUILD=NO
  to:
  INCLUDEINBUILD=<<DO_GAME_WOLF_BOOL_FULL_YESNO>>

  that is, main is always installed, and the editing media only in full
  NOTE: IS 6.0 has the nasty habit of changing order in Default.cdf on each save .. makes things harder

- edit 'sub configure_tree' in setup/win32/setup.pl:
  copy from an existing game pack code and adapt
  there's a general boolean, and a full setup boolean
  (search and replace affects Setup.rul and Default.cdf)

  add the corresponding items to
  # set default config
  
  add a corresponding output string under
  print "  DO_CORE          : $DO_CORE\n";

- search for '# set default config' and add the new default entry (default to 0)
as well as the verbosity below

- create a new .cf file

# ET setup

# output dir name
$SETUP_DIR = 'Setup-ET';

$DO_CORE = 1;
$DO_GAME_ET = 1;


- build a new setup using a .cf file.

e.g.

./setup.pl 'C:\\home\\Id' wolf.cf

- load up Setup-Wolf/GtkRadiant.ipl into IS and build it!