infodump for nba jam source code stuff

gistfile1.txt

NBA Jam Tournament Edition
==========================
This is an attempt to get the NBA Jam Tournament Edition source code into
a buildable state.

The original code is available from:
https://github.com/historicalsource/nba-jam-tournament-edition

Currently, the original, non-Tournament Edition NBA Jam is not accounted for.

The NBA Jam source code released under the historicalsource github account is
from some point during the development of NBA Hangtime. There is an "old"
directory, but it appears to have code from Tournament Edition.

Requirements
------------
* DOSBox or a computer running DOS
This is for older tools that don't have a modern equivalent at the moment.

* gspa.exe, gsplnk.exe
These are the assembler and linker for the GSP/TMS34010.

This repository currently assumes the use of the files found in the Revolution X
repository: https://github.com/historicalsource/revolution-x

You may be able to get away with using later versions, but you might need to
edit a few things.

* OPUS MAKE
"oh, I have GNU Make, will that work?"
Well, that probably won't work; not without some changes, anyways.

Like the assembler and linker, this has been sourced from the Revolution X repo.

* LOADIMG
This tool is responsible for building the game's image library.

The NBA Jam Tournament Edition source code references various files that are not
included in the repository. These are files such as "imgtbl.glo", "bkgdtbl.glo",
and so on. 

There are two versions of this program available. It's not known what the
actual differences are, but I'm assuming the larger version includes debugging
information. (Or rather, I'm *hoping* that's the case.)

The smaller version ("load2.exe") is available from the NBA Hangtime repository
in the "NEWLOAD2" directory:
https://github.com/historicalsource/nba-hangtime
There is a help file, "load2.hlp", in this repository, along with example
.lod scripts from Mortal Kombat.

The larger version ("load20.exe") is found in the "IMG" directory of the
Revolution X repository.

* preasm
...which doesn't exist in any of the extant source repositories.

From what I can tell, prefixing a value with '>' means to put a 'H' at the end.
Possibly also adds a leading zero to any value starting with a hex character.

Prefixing a label with '#' does something as well... probably a local label?
Since all the .axx files are deleted, we don't really have an idea of what
the actual transforms are.

Notes
-----
* Only relevant files are included.
For the source code, this is any file mentioned in the linker script (BB.CMD).

One notable exception to this rule is "d3.asm", also known as the "tank game".
"scream.asm" is not yet removed, since it may still be used...

Removed files:
- apunzip.asm
- rackup.asm
- unzip.asm

Instructions
------------
The source code relies on some files created by LOADIMG, so that's our first step.

Dealing with this program is a pain, as it normally assumes you're connected to
real hardware (T-Unit, Y-Unit, whatever). To get around this, use the /X parameter.

LOADIMG also makes some assumptions about default directories that we need to
handle... It's probably best to quote "load2.hlp":

---
Valid <flags>...

  /X  -DO NOT download to GSP. (If not present, it does)
  /Dx -Specify directory for .lod file (see below for 'x' description)
  /Tx -Build image table files (see below for 'x' description)
  /Fx -Build raw file (see below for 'x' description)
  /Ox -Override dir. for all files in .lod file (see below for 'x')
  /Ux -Override dirs. within all Universe files (see below for 'x')

