SCUMM file format specifications and documentation

The Really Useful SCUMM etc. Info File
Maniac Mansion .lfl-files
Additional .lfl info
AKOS format
Preliminary SAN documentation
Monkey Island 1 & 2 costume format
Monkey Island 2 costume format
Monkey Island 2 SCUMM opcodes
SCUMM index files
.bun file format
.lab file format
EMI .lab file format
EMI .til file format
GF/EMI .laf fonts file format
EMI mesh specs

(download file)

Escape from Monkey Island file specs v0.01
-------------------------------------------
by Benjamin Haisch aka john_doe (john_doe@techie.com)
If you have any questions regarding this text or found out new information just mail me.


Introduction
==============

In this text I try to describe the file formats of the 3d files used in Escape from Monkey Island.
These files are meshes (.meshb), skeletons (.sklb) and animations (.animb).
I haven't yet looked into the costume files (.cosb) which group all the above files together.

Note that I'm a newbie to 3d coding so many terms are probably wrong.


Contents
==========

0.  Common definitons
1.  Binary meshes (.meshb) specs
1.1 Notes about BoneInfoCount
2.  Binary skeleton (.sklb) specs
3.  Binary animation (.animb) specs
3.1 Note on bone operations:
3.2 Note on rotations:



0. Common definitons
======================

vector3d = float x,y,z
vector2d = float x,y

string:
long		length
byte[length]	string data



1. Binary meshes (.meshb) specs
=================================

These files contain the actual 3d model model data, i.e. vertices, normals, faces and texture coordinates and optionally information which vertex is connected to which bone in the skeleton.

Start:
--------
string		MeshName		Name of the mesh
vector3d	u[4]			unknown (maybe for collision detection)

long		numtex			Number of textures used
string		texname[numtex]		Texture filenames (incl. path information)

long		u			unknown, is 0x13 in many files
long		numvert			Number of vertices or similar
vector3d	vectors[numvert]	Vertex data
vector3d	normals[numvert]	Normal data

byte		size is numvert * 4	colormap for vertex coloring

vector2d	texcoords[numvert]	texture coords

long		facedatacount		Number of texture groups
					(for faster texturing, switching textures
					only once per texture)

repeated facedatacount times {
long		flags			usually 0x0304
long		textureused		0= not textures; 1= textured
long		texture			Index of texture to be used
					this is only stored if textureused=1
long		facescount		Number of faces
word		faces[facescount]	the faces data
}

long		hasbones		0= mesh has no bones; 1= has bones

if hasbones=0 the file ends here, else there's some more to read:

long		bonecount		Number of bones
string		bonename[bonecount]	Names of the bones
					(they refer to the names specified
					in the skeleton file, .sklb)
long		boneinfocount		Number of "bone infos" (need a better name)
					Stores for each vertex which bone it belongs to.

repeat boneinfocount times {		See description below for more notes
long		incval			(Need better name)
long		bone			The bone the vertex belongs to.
					I don't know yet if this index is into the skeleton
					file or into the bonename array first and from
					there to the correct bone in the skeleton.
float		weight			The weight the assiciated bone has to this vertex.
}

(Note: "Usually" means it's the same in all the files I checked.)


1.1 Notes about BoneInfoCount
-------------------------------

This is where the bone-vertex relations are stored.
Note that a vertex can be associated to more than one bone.
That's why boneinfocount and numvert may differ (but they may be the same, too).

If incval is one, then go to the next vertex. Otherwise if it's 0, then stay at the current vertex.

All weights added must equal to 1.0.


Example (from mk1.meshb):

BoneInfo[0]: Vertex= 0	IncVal=  1   Joint= 130  Weight= 1.000
BoneInfo[1]: Vertex= 1	IncVal=  1   Joint= 130  Weight= 1.000
BoneInfo[2]: Vertex= 2	IncVal=  1   Joint= 130  Weight= 0.871
BoneInfo[3]: Vertex= 2	IncVal=  0   Joint=  91  Weight= 0.129
BoneInfo[4]: Vertex= 3	IncVal=  1   Joint= 130  Weight= 1.000
BoneInfo[5]: Vertex= 4	IncVal=  1   Joint= 130  Weight= 1.000
BoneInfo[6]: Vertex= 5	IncVal=  1   Joint= 130  Weight= 0.749
BoneInfo[7]: Vertex= 5	IncVal=  0   Joint=  91  Weight= 0.251


Here the vertices 0, 1, 3, 4 are each linked to one bone (each with a weight of 1).
The vertices 2 and 5, however, are linked to two bones, each with different weight factors that add up to 1 (for each vertex).



2. Binary skeleton (.sklb) specs
==================================

These files store the skeleton of the model. Each bone is connected to several vertices of the mesh, so if one bone is moved or rotated, so do the attached vertices.

string32 means it's a string with a constant size of 32 bytes, without any length byte.


Start:
--------
long		bonecount		Number of bones in the skeleton

repeat bonecount times {
string32	name			Name of the bone
string32        parent			Name of parent bone
vector3d	position		Initial position of the bone
vector3d	rotation		Initial rotation of the bone
float		angle			Initial rotation angle
}



3. Binary animation (.animb) specs
====================================

These files contain keyframe data. Each bone has its own keyframe chunk. Each chunk can either be a translation or a rotation (maybe there are other types as well).


Definitions:
--------------
translation:
vector3d	vec		translation vector
float		time		time this translation is finished

rotation:
quaternion	rot		rotation quaternion
float		time		time this rotation is finished


Start:
--------
string		name		Name of the animation
float		duration	duration of this animation in seconds
long		bones		Number of animated bones (need another name)

repeat bones times {
string			bonename	Name of bone to be animated
					This refers to the bone name stored in the skeleton
long			operation	Operation on this bone (see below)
long			unk1		unknown (often 0x01)
long			unk2		unknown (often 0x00)
long			keyframes	Number of keyframes of this bone

if operation=3
translation[keyframes]	translations	List of translations

if operation=4
rotation[keyframes]	rotations	List of rotations

}


3.1 Note on bone operations:
------------------------------

If operation is 3 this means the bone has to be translated according to the data.
If operation is 4 the bone has to be rotated instead.
Other keyframe types may be possible but I only found these two.


3.2 Note on rotations:
------------------------

I think the rotations are stored as quaternions but they might as well be just an axis as vector3d and an rotation angle.