ROMulan Data Extractor/Injector

ROMulan Data Extractor/Injector

ROMulan is a tool designed to provide a simple way to extract data from program files for manipulation by an external program, and to then re-integrate the data regardless of its new size. Its primary use is to allow for the editing of video game data outside of the program that uses it. After editing, the data can be re-inserted into the original program even if it has grown larger than the area it used to occupy, as long as it does not increase the size of the original file beyond the specified maximum file size.

General Usage

Command/Directive Entry

Batch Command Files

GetPath PromptString
SrcPath PathName
DestPath PathName
MakePath PathName
GetFile PromptString
LoadFile FileName
Extract DataStart DataSize FileName (EndianSwitch)
Copy SourceFileName DestFileName (EndianSwitch)
Extern FileName Parameters...
WorkPath PathName
Print String
Pause String
RunBatch FileName
LoadInject FileName
AddInject FileName
RunInject InputFileName OutputFileName

Injector Files

Define String Parameters...
Translate StartAddr EndAddr Offset
Dispose StartAddr EndAddr
MaxSize Size
StartSeg (Name) (Offset (Size)) (Endianness)
EndSeg
(Label:)
include FileName (EndianSwitch)
BYTE Data
WORD Data
DWORD Data
String String

License

Official Site and Discussion Forum

Credits

General Usage

Command/Directive Entry

Batch Command Files

The "Batch Command File" is a text file that contains a series of commands for ROMulan to process. This file is used mostly to perform data extraction or to initiate injection, but may also perform certain other functions:

Multiple source files can be used for extraction, and multiple injectors can be run with different target files by a single Batch file.

External programs may be called by the Batch file to manipulate the data at any time, such as after extraction and prior to editing, or after editing and prior to injection.

Subfolders for the extraction process may be created by the Batch file.

The Batch file may copy files from the source location to the destination location.

The endianness of the data can be inverted on a WORD or DWORD basis during copy or extraction.

The user can be prompted to select the files or folder locations to be used throughout the process.

The following commands are available for the Batch Command File:

GetPath PromptString

Prompt the user to select a path/folder for an operation. The parameter "PromptString" is a string that will be printed to tell the user what they are being asked for

GetPath "Please select the path containing the source data files"

SrcPath PathName

Set the path/folder used for source file operations. The parameter "PathName" can be a string naming the path to use, or the identifier "#Got" can be used to specify the use of the last path selected by the command "GetPath". This sets the path associated with the #Src identifier

SrcPath "Subfolder" SrcPath "c:/folder/subfolder" SrcPath #Got

DestPath PathName

Set the path/folder used for destination file operations. The parameter "PathName" can be a string naming the path to use, or the identifier "#Got" can be used to specify the use of the last path selected by the command "GetPath". The desired folder must already exist. This sets the path associated with the #Dest identifier

DestPath "Subfolder" DestPath "c:/folder/subfolder" DestPath #Got

MakePath PathName

Create a new path/folder. The parameter "PathName" is a string naming either a subpath relative to the destination path, or the full name of a new absolute path. If the path/folder already exists, this command has no effect

MakePath "SubFolder"

GetFile PromptString

Prompt the user to select a file for an operation. The parameter "PromptString" is a string that will be printed to tell the user what they are being asked for

GetFile "Please select the source data file"

LoadFile FileName

Load a source file for data extraction. The parameter "FileName" can be either a string naming a file relative to the source path or the full path/name of a file in a fixed location, or the identifier "#Got" can be used to specify the use of the last file selected by the command "GetFile"

LoadFile "RelativeFile.ext" LoadFile "c:/Folder/SubFolder/File.ext" LoadFile #Got"

Extract DataStart DataSize FileName (EndianSwitch)

Extract a section of data from the loaded source file. The parameter "DataStart" is a decimal/hex value specifying the starting location of the desired data. "DataSize" is a decimal/hex value specifying the size of the data to extract. "FileName" is a string naming a file relative to the destination path, or the full path/name of a file in a fixed location, in which to place the data. The optional parameter "EndianSwitch" can be either the identifier "Swap16" to invert the endianness of the data on a WORD basis, or "Swap32" to invert the endianness of the data on a DWORD basis. To preserve the endianness of the data, do not include this parameter