NOTE! The above flags are independent and may be used in any combination.

  /Rx -Load from a raw image file. (see below for 'x' description).
  /H  -Print an explanation of .lod file directives.
  /V  -Verbose mode, report lots of stuff.
  /I  -Write background data to image roms
  /B  -Make Bits Per Pixel based on Image data, not Palette size
  /P  -Pad images to multiple of 4 bits
  /L  -aLign images to 16 bit boundaries
  /A  -Append to (i.e. do not erase and recreate) default table files.
  /S  -Write sequences in .uni files to univseq.new
  /E  -ED adjustment (Dual banked image memory (not available in load20)

The T,F,R,D,O and U options use a secondary flag shown above as 'x'.
  If x is I, the affected file uses IMGDIR.
  If x is S, the affected file uses SRCDIR.
  If x is C, the affected file uses the current dir.
  If x is =, supply a directory on the command line.
---

NBA Jam Tournament Edition uses multiple .LOD files, so we need to be careful
about build order and overwriting data.

Originally, I was able to get "bb.lod" built using the following command:
load2 bb /X /DC /FC /TC

However, you may also need to use "/I", "/P", /"L", and/or "/A".

The current assumed order, which may be wrong:
- bb.lod
- bb2.lod
- bb3.lod
- bbmug.lod
- bbpal.lod
- bbtest.lod
- bbtst.lod

The data found in the .IRW files is mostly close to the final graphics ROM
output, but it contains a header with currently unknown information.

The graphics ROMs must also be split between four files...
First file has the first byte, second file has the second byte,
third file has the third byte, and fourth file has the fourth byte.

Repeat for the rest of the file, looping back to the first file after the
fourth byte.

Graphics ROM set 1: ug14, uj14, ug19, uj19
Graphics ROM set 2: ug16, uj16, ug20, uj20
Graphics ROM set 3: ug17, uj17, ug22, uj22
Graphics ROM set 4: ug18, uj18, ug23, uj23

Graphics ROM set 1 starts with data from BB2.IRW, 0x200000 bytes worth (out of 0x3BF110 total)

info.txt

https://github.com/historicalsource is good

there are three sources I care about at the moment:
* nba-jam
* nba-jam-tournament-edition
* open-ice

they are talked about at length below
================================================================================
[nba-jam]
You'd think this was NBA Jam, but it appears to be in the process of being
converted to NBA Hangtime... The "OLD" folder contains NBA Jam source code, but
it's actually NBA Jam Tournament Edition (version undetermined).

You probably also want IMG/OLD instead of just IMG... I have no way of viewing
these files at the moment, though.

-------------+-----------------------------------------------------------------------
Filename     | Description
-------------+-----------------------------------------------------------------------
APUNZIP.ASM  | "Amusement Park Unzipper"; used for movie sequences? (Halftime Report)
ATTRACT.ASM  | "attract mode"
BB.ASM       | "NBA JAM Basketball game program", "first game module" (description from bb.cmd)
BB.CMD       | "Game linker command file"
BB2.ASM      | "Basketball game program"; looks like some small debugging thing
DRONE.ASM    | "basketball drone code", NBA Jam version?
DRONE2.ASM   | "basketball drone code", "Smarter for tournament ed."
DUNKS.ASM    | dunk data definitions?
GAME.EQU     | "All .equ constants to be used throughout the game"
IMGPAL.ASM   | image palettes
IMGPAL2.ASM  | image palettes part 2
IMGPAL3.ASM  | image palettes part 3
IMGPALM.ASM  | image palettes
IMGPALP.ASM  | image palettes
IMGTBL.ASM   | image table(s)
MAKEFILE     |
PLYR.ASM     | "basketball player code"
PLYR.EQU     | "Player/game constants and structures"
PLYR2.ASM    | "basketball player code"
PLYR3.ASM    | "basketball player code"
PLYRAT.ASM   | "basketball player code"; player attributes
PLYRAT2.ASM  | "basketball player code"; player attributes part 2
PLYRDSEQ.ASM | "basketball plyr sequence code"; dunks?
PLYRLSEQ.ASM | "basketball plyr sequence code"; layups?
PLYRSEQ.ASM  | "basketball plyr sequence code"
PLYRSEQ2.ASM | "basketball plyr sequence code"
PLYRSTND.ASM | "basketball plyr sequence code"
RECORD.ASM   | "CMOS records etc"
SCORE.ASM    | "score stuff"
SCORE2.ASM   | "score stuff"
SELECT.ASM   | "name & team selection"
SELECT2.ASM  | "name & team selection"; this one has the initials + birthdates of the hidden players
SOUNDS.ASM   | "sound processor"
SPEECH.ASM   | "announcer speech etc..."
STRING.ASM   | "string printing stuff"
TEXT.ASM     | "font tables"
-------------+-----------------------------------------------------------------------

Many files referenced in the source are not included in this directory.
It's assumed that you can use the ones from the main folder as-is, but I have
not checked that. Worst case scenario, you can probably grab them from Jam TE.

================================================================================
[nba-jam-tournament-edition]
assumed to be a more complete version of the "OLD" folder found in nba-jam.

-------------+-----------------------------------------------------------------------
Filename     | Description
-------------+-----------------------------------------------------------------------
ADJUST.ASM   | adjustments menu
APUNZIP.ASM  | "Amusement Park Unzipper"
ATTRACT.ASM  | "attract mode"
AUDIT.ASM    | "audits and ajustments handling"
AUDIT.EQU    | audit equates
BAKGND.ASM   | "background handlers", "background generator"
BB.ASM       | "NBA JAM Basketball game program", "first game module"
BB.CMD       | "Game linker command file"
BB.HDR       | ?????
BB.TVS       | information for ToddView?
BB2.ASM      | "Basketball game program"; looks like some small debugging thing
BGNDPAL.ASM  | background palettes
BGNDTBL.ASM  | background tables
BKUP.BAT     | backup script using xcopy
COLL2.ASM    | "collision routines"
D3.ASM       | "Mega 3d polygon code"; probably tank game
DIAG.ASM     | board diagnostics
DIPEQU.ASM   | dipswitch equates
DISP.EQU     | "Display proc equates"
DRONE.ASM    | "basketball drone code"
DRONE2.ASM   | "basketball drone code", "Smarter for tournament ed."
DUNKS.ASM    | dunk data definitions?
GAME.EQU     | "All .equ constants to be used throughout the game"
GSP.EQU      | graphics hardware-related equates?
HSTD.ASM     | "robo high-score-to-date management"
IMGPAL.ASM   | image palettes, "image palettes generated by loadimg"
IMGPAL2.ASM  | image palettes part 2
IMGPAL3.ASM  | image palettes part 3
IMGPALM.ASM  | image palettes
IMGPALP.ASM  | image palettes
IMGTBL.ASM   | image table(s), "image stub"
LINK.EQU     | ???
MAC2.ASM     | various macros?
MAIN.ASM     | "initialization and interrupts"
MAKE.INI     |
MAKEFILE     |
MENU.ASM     | "test menus"
MENU.EQU     | menu equates
MPROC.ASM    | "GSP multi-processing system", "multi-tasker"
MPROC.EQU    | equates and macros for mproc
NDSP1.ASM    | "GSP display processor V 4.3", "image handler"
PAL.ASM      | "palette allocator and fader control"
PATCH.ASM    | ???
PLYR.ASM     | "basketball player code"
PLYR.EQU     | "Player/game constants and structures"
PLYR2.ASM    | "basketball player code"
PLYR3.ASM    | "basketball player code"
PLYRAT.ASM   | "basketball player code"; player attributes
PLYRAT2.ASM  | "basketball player code"; player attributes part 2
PLYRDSEQ.ASM | "basketball plyr sequence code"; dunks?
PLYRLSEQ.ASM | "basketball plyr sequence code"; layups?
PLYRSEQ.ASM  | "basketball plyr sequence code"
PLYRSEQ2.ASM | "basketball plyr sequence code"
PLYRSTND.ASM | "basketball plyr sequence code"
RACKUP.ASM   | "total carnage game program" (total carnage leftover, I suppose)
RECORD.ASM   | "CMOS records etc"
SCORE.ASM    | "score stuff"
SCORE2.ASM   | "score stuff"
SCREAM.ASM   |
SELECT.ASM   | "name & team selection"
SELECT2.ASM  | "name & team selection"; this one has the initials + birthdates of the hidden players
SHAWN.HDR    | "Macro defines, include after mproc.equ"
SOUNDS.ASM   | "sound processor"
SPEECH.ASM   | "announcer speech etc..."
STRING.ASM   | "string printing stuff"
SYS.EQU      | "T/Z-UNIT SYSTEM SPECIFIC EQUATES"
TEST.ASM     | "test program"
TEXT.ASM     | "font tables"
UNZIP.ASM    | "pkzip unzipper"
UTIL.ASM     | "utility subroutines"
-------------+-----------------------------------------------------------------------

the IMG folder has some very interesting files, including "KENGRIF.IMG".

A lot of .glo files are referenced, but not included:
- bgndtbl.glo ("background equates"; built as a part of bb.lod)
- imgtbl.glo (default global image table; various .lod scripts build to this)
- imgtbl2.glo
- imgtbl3.glo (built as a part of bbmug.lod)
- imgtbl4.glo (built as a part of bb3.lod)
- imgtblm.glo
- imgtblp.glo
- mainimg.glo
they are probably built from the .lod files in the IMG directory

.glo files commented out:
- imgcrwd.glo (bb.asm)
- imgtbl2.glo (diag.asm)

Referenced by files, but not included:
- ap.h (apunzip.asm)
- string.h (apunzip.asm)
- arrow.tbl (score.asm) [bb.lod]
- ball.tbl (plyr2.asm) [bb2.lod]
- city.tbl (score.asm) [bb.lod]
- court.tbl (bb.asm, bb2.asm) [bb.lod]
- crowd.tbl (bb.asm) [bb2.lod]
- fireseq.tbl (plyrdseq.asm, plyrseq2.asm) [bb3.lod]
- frame.tbl (unzip.asm) [???]
- layup.tbl (plyrlseq.asm) [bb2.lod]
- mugshot.tbl (select2.asm) [bbmug.lod]
- pass.tbl (plyrseq2.asm) [bb2.lod]
- plyrdseq.tbl (plyrdseq.asm) [bb2.lod]
- plyrd2se.tbl (plyrlseq.asm) [bb2.lod]
- plyrhd.tbl (plyrat2.asm) [bb.lod]
- plyrhd2.tbl (plyr3.asm) [bb.lod]
- plyrhd3.tbl (plyr3.asm) [bbmug.lod]
- plyrhd4.tbl (plyrat.asm) [bb3.lod]
- plyrseq.tbl (plyrseq.asm) [bb2.lod]
- plyrseq2.tbl (plyrseq2.asm) [bb2.lod]
- stand.tbl (plyrstnd.asm) [bb.lod]
- text.tbl (text.asm) [bb2.lod]

load2 bb /X /TC
this command builds bb.lod, which results in 14 new files.
ignore L2TEMP, and it's 13. see below for full details

if you're going to run this in dosbox, you might want to up the CPU cycles,
since big .lod files take longer to process.

load2 bb /X /FC
attempts to build "bb.irw", but load2 errors out saying
"ERROR *** Cannot create temp file, save_temp_file!!"

"bb.irw" is built and is 173KB. it mostly consists of the contents of court.bin,

HOWEVER! doing...
load2 bb /X /DC /FC /TC
will work. you may need even more flags, depending on how things go.

some command line options you might need; descriptions blatantly stolen from LOAD2.HLP
/I  -Write background data to image roms
/P  -Pad images to multiple of 4 bits
/L  -aLign images to 16 bit boundaries
/A  -Append to (i.e. do not erase and recreate) default table files.

various LOD files and what they make
------------------------------------
[bb.lod]
(this one is big, hold your horses)

glo: IMGTBL.GLO
asm: COURT.TBL
uses:
- COURT (FRM definition)
- ADS.IMG
- COURTZ.IMG
- CHEERS.IMG

asm: PLYRHD.TBL
uses:
- HDS1.IMG
- HDS2.IMG
- HDS3.IMG
- HDS4.IMG
- HDS5.IMG
- HDS6.IMG

asm: PLYRHD2.TBL
uses:
- HDS7.IMG

asm: IMGTBL.ASM
uses:
- BALL.IMG

asm: STAND.TBL
uses:
- WST.IMG

asm: IMGTBL.ASM
uses:
- REFTIP.IMG
(defines imgtbl.asm again for whatever reason before these next images)
- BALLTIME.IMG
- TVSCORE.IMG
- TVSCORE2.IMG
- FONT6.IMG
(defines imgtbl.asm for a third time)
- SPARKS.IMG
- HOOP.IMG
- TVTEXT.IMG
- OSGEMD.IMG
- LOGOS.IMG
- CITIES.IMG
- LGMD.IMG
- STATSTXT.IMG
- SGMD8.IMG
- OGMD10.IMG
- INFOWIN.IMG

asm: ARROW.TBL
uses:
- ARROWS.IMG

asm: CITY.TBL
uses:
- CITNAMES.IMG

asm: IMGTBL.ASM
uses:
- TROPHY.IMG
- XPLOSION.IMG
(defines imgtbl.asm again)
- NSCRN2.IMG

asm: IMGTBL.ASM
glo: BGNDTBL.GLO
uses (all are BBB/background type):
- HISCORE
- EMPTYJAM
- YESNO
- SELBACK
- TEAMSEL
- MATCHBAK
- STATSCRN
- NEWTITLE (TITLE in non-TE Jam)
- CONGRATS
- LADDER2
- CHRVIC
- SELBACKK
- SUBST
- VIEWHP
- blankjam

glo: IMGTBL.GLO
uses:
- TSMLOGO.IMG
- FLASH.IMG

[bb2.lod]
(assumes imgtbl.glo per loadimg defaults?)
asm: leds.tbl
uses:
- leds1.img

asm: junkxxxx
uses:
- diagp.img

asm: pass.tbl
uses:
- wnlp.img

asm: plyrseq.tbl
uses:
- todd.img
- willie.img
- willie2.img

asm: plyrd2seq.tbl
uses:
- todd.img

asm: plyrdseq.tbl
uses:
- willie2.img
- dunks.img

asm: plyrd2seq.tbl
still using dunks.img?

asm: plyrdseq.tbl
still using dunks.img?

asm: plyrseq.tbl
uses:
- willie3.img

asm: layup.tbl
uses:
- willie3.img (from above definition)
- layups.img

asm: plyrseq.tbl
uses:
- willie4.img

asm: plyrseq2.tbl
uses:
- willie4.img (from above definition)

asm: plyrseq.tbl
uses:
- willie4.img (from above definition)

asm: plyrseq.tbl
uses:
- willie5.img

asm: TEXT.TBL
uses:
- trogf15.img
- trogf7.img
- squadplt.img

asm: ball.tbl
uses:
- ball.img

asm: crowd.tbl
uses:
- courtz.img

[bb3.lod]
glo: IMGTBL.GLO
asm: fireseq.tbl
uses:
- firefall.img
- ndunks5.img

glo: IMGTBL4.GLO
asm: plyrhd4.tbl
uses:
- ourhds2.img
- ourhds3.img
- raiden.img

[bbmug.lod]
glo: IMGTBL.GLO
asm: mugshot.tbl
uses:
- nmugs.img
- mugshots.img
- mugshot3.img

glo: IMGTBL3.GLO
asm: plyrhd3.tbl
uses:
- HDS8.img
- HDS9.IMG
- HDS10.IMG
- HDS11.IMG
- HDS12.IMG

[bbpal.lod]
"flesh and uniform pals"
glo: IMGTBL.GLO
asm: junkxxxx
uses:
- pals.img
- crwdpals.img

[bbtest.lod]
asm: plyrseq2.tbl
uses:
- firefall.img

[bbtst.lod]
glo: IMGTBL.GLO
asm: plyrhd.tbl
uses:
- hds1.img

================================================================================
[open-ice]
Luckily, 2 on 2 Open Ice Challenge did not get overwritten during the process of
making a sequel. However, it's no less challenging to navigate.

the directories:
- bill
- code
- img
- macros
- other

================================================================================
[other archives I pulled down]
these aren't listed in the main section because I'm mainly grabbing them for
other reasons...

nba-hangtime: doc folder
revolution-x: tools!

================================================================================
[assorted notes]
.glo files are just a bunch of ".globl" definitions...

--------------------------------------------------------------------------------
.vda files, as rare as they are in these archives, are similar to TGA files.

These are meant to go through a multi-step process:
1) vda to "frm", which splits the vda into "hdr" and "frm" files.
hdr contains the important parts of the header, namely image size, bpp, and the
palette data (for a 16 bit image, each color is 1555).
frm contains the image data itself.

