MexScript

From XentaxWiki
Revision as of 22:07, 3 January 2006 by Mr.Mouse (talk | contribs) (Introduction)

Jump to: navigation, search

Introduction

BMS stands for Binary MultiEx Scripts. It is the format used by MultiEx Commander (MexCom) to "disassemble" an impressive array of GRAFs. The file format consists of a text file with 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. MultiEx Commander then enables the user to extract and replace resources in these game archives.

In MexCom, users can run their custom made BMS against an archive of their choice. The XeNTaX WIKI and XeNTaX Forum are the places to go to find a huge number of BMS, that could greatly help you understand the way the script works.

MexScriptor is a tool that comes with MexCom that enables one to write BMS 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 an MRF (MultiEx Resource File) file. In the current version of the scriptor, the Help dialog offers a rudimentary overview of the available statements.

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 statements. As it is, the need for a semi-colon will probably be removed in some future update. For now, it will need to be one space away from the last token on a line.

Remember, if you copy a BMS script from the Internet, there will often be extra spaces after the semicolons. These must be removed prior to saving, or an error will be returned.


Comments

Currently, MexCom makes no provisions for comments within a BMS script.

Case Sensitivity

Statements are not case sensitive, so you could for example write IDString as idStrIng. Statements and operators are expected at the correct space-delimited column(s), so there's no need for case-sensitivity here. However, variable names ARE case-sensitive. So, if you declare a variable 'FileOffset', be sure to keep the cases when referencing this variable later on.

Variable manipulation

BMS scripts can declare variables and perform basic arithmetic operations on them and control operations with them.
To declare a new variable simply use them in a Set, Get or SavePos statement for the first time. Variables MUST have been previously declared when used in other statements.

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, For..Next, and the classic If..Then..Else 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? Well, you can use the IF...THEN...ELSE loop and change parameters used in the statement inside the IF control structure.

If..Then..Else

The structure of the If..Then..Else loop is as follows:

 If <var1> <operator> <var2> ;
 (do something)
 Else ;
 (do something else)
 EndIf ;

Thus, an If construction is always terminated with EndIf ; . Note also that Else ; is optional.

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 to
= equal to
>= greater than or equal to 
<= less than or equal to

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 statements between the the For and Next statements for M iterations.

Statement Reference

CLog

CLog name offset size offsetoffset resourcesizeoffset uncompressedsize uncompressedsizeoffset; The CLog statement is similar to the Log statement and signals to the interpreting engine that it has found the information for a particular compressed resource including the resource's name, absolute offset within the GRAF file, the number of contiguous bytes it occupies in the GRAF, the offsets of the aforementioned offset and size parameters in the GRAF, the uncompressed size of the resource (if known) and the position of the uncompressed size of the resource in the archive.

  • 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).
  • uncompressedsize : The size in bytes the resource would occupy after decompression.
  • uncompressedsizeoffset : The offset of the variable in the GRAF that specifies the original size of the resource.

Do

Do ; 

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

FindLoc

FindLoc <var> <datatype> <text/number> <filenumber>

FindLoc searches for a string in the open file and returns its offset in a user variable when found.

Example :
FindLoc MyOffset String RIFF 0 ;

Will look for the string 'RIFF' in file 0 and when found load MyOffset with the offset.

For

Get

GetDString

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 filenumber bytes ;

The IDString statement compares bytes in order to check for an identifying signature. If the signature does not match, the BMS script terminates.

  • filenumber: the ID string applies to a file with this number (0 = main archive). The strings always start at offset 0.
  • 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

ImpType is used to tell MultiEx that a format is supported for Resource replacement, the offsets of the parameters which denote the Size and/or Offset of the Resources should be specified in the Log or CLog statement.

ImpType can be :

    • Standard: tells MultiEx that offsets of ResourceOffset and ResourceSize parameters are specified and will be Logged.
    • StandardTail: tells MultiEx that the Resource info is not in a header, but in a tail, and therefore further upstream than all actual resource data, and tells MultiEx that offsets of ResourceOffset and ResourceSize parameters are specified and will be Logged.
    • SFileSize : tells MultiEx that only offsets of ResourceSize parameters can be specified in the Log statement
    • SFileOff : tells MultiEx that only offsets of ResourceOffset parameters can be specified in the Log statement

Log

Log name offset size offsetoffset resourcesizeoffset ;

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 aforementioned 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. 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 a variable or a constant value.

Next

SavePos

Set

While

String