Readme for the SE4 Templatizer version 3.0.0

What is the SE4 Templatizer?

The SE4 Templatizer is a tool which allows for quick, easy creation of entire families of components, facilities, and other items for the computer strategy game Space Empires IV by Malfador Machinations.

What do I need to run the SE4 Templatizer?

You will need two things to run the SE4 Templatizer:

• The Java runtime, version 5
• The free GNU calculator tool calc

How do I use the SE4 Templatizer?

First, you must create a template file. A template file looks exactly like a standard SE4 data file, except that the *BEGIN* and *END* tags are not required, anywhere in a field value (including in the special fields noted below) you can use a formula (enclosed in square brackets), you may use C++-style "//" comments, and there are some extra optional fields (which may not contain spaces or mathematical symbols in their names), as noted here:

• The "*" field: A "*" at the beginning of a field name defines a global function. Global functions may be used anywhere in the file after they are defined. An example of a global function is "*add(x,y,z) := x+y+z". The mnemonic for the global function symbol is that the "*" is radially symmetric like a globe.
• The "@" field: An "@" at the beginning of a field name defines a local function. Local functions act just like global functions, except they cannot be used after the record they are defined in ends (there is a blank line). Local functions override global functions with the same name. The mnemonic for the local function symbol is that the "@" stands for "at", which refers to a location.
• The "#" field: A "#" at the beginning of a field name defines a tech grid area. Tech grid areas are the meat of the Templatizer; they are what define the vast arrays of records the Templatizer is capable of producing. Tech grid areas take two values, which are separated by the ".." symbol (two periods). They apply only to the record in which they are located, and should be placed at the top of the record. You may define any number of tech grid areas you want for any template. A sample tech grid area is "#dmgtech := 1..5". Note that tech grids are multiplicative; the more you add to any given template, the longer it will take to generate the end result. Also note that Space Empires IV has a limit of 65,536 records in any given data file (thanks to Suicide Junkie for figuring that out); while that may sound like a lot, it is easy to go overboard with tech gridding - one record with eight tech grid areas with four levels each will completely fill up this capacity! (1 * 4 ^ 8 = 65,536) The mnemonic for the tech grid area symbol is that the "#" looks like a grid.
• The "~" field: A "~" at the beginning of a field name (actually nothing is required but the "~") defines a weapon component's minimum and maximum range. It is required only by records that define weapon components. Like a tech grid area, the weapon range field takes two values separated by "..": the minimum and the maximum effective range. Note that a weapon's actual range may be less if the damage values come out to zero or less (negative values are automatically zeroed).

Once you have created your template file, you need to then start the Templatizer and select your template file from the dialog box. You will then be prompted for a new file to save the output under. Once you have entered this file name, the Templatizer will then begin generating the output SE4 data file from your template file.

Also of note is the file "templatizer-functions.txt", which defines several useful functions for Templatizer users. You may edit this file in order to define your own functions; the syntax is the same as that of the calc utility, as the contents of the file are fed directly into calc for every calculation.

Who wrote the SE4 Templatizer?

The SE4 Templatizer was written by Ed Kolis, whose email address is koliset@fuse.net and whose web address is http://home.fuse.net/koliset.

What caveats are there when I use the SE4 Templatizer?

• If the program hangs at a seemingly random point, it is likely that you are calling an undefined function; the program is currently not able to handle calc giving no output through the standard output stream. Until this problem is fixed, you will need to find the offending function call and either define, rename, or remove it. A hint: look at the record on which the program crashed, and remember that "records" containing only global functions still count as records. Alternatively, it is possible that you have defined a function somewhere which is not in valid calc syntax. In that case you will need to find and remove the offending function or fix the syntax; please see the documentation for calc if you wish to do so.
• If you are using Windows and your Windows calculator pops up, you will need to edit the enclosed "calc-path.txt" file to point to the location of the calc utility. Alternatively, you can rename your Windows calculator executable, but that might just break something in Windows...
• If your functions aren't working, make sure they are not enclosed in square brackets. Calc uses square brackets for lists and matrices, and enclosing function definitions inside them is not recommended.

What restrictions are there on my use of the SE4 Templatizer?

The SE4 Templatizer is released under the terms of the GNU Lesser General Public License, a copy of which should have been included with the Templatizer.

What is the history of the SE4 Templatizer?

• v3.0.4 (24 Feb 2005)
  • Fixed - Linux shell script to run the templatizer was using DOS-style argument lists.
  • Fixed - Carriage returns are now added along with newlines at the end of each output line; the lack of carriage returns was making the previous outputs unreadable to Notepad and to SE4.
• v3.0.3 (22 Feb 2005)
  • Fixed - Calling a function which appears earlier in the alphabet but later in the template file than another function will no longer produce "undefined" errors in the output file.
  • Added - The program can now take up to two command-line parameters. The first specifies the input file name; the second specifies the output file name.
  • Changed - The output file dialog box now defaults to the directory in which the input file is located.
  • Fixed - "Too many open files" error when processing multiple templates within a template file.
  • Fixed - The value in calc-path.txt is now actually used.
  • Fixed - Tech grid areas with comments on same line now work properly.
  • Fixed - Functions that depend on tech grid areas now work properly.
  • Changed - Distributed as a .zip file instead of a .tar.bz2
  • Added - Batch file and shell script for running the templatizer without specifying the Java runtime on the command line.

Versions 1.x.x and 2.x.x were based on my own expression evaluator (EEE) instead of calc and written in C# instead of Java.

Have Fun!