Extract $1000 $10 "RelativeFile.ext" Swap16 Extract $10 $1000 "c:/Folder/SubFolder/File.ext" Swap32 Extract $256B $FF "SubFolder/RelativeFile.ext"

Copy SourceFileName DestFileName (EndianSwitch)

Copy a file from one location to another. The parameter "SourceFileName" is a string naming a file relative to the source path, or the full path/name of a file in a fixed location. The parameter "DestFileName" is a string naming a file relative to the destination path, or the full path/name of a file in a fixed location. For either parameter, the identifiers "#Got", "#Src", or "#Dest" can be inserted at the beginning of the strings to specify a different parent path for a relative path/filename than the default for that parameter. The optional parameter "EndianSwitch" can be either the identifier "Swap16" to invert the endianness of the file on a WORD basis, or "Swap32" to invert the endianness of the file on a DWORD basis. To preserve the endianness of the file, do not include this parameter

Copy "SrcFile.ext" "DestFile.ext" Copy "#Dest/SrcFile.ext" "#Src/DestFile.ext" Swap16 Copy "#Got/SrcFile.ext" "DestFile.ext" Swap32

Extern FileName Parameters...

Call an external program. The parameter "FileName" is a string naming a file relative to the path containing the Batch file being run, or the path/name of a file in a fixed location. "Parameters..." are a series of strings providing the command-line parameters to be used by the external program. The identifiers "#Got", "#Src", or "#Dest" can be inserted at the beginning of any of the strings that represent a path/filename to insert the path associated with that identifier before the rest of the string. Be aware that some external programs may not allow foreward slash ("/") in path strings, so it may be necessary to use backslash, which must be represented as double-backslash ("\\")

Extern "SomeProgram.exe" "Param1" "Some.fil" "1234" Extern "compress" "#Src\\Data.bin" "#Dest\\Data.bin"

WorkPath PathName

Set the "Working Path", the path in which all following "Extern" calls will take place. The parameter "PathName" is a string naming either a subpath relative to the current "Working Path", or the full name of an absolute path. The identifiers "#Got", "#Src", or "#Dest" can be inserted at the beginning of (or instead of) the string to insert the path associated with that identifier before the rest of the string

WorkPath "SubFolder" WorkPath "#Dest/SubFolder" WorkPath "#Src"

Print String

Send the string given by the parameter "String" to the message system

Print "X complete, now processing Y..."

Pause String

Send the string given by the parameter "String" to the message system and pause processing until the user presses a key

Pause "Please press any key to continue"

RunBatch FileName

Call another Batch file. The parameter "FileName" is a string naming a file relative to the path containing the Batch file being run

RunBatch "ExtLev1.txt" RunBatch "Injector/InjBatL2.txt"

LoadInject FileName

Load an Injector file, removing any that were previously loaded. The parameter "FileName" is a string naming a file relative to the path containing the Batch file being run

LoadInject "Inject.txt" LoadInject "Injector/InjLev1.txt"

AddInject FileName

Load an Injector file, adding to any that were previously loaded. This is useful for keeping separate injector files for different data types, or for combining injectors for different data areas created by different authors at the time of injection. The parameter "FileName" is a string naming a file relative to the path containing the Batch file being run

AddInject "XtraStuf.txt" AddInject "Injector/MoreStuf.txt"

RunInject InputFileName OutputFileName

Run the loaded Injector file(s). The parameter "InputFileName" is a string naming the unaltered file in which to inject the data. "OutputFileName" is is a string naming the file in which to save the results. The identifiers "#Got", "#Src", or "#Dest" can be inserted at the beginning of the strings to insert the path associated with that identifier before the rest of the string, or the identifier "#Got" may be used in substitution of a full path/file name. Otherwise, if a relative path is used, it is assumed to be relative to the path containing the Batch file being run

RunInject "SrcFile.ext" "DestFile.ext" RunInject "#Src/SrcFile.ext" "#Dest/SrcFile.ext" RunInject #Got #Got

Injector Files