2) the frm file is zipped with an older version of pkzip.
How old? "Version 1.1 03-15-90"

3) the zip file is passed into a program called "zip2bin", which performs
transformations that are currently unknown to me.

--------------------------------------------------------------------------------
.bdb files are text, and are probably paired with the corresponding .bdd file.

These are somewhat described in loadbg.doc from NBA Hangtime docs directory.
However, that document assumes the reader has an unspecified fax with more
complete information on the format.

.bdb file info
--------------

first line:
NAME xlength ylength zlength numMods numPals numBlocks

module definition:
NAME upper_lft_x lower_rt_x upper_lft_y lower_rt_y 

followed by numBlocks entries in the following format:
univ_Z univ_X univ_Y Hdr Palette

.bdd file info
--------------
for the two header lines ending in 0x0A, all values are ASCII.
space seems to be the value separator for line 2.

number of images, 0x0A

old_hdr width height big_pal, 0x0A

old_hdr seems to be incremented by 3 for each entry? (from viewing yesno.bdd)

image and palette data follow

palettes seem to be...
name entries, 0x0A

with values being 1555 ?RGB.

--------------------------------------------------------------------------------
.lod files are some sort of script?

loadimg.doc from the NBA Hangtime docs directory gives this information:
"The format for the .lod file is...
A fully qualified .img filename starting in column 1.
A series of lines starting with "---> " followed by as many
image names as will fit on a line separated by commas.
A line that starts with "BBB> " expects a list of Blimp
background files."

