MexScript

BMS stands for Binary MultiEx Scripts. It is the format used by MultiEx Commander (MexCom) to take apart an impressive array of GRAFs. The file format consists of a text file which a series of instructions to be run through an interpreter. The interpreter uses the instructions to traverse through a GRAF file and search for key data such as names, offsets, and sizes of various constituent files.

Basics

Each line of a BMS script contains a single statement. The statement can be broken down into a series of tokens.

Each line can only contain one statement, but is nevertheless terminated by a semi-colon (;). This is superfluous, yes, but was intented to foresee multi-line statement. As it is, the need semi-colon will probably be deleted in some future update. For now, it will need to be one space away from the last token on a line.

MexScriptor is a tool that comes with MultiEx Commander that enables one to write the scripts and save them as BMS files, which MexCom can read. The scriptor can be found in MexBinderPlus, a BMS-package tool that can save a selection of BMS-es as a MRF file (MultiEx Resource File). In the current version of the scriptor the Help dialog offers some rudimentary overview of the available statements.

Statements

The first token on a statement line indicates what operation that line is to perform. These are the known statement types: Taken from the help in MexScriptor (needs some text-formatting):

• Set

Set
   Set <variable> <variable/number>
   1 (variable number) 2 

• Get

Get
   Get <variable> <datatype> <filenumber>
   NOTE: <filenumber> 0 means the actual datafile
   There's no need to open it first
   NOTE: Datatype string means NULL terminated string

• Open

Open
   Open <directory> <filename> <filenumber>

   <directory> FileDir is the dir of the first file 
    (code 504)
   This is for opening additional files
   <filenumber> must be chosen incrementingly e.g.
   0 is the actual datafile, so any additional files
   get number 1, 2, etc..

• For

   For <variable> = <var/number> To <var/number>
   This is the standard for...next loop

• Next

   Next <variable>
   This variable must equal the first variable used
   in the for syntax

• GetDString

   GetDString <variable> <length (var or num)>
   Get a string of fixed length

• IDString

   IDString <string>

    If the format starts with an Identity string 
    in the archive file, name it here. 

• GoTo

   GoTo <var/number> <filenumber>

    Go to position (variable or number) in file. 

• Math

   math <var> <math spec> <var/number>

   Do a mathematical operation on <var>,
   with specifiers as shown below in this 
   help text. 

• Log

   Log <var name> <var offset> <var size> <var/num offoff> <var/num sizeoff>
    
   You must log the file info you got out of an 
   archive for each individual file in there, 
   for MultiEx Commander. MultiEx Commander uses
   this log to show archive contents and extract/import
   from/into archives. See also CLog. 

• SavePos

   SavePos <var> <filenumber>
    
   This will save the actual filepointer 
   (the current position in a file)
   as a long in a variable of your choice. 

• ImpType

   ImpType <Imptype>
    
   Specify what the condition is for Importing
   into the archive. See below for options. 
   Make sure you give enough info to the 
   Commander in the Log you create to be able 
   to support importing. You need to be able 
   to tell the Commander the exact position
   of the fileinformation such as Offset and Size
   in the archive, so when asked to import the 
   Commander can update these variables in the 
   archive as well, or things get pretty messy. 

• GetCT

   stands for Get Character-Terminated
   GetCT <variable> <datatype> <character> <filenumber>

   Get a variable from a file 
   (a long, byte, string etc. ) 
   that is terminated with a specific character. 
   So, suppose there are strings for filenames 
   that end with the sign @ every time. 
   GetCT FileName String @ 0 
   would then load a string into the variable 
   FileName from file 0 (the archive) until it 
   reached the @ sign in the file. 

• ComType

   Specify the compression type
   Zlib1 : Standard Zlib compression
   ComType <ComType>

• CLog

   when you have specified a compression type you MUST use
   this log event instead of 'Log'
   CLog <var name> <var offset> <var size> <var/num 
   offoff> <var/num sizeoff> 
   <var/num OrSize> <var/num OrSIzeOff>