The "Injector File" is a text file that contains commands and directives that control the re-insertion of altered data into the original file. In some cases, altered data may grow in size, and thus, cannot be placed at its original location in a precompiled program file. To accommodate this, ROMulan is capable of relocating the data, assuming it is provided with the proper information to do so.

This file instructs ROMulan on how large the file can be and what parts of the file can be overwritten by the incoming data in case of relocation, and how to generate offsets and addresses when replacing references to the data with values representing its new location. Data may be entered manually as decimal or hexadecimal values using data directives, or may be taken from a file by using the "include" directive, but it must appear inside a "Segment".

"Segments" are used to group data together, and "Labels" are used as pointers to the starting location of any individual data. Segments may be given a specific location at which to be inserted into the destination file, or, if a location is not specified, ROMulan will attempt to place it either within an area of the file noted by the "Dispose" directive if it fits within the given range, or at the end of the file if it will not expand the file beyond its given maximum size.

In order for the program being altered to know where relocated data can be found, all references to that data must be replaced using segments containing data that references the starting location in the same format as the original references, that are set to overwrite the original reference. Both Labels and Segments can be used by name when it is necessary to insert values representing their location, and may be used with mathematical operators to generate offsets, or add other data values to the upper portion of the address value when the program expects them to be stored as one.

The value generated when a Segment or Label name is used is automatically adjusted by ROMulan when "Translate" directives are used to specify which address ranges are assigned address space that does not directly correspond with the layout of the program/data file itself while the program is being run.

The following directives are available for the Injector File:

Define String Parameters...

Define ThisValue $FF
Define ThisExpression $20 + ThisValue

Translate StartAddr EndAddr Offset

Translate $000000 $080000 $880000

Dispose StartAddr EndAddr

Dispose $22E974 $22F1AC

MaxSize Size

MaxSize $400000

StartSeg (Name) (Offset (Size)) (Endianness)

StartSeg ThisSeg $1000 $200 Big_Endian
StartSeg $2345 Little_Endian
StartSeg ThisSeg
StartSeg Little_Endian
StartSeg $2345
StartSeg ThisSeg $2345
StartSeg ThisSeg Little_Endian
StartSeg

EndSeg

EndSeg

(Label:)

LabelName:
LabelName: BYTE $FF
LabelName: include "File.ext"

include FileName (EndianSwitch)

include "RelativeFile.ext"
include "SubFolder/RelativeFile.ext" Swap16
include "C:/Folder/SubFolder/File.ext" Swap32

BYTE Data

BYTE $FF
BYTE $10, $AB, $FF
BYTE $10+DefineName
BYTE LabelName2-LabelName1
BYTE LabelName
BYTE LabelName+DefineName

WORD Data

WORD $FFFF
WORD $10, $23, $FFFF
WORD $10+DefineName
WORD LabelName2-LabelName1
WORD LabelName
WORD LabelName+DefineName

DWORD Data

DWORD $FFFFFFFF
DWORD $10, $ABCD, $FFFFFFFF
DWORD $10+DefineName
DWORD LabelName2-LabelName1
DWORD LabelName
DWORD LabelName+DefineName

String String

String "Replacment Text"

License

Any material whose creation is due in any way at all to ROMulan may not be exchanged for profit, regardless of the content of the material or the authors' legal status in relation to any existing intellectual property. In order to use ROMulan for any profitable and/or commercial purpose, special license must be obtained from ROMulan author Stealth.
Any projects making use of ROMulan should in some way credit the utility and/or Stealth. It is preferable, at minimum, that this reference be made in addition to any other existing credits listing under a heading such as "Utilities".
Any redistribution must be made freely, requiring no form of compensation whatsoever, and may not be included as part of any sort of package.
Any redistribution must not be modified; ROMulan may only be redistributed as it was originally packaged. The archive, its file contents, and the files themselves must not be modified in any way, and may not be accompanied by any material that was not a part of the original distribution.

Official Site and Discussion Forum

ROMulan program and script updates will be noted on the Organized Chaos homesite:

http://stealth.hapisan.com

http://stealth.hapisan.com/ROMulan

http://stealth.hapisan.com/Forum

Credits