upon viewing multiple .lod files, the format is clearly not that simple.
load2.hlp from NBA Hangtime's "newload2" directory gives more info...

Any line beginning with ';' or '/' is a comment.

The first four characters of a non-comment line are checked for a command.
If a valid command is not found, "the line is assumed to contain a WIMP .img
filename".

---> img1[:stcol][*{2-4}],img2[:stcol][*{2-4}],...,imglast[:stcol][*{2-4}]
Starts an image list using the active .img file.

"stcol" is optional; it denotes an index into the color palette for all non-zero
values in the image.

the asterisk is also optional; it tells load2 (the .lod parser) to create multiple
sizes of the image for scaling purposes. The value following the asterisk must be
a number; it determines how many different scale levels are made.

***> hex_address[,end_address][,bank]
Set the current address counter to the specified address.
When starting load2, the default address is 2000000h.

end_address is optional, and will tell load2 to check if the requested data can
fit within the range given.

bank is also optional, and is only usable with the /E flag (indicating dual-banked
image memory). The value can be 0 or 1, and is 0 by default.

GLO> global_filename
Set the filename for future global labels to be written to.
By default, this is "imgtbl.glo".

ASM> imghdr_filename[,section_name]
Set the filename for all future image headers to be written to.
By default, this is "imgtbl.asm".