• FindLoc

   FindLoc <var> <datatype> <text/number> <filenumber>
   Find location of a certain string or number in
   filenumber. That is , only text is regarded as a
   string, only numbers as something you specify (byte, int, long)
   the found location will be stored in <var>iable.
   NOTE: ONLY A STRING PLEASE !!! THE OTHERS HAVE NOT BEEN CHECKED

Comments

Does BMS make provision for comments? - No, it doesn't. Mr.Mouse

Case Sensitivity

Is BMS case sensitive? Does it have to be written as IDString, or will idstring or iDstrINg both work?

Variables

BMS scripts can declare variables and perform basic arithmetic operations on them and control operations with them.

Control Structures

BMS scripts are executed in order from top to bottom unless an alternate control structure is encountered. These control structures include Do..While and For..Next loops.

Question: Is there any equivalent to the 'while {}' C structure or WHILE..WEND structure in BASIC? IOW, a pre-evaluation control structure instead of just the post-evaluation version?

Do..While

The structure of the Do..While loop is as follows:

Do ;
statement 1 ;
--
statement n ;
While condition ; 

Condition compares 2 values, e.g., a variable and a constant, and branches execution back to statement 1 if the condition is evaluated to be true. The available comparison operators are:

< - less than
> - greater than
<> - not equal o
What are all the operators?

For..Next

The structure of the For..Next loop is as follows:

For I = 1 to M;
statement 1 ;
--
statement n ;
Next I ;

This example performs the sequence of statement between the the For and Next statements for M iterations.

Statement Reference

Do

Do ; 

The Do statement marks the beginning of a Do..While control structure.

GoTo

GoTo pos file ;

The GoTo statement causes the interpreter to jump to a specified offset with the GRAF file.

• pos: The offset to jump to.
• file: The open file to perform this command on. Usually this is file 0 (the archive). The BMS is run on a game archive, which is automatically file 0. Any new files opened from within the script with an Open statement will get a new number, in an incrementing way.

IDString

IDString offset bytes ;

The IDString statement compares bytes in order to check for an identifying signature. If the signature does not match, the BMS script terminates. (Right?) --Multimedia Mike 02:21, 31 Dec 2005 (EST)

• offset: The offset where the ID bytes should appear. I am guessing on this one-- it is always 0 in the scripts I have seen but that is there the offsets usually are. --Multimedia Mike 02:21, 31 Dec 2005 (EST)
• bytes: The raw text bytes to compare against. Note that this is not a typical string since it is not enclosed in quotes. It is just raw text bytes which means it cannot have spaces.

Example usage:

IDString 0 BIFFV1 ;

This statement verifies that the first 6 bytes of a file (offsets 0..5) contain the characters "BIFFV1" which is the signature for the Baldur's Gate BIFF format.

ImpType

I have absolutely no clue what this is for... --Multimedia Mike 02:07, 31 Dec 2005 (EST)

Log

Log name offset size offsetoffset filesizeoffset ;

The Log statement signals to the interpreting engine that it has found the information for a particular resource including the resource's name, absolute offset within the GRAF file, the number of contiguous bytes it occupies in the GRAF, and the offsets of the afore mentioned offset and size parameters in the GRAF.

• name: A text string indicating the resourcename. If the resourcename can not be determined, set this to NULL ("").
• offset: The absolute offset of the resource within the GRAF.
• size: The number of contiguous bytes that the resource occupies in the GRAF beginning from offset.
• offsetoffset: the offset of the variable in the GRAF that points to the offset of the resource. This is needed for Replacement support (see ImpType statement).
• sizeoffset: the offset of the variable in the GRAF that is the size of the resource. This is needed for Replacement support (see ImpType statement).

Math

Math var1 op var2 ;

The Math statement performs an arithmetic operation on a variable.

• var1: The variable to be modified.
• op: The arithmetic operation to be performed. Known operations include:
  • += : Add var2 to var1 and store the sum in var1.
  • *= : Multiply var1 by var2 and store product in var1.
  • /= : Integer divide var1 by var2 and store the quotient in var1.
  • -= : Subtract var2 from var1.

• var2: The value to apply to first variable. Note that this can be either an variable or a constant value.