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:

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