section_name is optional; if omitted, a ".data" line will be written at
the beginning of the .asm file.

ROM> staddr,endaddr
Specifies an area for image data to NOT be downloaded to.

PPP> digit
Sets the pixel packing level for DMA2.
0 (the default) packs images to the smallest possible level.
non-zero values from 1-8 represent the number of bits per pixel.

ZON>
ZOF>
Enable or disable DMA2's "zero compression" feature. This is best described by
stealing from load2.hlp:
"When on, load2 computes the leading and trailing zeros for each line of each
image and sets the appropriate bits in the DMA control field of the image header.
When off (the default), load2 downloads the data as it always has in the past.
Zero compression is AUTOMATICALLY turned off for scaled images!"

CON>
COF>
Enable or disable checksums.
Again, load2.hlp has a better description than I could write:
"These keywords turn checksums on and off.
When on (the default), load2 computes a checksum for each image to see if it
matches a previous image. If so, it creates a new image header pointing to
the previous data, and does not download the identical data.
When off, identical data will be downloaded separately."

PON>
POF>
"These keywords turn the palette entry in the image header on and
off when the /T option is in effect.

When on (the default), load2 includes the palette field in the image header
table (assuming it is part of the IHDR format).

When off, the palette field is not included in the image header.

THIS IS REALLY OBSOLETE SINCE YOU CAN DO THE SAME THING WITH THE IHDR COMMAND."

