Difference between revisions of "Resource file format"
m (Accidentally removed header.) |
(Expanded the lead in order to have a more newbie-friendly definition, able to be referenced from other articles) |
||
| Line 1: | Line 1: | ||
| − | Stunts game data are stored in a common container format. Files of this format can hold multiple resources of | + | Stunts game data are stored in a common container format. Files of this format can hold multiple ''resources'', blocks of data that may be of various types - text, bitmaps, sounds, etc. Resources are uniquely identified within each file solely by a 4-byte name. A resource container file can be encapsulated by [[Compression|compression]]. |
This document focuses on [[Game versions#PC versions|BB Stunts 1.1]], but details described here may still—partly or wholly—cover other versions, or even other games developed by DSI at the time. | This document focuses on [[Game versions#PC versions|BB Stunts 1.1]], but details described here may still—partly or wholly—cover other versions, or even other games developed by DSI at the time. | ||
Revision as of 01:14, 25 April 2008
Stunts game data are stored in a common container format. Files of this format can hold multiple resources, blocks of data that may be of various types - text, bitmaps, sounds, etc. Resources are uniquely identified within each file solely by a 4-byte name. A resource container file can be encapsulated by compression.
This document focuses on BB Stunts 1.1, but details described here may still—partly or wholly—cover other versions, or even other games developed by DSI at the time.
File names
Different file name extensions are used to indicate the content of the files. Compressed files has "P" (packed) as the first letter of their extensions. Whether the game prefers raw or compressed files varies based on file type.
| File contents | Raw | Compressed | Preferred |
|---|---|---|---|
| Text and misc. settings | RES | PRE | Raw |
| Bitmap images | VSH | PVS | Compressed |
| Icons | ESH | PES | Compressed |
| 3d shapes | 3SH | P3S | Compressed |
| Music tracks | KMS | PKM | Raw |
| Instrument samples | VCE | PVC | Raw |
| Sound effects | SFX | PSF | Raw |
Structure
The resource file header consists of two integer fields denoting the total length of the file and the number of resources contained. The following table of contents has a list of ids and a corresponding list of offsets into the remaining data section.
// Header uint32 fileLength uint16 numResources // Table of contents char ids[numResources][4] uint32 offsets[numResources] // Resource data char data[]
Types
Resource type can be determined by looking at the resource's id string and/or the source file name.
Plain text
Text resources are null-terminated C strings found in RES/PRE files. Strings can contain non-alphanumeric codes used by the game to achieve certain effects. Most prominent is the "]" (right square bracket) used to represent newline in multi-line text.
Bitmap images
Bitmaps are images with 8-bit color depth using a fixed palette in VGA mode. Special bitmaps using the naming scheme !cg_ and !eg_ provides color mapping for graphics modes with fewer available colors.
uint16 width uint16 height uint16 unknown1[4] uint8 unknown2[4] uint8 image[width * height]
Parts of this structure are not fully understood. unknown1 appears to be related to Stunts' internal memory management. unknown2 seems to affect how image pixels are organized in compressed resource files, likely to gain more effective run-length compression. Images with pixel data stored as continuos horizontal lines has unknown2 set to { 0x1, 0x2, 0x4, 0x8 }.
Icons
3d shapes
Shapes are composed of a vertex list and a list of primitives. Primitives are basic shapes that can have different types, such as polygons or wheels. Depending on the type it contains a number of indices into the vertex list needed to draw the shape, color variations and some rendering hints. Stunts' coordinate system use 16-bit signed integers, making the resolution relative to the scale of the model. Shapes presented in the car selection screen are more detailed than in-game shapes, thus requiring larger scaling.
Due to the counter header fields being stored in single bytes, the total amount of vertices and primitives are limited to 255 per shape.
Main strcture
uint8 numVertices uint8 numPrimitives uint8 numPaintJobs uint8 reserved // Always == 0 VERTEX vertices[numVertices] UNKNOWN unknowns[numPrimitives] PRIMITIVE primitives[numPrimitives] uint8 terminate; // Always == 0
Additional structures
struct VERTEX { int16 x int16 y int16 z } struct UNKNOWN { int8 data[8] } struct PRIMITIVE { uint8 type uint8 depthIndex uint8 materials[numPaintJobs] uint8 indices[...] // Size depends on type. }
Primitive types
| Primitive type | Vertex indices needed | Description |
|---|---|---|
| 1 | 1 | Particle, 1 pixel |
| 2 | 2 | Line segment, 1 pixel width |
| 3–10 | 3–10 | Polygon, n sides |
| 11 | 2 | Sphere (center + ~(radius / 2) |
| 12 | 6 | Wheel |
| * | 0 | Ignored |
The first three vertices in a wheel primitive marks the center, tire radius and rim radius for the inner wheel-half facing the vehicle. The last three vertices does the same, in the same order, for the outer half of the wheel. Directions does not matter, the vertex locations are only used to measure distances. This rule applies to the sphere primitive as well.
The value depthIndex in the PRIMITIVE structure is used to override the game's depth clipping in order to avoid flickering when several primitives are being drawn at the exact same depth. Higher value gives the primitive higher precedence.
Materials are indices into a fixed, internal game structure and are assigned per-primitive. Cars can have multiple paint jobs, every primitive in the shape must set a material for each color scheme.
Experimentation has revealed that UNKNOWN data at least partially controls occlusion culling on primitive level. How, and exactly which parts of this structure does what has yet to be understood.
