GK3 Tools / Wiki / combine

combine

Authors:

combine.exe is a tool included with GK3 used mostly to create .brn files.

Usage: combine.exe command options

command is one of:
build - build/modify a barn via Sheep
listfunctions - list available functions in a Sheep script
exec - execute Sheep directly, returns integer
extract - extract file(s) from barn(s)
verify - verify data in a barn
dump - dump a barn as text
listsheep - list Sheep commands (regx ok)
helpsheep - get help for Sheep commands (regx ok)
test - test function

So to build or modify a brn file you'll want to use the "build" command.

Usage: combine build sheepfile sheepfunction

sheep_file is the name of a sheep script
sheep_function is optional, and if provided it should be the name of a sheep function to execute. If it's not provided then the tool will execute the first function in the script.

Building from a sheep script

The sheep script tells the tool how to build a brn file. First the script sets a bunch of options and adds files to the barn, then the last thing it does is call CommitWorkOrder() to tell combine.exe to build the actual brn file. Here is a list of sheep commands:

AddSectionExclusion(string sectionID) - Add an exclusion to keep this particular section from appearing in the output barn. Only certain sections may be excluded: 'Relo', 'SrtA', and 'Path' (the 'Path' section will always be added if any path-only files are used).

ResetSectionExclusions() - Reset all specific exclusions of sections. This will force all sections to be included in the output barn during the commit.

AddExclusions(string nameSpec) - Add specifications of files, file types, and paths to exclude during scanning.

AddFilesByPathSpec(string pathSpec) - Add files to the build list by path spec. Normal inclusions and exclusions will apply.

AddFormatSpecs(string nameSpec, string format) - Add specifications of files, file types, and paths to be stored in the barn as the 'format' type, which may be one of: 'native', 'nativelocal', 'zlib', or 'lzo'.

AddInclusions(string nameSpec) - Add specifications of files, file types, and paths to include during scanning.

AddTypeSpecs(string nameSpec, string type) - Add specifications of files, file types, and paths to be stored in the barn as the 'type' type, which may be one of: 'plain' (the default), 'path', or 'exception'.

CreateDatabase(string dbName) - Create a new database and set it to current.

DeleteCurrentDatabase() - Deletes the current database (to save memory). Clears out the current database pointer so you have to select a new one.

DisableFiltering() - Disable all filters for new scans.

EnableFiltering() - Enable all filters for new scans.

RemoveFilter(int cookie) - Remove a filter using the cookie from when it was previously added.

ResetExclusions() - Reset all specific exclusions used during scanning.

ResetFilterSpecs() - Reset all filters used during scanning.

ResetFormatSpecs() - Reset all specific format specs to always use 'native'.

ResetInclusions() - Reset all specific inclusions used during scanning. Note that this will prevent all files from being included unless inclusions are added before the next scan.

ResetTypeSpecs() - Reset all specific type specs to always use 'plain'.

SetCurrentDatabase(string dbName) - Set the database to be the current one. All further database functions will now execute from this one. Does not affect the current database for any pending work orders.

SetZLibCompressionLevel(int level) - Set the current ZLib compression level to use. This may be a value from 1 (fastest) to 9 (highest compression). Default is 6.

SetMinCompressionRatio(int ratioPercent) - Set the current minimum compression ratio to allow (in percent). This may be a value from 0 (no compression) to 100 (infinite compression). Default is 20 percent.

int AddConvertGraphicFilterSpecs(string nameSpec, string destType) - Add specifications of files, file types, and paths to use the 'convert graphic' filter. The 'destType' parameter may be one of the following: 'bmp24', 'png8', 'png16', 'png24', 'mini16', and 'mini24'. Returns a cookie that can be used for filter removal.

int AddDollarSignFilterSpecs(string nameSpec) - Add specifications of files, file types, and paths to use the 'dollar sign finder' filter. Returns a cookie that can be used for filter removal.

int AddLineCountFilterSpecs(string nameSpec) - Add specifications of files, file types, and paths to use the 'line count' filter. Returns a cookie that can be used for filter removal.

int AddModelLODFilterSpecs(string nameSpec, float dist, float error, int numLevels) - Add specifications of files, file types, and paths to use the 'model LOD generation' filter (generate level-of-detail key frames for model). Returns a cookie that can be used for filter removal. Parameters: 'dist' is the distance when LODs kick in, 'error' is some kind of number, bigger means more error, and 'numLevels' is how many key frames to generate.

int AddModelSharedPolyFilterSpecs(string nameSpec) - Add specifications of files, file types, and paths to use the 'model shared poly' filter (add shared poly lists to end of file for faster load in HW). Returns a cookie that can be used for filter removal.

int AddSheepFilterSpecs(string nameSpec, bool syntaxOnly, bool devGrammar) - Add specifications of files, file types, and paths to use the 'sheep' filter. Set 'syntaxOnly' to true to only check the file for syntax errors (do not precompile). Set 'devGrammar' to true to allow a larger development grammar during the filtering. Returns a cookie that can be used for filter removal.

AddInstanceByName(string fileName) - Add a particular file as an (extra) instance to the data section. New instances are always added.

AddInstanceBySet(string setFileName) - Add a particular set of files as (extra) instances to the data section. The set file is a list of filenames, separated by newlines, that will be added to the barn in the same order they are in the file. New instances are always added.