XON>
XOF>
"These keywords turn on extra zero pixels along the right and bottom edge
of images so the DMA's scaling computation doesn't truncate them prematurely."

FRM> bin_filename1,bin_filename2,...
"Compressed movie footage is contained in files with a .bin extension.
These need to be loaded using the FRM> keyword."

BBB> bg_filename1,bg_filename2,...
"Loads a BLIMP background file.  This causes the following tables to be
created when the /T option is in effect...
bgndequ.h, bgndtbl.asm, bgndpal.asm"

UFN> uni_file_num
Used with /A option to set the starting "universe number".
By default, this is 0, which could overwrite previous data if you're not careful.

UGL> user_glo_file
"This sets a file name which will be included in a file that load2 generates. 

The user_glo_file is one file for all universes which you create and maintain
containing image, sequence and/or damage table names which you want to be global,
but are not automatically set to be by load2.
The only reason you are supplying the name here is so load2 can put a .include
line in univtbl.glo."

UNI> uni_fname[;override_directory][,uni_fname[;override_dir]...]
Load a BGTOOL universe file.

"The image files contained within the universe file must come from IMGDIR
or the override directory (if specified).

The following tables are created when the /T option is in effect...
univtbl.glo (for the first UNI> encountered)
unixx.asm,uniseqxx.asm,unixx.tbl,univtbl.glo"

IHDR FLD1:S,FLD2:S,...,FLDn:S
Specify an image header format. Fields are defined as name:size.

load2.hlp has this information:
VALID FIELDS ARE LIMITED TO THE FOLLOWING...
	SIZX	x size
	SIZY	y size
	SAG	image address
	CTRL	DMA2 control field
	ANIX	x anim pt
	ANIY	y anim pt
	PAL	palette name
	ALT	alternate palettes (if there are any)
	NOTE: these are terminated with a -1.
	If an image has none, a -1 is still placed in its table.
	PTnx	Point Table values
	(n = 0-9   x = X or Y)

VALID SIZES ARE LIMITED TO THE FOLLOWING..
	B	.byte
	W	.word
	L	.long

By default, load2 assumes the following image header:
IHDR SIZX:W,SIZY:W,SAG:L,ANIX:W,ANIY:W,CTRL:W,PAL:L

"DMA2 control field" likely maps to DMA2 register 1:
FEDCBA98 76543210
||_||||| |||||__|
| | |||| ||||  |
| | |||| ||||  +-- Pixel Operations
| | |||| |||+----- (HFL) Horizontal Flip
| | |||| ||+------ (VFL) Vertical Flip
| | |||| |+------- (CLP) DMA Clip
| | |||| +-------- (CMP) DMA Compress Mode
| | |||+---------- (LM0) DMA Compression Lead Pixel Multiplier bit 0
| | ||+----------- (LM1) DMA Compression Lead Pixel Multiplier bit 1
| | |+------------ (TM0) DMA Compression Trailing Pixel Multiplier bit 0
| | +------------- (TM1) DMA Compression Trailing Pixel Multiplier bit 1
| +--------------- (PIX) Pixel Size (0=8 bits)
+----------------- (DGO) DMA Go/Halt

Fields used by NBA Jam .lod files that are not mentioned above:
PWRD1:W,PWRD2:W,PWRD3:W

--------------------------------------------------
Commands not mentioned in the help file, but found in the executable:
ZAL>
probably grouped with ZOF> and ZON> commands

MOF>
MON>
unknown functionality

BOF>
BON>
unknown functionality

--------------------------------------------------------------------------------
.img format is the one we all really want to know about, so let's examine...

the first 16 bytes of "kengrif.img":
08 00 06 00 90 30 00 00 3F 06 00 00 00 00 00 00

grouping them slightly...
0800 0600 90300000 3F06 0000 0000 0000
|__| |__| |______| |__| |__| |__| |__|
  |    |      |      |    |    |    |
  |    |      |      |    |    |    +---- ???
  |    |      |      |    |    +--------- number of anim. scripts?
  |    |      |      |    +-------------- number of anim. sequences?
  |    |      |      +------------------- WIMP version number used to generate this file
  |    |      +-------------------------- directory info address
  |    +--------------------------------- ???
  +-------------------------------------- number of images?

and the second 12 bytes, just in case...
CD AB 00 00 00 00 00 00 00 00 00 00

grouped
CDAB 0000 0000 0000 0000 0000
|__| |__| |__| |__| |__| |__|

thanks to "wlib.exe", we can get some information about this file:

8 images in C:\BIN\kengrif.img
GRIFFEY            KEN_MUG            KGRIF05            KGRIF04
KGRIF03            KGRIF02            KGRIF01            KGRIF16

3 palettes in C:\BIN\kengrif.img
scorep             KEN_MUGP           KGRIF_P

wlib lists the following other possible data types:
- animation sequences
- animation scripts
- point tables
- alternate palette tables
- damage tables

wlib is also capable of determining what version of WIMP the .img file was
made from... kengrif.img was made with v6.63 of WIMP, apparently.

so if I had to guess, the first two bytes store the number of images.
the next two bytes are ???
the third set of two bytes is the file address where directory info begins?

for this file, the directory info is at 0x3090.
- each image entry is 0x32 bytes long?
- each palette entry is 0x1A bytes long?
- each anim sequence entry is 0xE0 bytes long?
- each anim script entry is 0x74 bytes long?
- point table, altpals, damage: unknown at the moment

; image "GRIFFEY" (size 42x9, xani 21, yani 0, palette "scorep")
47 52 49 46 46 45 59 00 20 07 20 07 20 07 20 07
20 00 [15 00] [00 00] [2A 00] [09 00] [03 00] [E0 02 00 00]
4A 3A 25 55 00 00 FF FF FF FF FF FF FF FF FF FF
FF FF

; image "KEN_MUG" (size 65x61, xani 0, yani 61, palette "KEN_MUGP")
4B 45 4E 5F 4D 55 47 00 20 20 20 20 20 20 20 00
00 00 [00 00] [3D 00] [41 00] [3D 00] [04 00] [6C 04 00 00]
00 00 00 00 00 00 FF FF FF FF FF FF FF FF FF FF
FF FF

; image "KGRIF05" (size 25x37, xani 11, yani 33, palette "KGRIF_P")
4B 47 52 49 46 30 35 00 20 20 20 20 20 20 20 00
00 00 [0B 00] [21 00] [19 00] [25 00] [05 00] [A0 14 00 00]
00 00 00 00 00 00 00 00 00 00 FF FF FF FF FF FF
FF FF

; image "KGRIF04" (size 36x36, xani 18, yani 32, palette "KGRIF_P")
4B 47 52 49 46 30 34 00 20 20 20 20 20 20 20 00
00 00 [12 00] [20 00] [24 00] [24 00] [05 00] [AC 18 00 00]
00 00 00 00 00 00 FF FF FF FF FF FF FF FF FF FF
FF FF

; image "KGRIF03" (size 39x35, xani 20, yani 32, palette "KGRIF_P")
4B 47 52 49 46 30 33 00 20 20 20 20 20 20 20 00
00 00 [14 00] [20 00] [27 00] [23 00] [05 00] [BC 1D 00 00]
00 00 00 00 00 00 00 00 00 00 FF FF FF FF FF FF
FF FF

; image "KGRIF02" (size 32x33, xani 18, yani 31, palette "KGRIF_P")
4B 47 52 49 46 30 32 00 20 20 20 20 20 20 20 00
00 00 [12 00] [1F 00] [20 00] [21 00] [05 00] [34 23 00 00]
00 00 00 00 00 00 FF FF FF FF FF FF FF FF FF FF
FF FF

; image "KGRIF01" (size 27x33, xani 13, yani 31, palette "KGRIF_P")
4B 47 52 49 46 30 31 00 20 20 20 20 20 20 20 00
00 00 [0D 00] [1F 00] [1B 00] [21 00] [05 00] [54 27 00 00]
00 00 00 00 00 00 FF FF FF FF FF FF FF FF FF FF
FF FF

; image "KGRIF16" (size 34x40, xani 32, yani 34, palette "KGRIF_P")
4B 47 52 49 46 31 36 00 19 00 24 00 21 00 0C 00
00 00 [20 00] [22 00] [22 00] [28 00] [05 00] [F0 2A 00 00]
00 00 00 00 00 00 FF FF FF FF FF FF FF FF FF FF
FF FF

; palette "scorep"
73 63 6F 72 65 70 00 55 AC 04 10 06 [3F 00] [1C 00
00 00] 86 72 00 00 00 00 AC 00