AddInstancesByNameSpec(string nameSpec) - Add files to the data section as instances. Only files that have not already been instanced will be added. To force a new instance use 'AddInstanceByName()'.

AddRemainingInstances() - Add all remaining files to the data section that have not already been instanced.

CreateBarnWorkOrder(string fileName) - Create a new work order for a new barn using the given filename. Automatically overwrite any barn that already exists with the same name.

CreateBarnWorkOrderX(string fileName, string prefix, string postfix) - Create a new work order for a new barn using the given filename. Automatically overwrite any barn that already exists with the same name. The prefix and postfix strings are used.

SetBarnName(string barnName) - Change the current work order to output with a new name for the barn file. Note that this will not change the name of the work order.

SetContentBuild(int build) - Set the content build number to use for this barn.

SetExeBuild(int build) - Set the EXE build number to use for this barn.

SetIndexID(string id, string description, int discNumber) - set the ID and description to use for the data directory on this barn. 'id' must be exactly four characters long and must be unique across barns. 'discNumber' is which disc the barn may be found on.

SetIndexPriority(string priority) - set the internal priority for this index, which may be one of the following: 'factory', 'patch', 'customlow', and 'customhigh'.

AddToIndex(string fileName) - Add all the data directories in the given barn to the current new index work order.

AddToIndexX(string fileName, string prefix, string postfix) - Add all the data directories in the given barn to the current new index work order. The prefix and postfix strings are used.

SetCheckIndexDups(bool set) - Set the current work order to check all indexed barns against the entire database for duplicates.

SetVerifyOnCommit(bool set) - Set the current work order to check the data integrity of the current barn when it is constructed.

Call(string functionName) - Call a Sheep function within the current Sheep file. This is exactly the same as 'CallSheep()' except you don't need to worry about the filename.

CallDefaultSheep(string sheepFileName) - Call the first Sheep function in the file. This is the same as 'CallSheep()' except that the function name is not required. This function just finds the first Sheep function in the file and executes it.

CallSheep(string sheepFileName, string functionName) - Call a Sheep function. The 'sheepFileName' is the name of the .shp file without the extension, and the 'functionName' is the name of the function within the Sheep file. Including the trailing '$' on the function name is a good idea for consistency, but it's not absolutely necessary).

strempty(string str) -

strcmp(string l, string r) -

stricmp(string l, string r) -

strlen(string str) -

PrintFloat(float value) - Prints a floating point number to the 'SheepScript' stream.

PrintInt(int value) - Prints an integer to the 'SheepScript' stream.

PrintIntHex(int value) - Prints an integer to the 'SheepScript' stream as a hexadecimal value.

PrintString(string message) - Prints a string to the 'SheepScript' stream.

ChangeDir(string directory) - Change the current working directory to 'directory'.

FileDelete(string fileName) - Delete the given file.

int GetChar() - Get a character input from the keyboard.

int GetTickCount() - Get the number of milliseconds since Windows was started.

int IsComputerName(string computerName) - Returns bool (1 or 0) value of whether or not this computer's name matches 'computerName'.

int ReadExeBuild(string exeFileName) - Read the build number from the given EXE filename and return it.

AbortWorkOrder() - Abort the current work order and nuke it.

CommitWorkOrder() - Commit the current work order (force it to execute). This will result in the work order being deleted as well.

SetCurrentWorkOrder(string orderName) - Set the work order to be the current one. All further work order functions will now execute from this order.

SetDumpOnCommit(bool set) - Set whether or not the barn should be dumped to a text file when it is committed.

int AddFileSizes(string treePath) - Add up the total sizes of files in the entire tree.

BuildRandomFile(string outFileName, int outFileSize) - Build a file of the given size and fill it with random data.

GenerateCDEnforcer(string outFileName, string scriptName, string searchPath) - Generate a CD Enforcer config file to the given out filename. The 'scriptName' is the prototype to build the config file from, and 'searchPath' is where to search for the files to compute sizes from.

int GetFileSize(string fileName) - Return the size of the file.

PatchCDEnforcer(string exeFileName, string enforcerFilename) - Patch the resources of the given EXE filename with the encrypted contents of enforcerFilename. Does not verification on the source or dest file. Replaces an existing patch if there is one.

Example

Here is an example of a minimal script that will generate a barn file. It will write a barn file called "test.brn" in the "c:\game" directory containing all files in the "c:\game\data" directory.

symbols
{
    string BarnName$ = "test";
    string OutputDir$ = |<c:\game>|;
    string InputDir$ = |<c:\game\data\*>|;
}

code
{
    main$()
    {
        ChangeDir(OutputDir$);

        CreateDatabase(BarnName$);
        CreateBarnWorkOrder(BarnName$);

        ResetSectionExclusions();
        AddSectionExclusion("Relo");
        AddSectionExclusion("SrtA");
        SetDumpOnCommit(1);

        SetExeBuild(1);
        SetContentBuild(1);
        SetIndexID("Test", "Test barn", 0);

        AddInclusions("*");
        AddFilesByPathSpec(InputDir$);

         AddRemainingInstances();
        CommitWorkOrder();
    }
}

GK3 Tools Wiki

combine

Building from a sheep script

Example