; palette "KEN_MUGP"
4B 45 4E 5F 4D 55 47 50 00 04 00 08 [E5 00] [9A 00
00 00] 86 72 00 00 00 00 AC 00

; palette "KGRIF_P"
4B 47 52 49 46 5F 50 00 00 04 00 06 [3E 00] [64 02
00 00] 86 72 00 00 00 00 AC 00

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; from pals.img, "?BLANK" has a points table assigned to it.

here's the value in the directory table
3F 42 4C 41 4E 4B 00 20 20 20 20 20 20 20 20 00
00 00 [00 00] [00 00] [0E 00] [16 00] 03 00 [FC 47 00 00]
00 00 00 00 00 00 FF FF FF FF FF FF FF FF 00 00
FF FF

and the points table value, which is 0x28 bytes long and is at PALS.IMG offset 0xDE74
"1 Point Table in C:\BIN\pals.img

Image ?BLANK:
	7344,7345   7346,7347   7348,7349   7350,7351   7352,7353   
	7354,7355   7356,7357   7358,  -1     -1,  -9   7362,7363  "

[B0 1C, B1 1C] [B2 1C, B3 1C] [B4 1C, B5 1C] [B6 1C, B7 1C] [B8 1C, B9 1C]
[BA 1C, BB 1C] [BC 1C, BD 1C] [BE 1C, FF FF] [FF FF, F7 FF] [C2 1C, C3 1C]

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; raiden.img has some animation scripts and sequences

2 animation sequences in C:\BIN\raiden.img
blite              light

2 animation scripts in C:\BIN\raiden.img
blite              lite

raiden.img header
0E00 0400 1E0C0000 3E06 0200 0200 0000 CDAB 0000 0000 0000 0000 0000

"blite" anim sequence directory entry
62 6C 69 74 65 00 61 6D 65 29 20 20 20 20 20 00
40 00 07 00 4A 34 B8 5B 36 34 B8 5B 22 34 B8 5B
0E 34 B8 5B FA 33 B8 5B E6 33 B8 5B D2 33 B8 5B
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 0A 00 0A 00 FF FF FF FF FF FF 00 00
00 00 00 00 00 00 06 00 01 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 05 00 01 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 04 00 01 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 03 00 01 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 02 00
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
01 00 01 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00

"light" anim sequence directory entry
6C 69 67 68 74 00 61 6D 65 29 20 20 20 20 20 00
40 00 07 00 3A 35 B8 5B 26 35 B8 5B 12 35 B8 5B
FE 34 B8 5B EA 34 B8 5B D6 34 B8 5B C2 34 B8 5B
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 0A 00 0A 00 FF FF FF FF FF FF 00 00
00 00 00 00 00 00 0D 00 01 07 00 00 00 00 00 00
00 00 00 00 00 00 00 00 0C 00 01 0E 00 00 00 00
00 00 00 00 00 00 00 00 00 00 0B 00 01 0E 00 00
00 00 00 00 00 00 00 00 00 00 00 00 0A 00 01 07
00 00 00 00 00 00 00 00 00 00 00 00 00 00 09 00
01 07 00 00 00 00 00 00 00 00 00 00 00 00 00 00
08 00 01 07 00 00 00 00 00 00 00 00 00 00 00 00
00 00 07 00 01 0A 00 00 00 00 00 00 00 00 00 00

"blite" anim script directory entry
62 6C 69 74 65 00 61 6D 65 29 20 20 20 20 20 00
00 00 01 00 B2 35 B8 5B AE 25 B6 6C C2 25 B6 6C
D6 25 B6 6C EA 25 B6 6C FE 25 B6 6C 12 26 B6 6C
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 E4 00 7A 00 FF FF FF FF FF FF 00 00
00 00 00 00 00 00 00 00 01 07 00 00 00 00 00 00
00 00 00 00

"lite" anim script directory entry
6C 69 74 65 00 4E 61 6D 65 29 20 20 20 20 20 00
00 00 01 00 2A 36 B8 5B 26 90 B5 5C 3A 90 B5 5C
4E 90 B5 5C 62 90 B5 5C 76 90 B5 5C 8A 90 B5 5C
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 60 00 98 00 FF FF FF FF FF FF 00 00
00 00 00 00 00 00 01 00 01 00 00 00 00 00 00 00
00 00 00 00

@droussos Hi, sorry for the late reply on this; finally found the time to get my notes and uploaded them as another file in this post: https://gist.github.com/freem/34424b449ab812c6cbf97dfd5abebac3#file-gistfile1-txt

I never actually got around to testing the built ROMs in MAME, though, as I wasn't sure how the output was meant to be split.

A lot of the files mentioned/you'll need are in the Revolution X repository: https://github.com/historicalsource/revolution-x