DO/BTB

From Dark Omen Wiki

< DO
Revision as of 19:19, 5 January 2009 by Mikademus (Talk | contribs)
Jump to: navigation, search

Contents

Overview

A BTB file (originally thought to be an abbreviation of "Battle Boundaries") contains information about zones, obstacles, objectives and game elements in a Dark Omen map.

The file format is fully binary, and consists of blocks ("chunks") that contains items. Usually the items are atomic (contains a single datum) but sometimes they are records with items in themselves. All blocks and items share the same anatomy and have a 8-byte header (the first 4 bytes is the block type ID, the second is the size of the block, excluding header for top-level blocks ("chunks") but including the header size for items. This is for convievable faster parsing: if you want a particular block you read headers and then chomp size bytes for the next block, while it is probably a Good Think to have the size of items in the full. More likely, however, is that the DO designers thrived on inconsistency.

Tabulation of Blocks and Records

id alias here size notes
0xBEAFEED0 BT_startend header + 0 No content, just used to indicate file start and end
1 BT_mapdata header + 240 Fixed content
2 BT_objectives header + varies Varying contents
3 BT_obstacles header + varies Varying contents
4 BT_region header + varies Varying contents
5 BT_gameobjects header + varies Varying contents
501 IT_obstacle 80 (with header) Sub-block under BT_obstacle, fixed content
503 IT_gameobject 104 (with header) Sub-block under BT_gameobjects, fixed content

Note again that the size values of blocks BT_startend--BT_gameobjects are given exclusive of the header 8 bytes, while the size given in the records IT_obstacle--IT_gameobject are including the 8-byte header.

Tabulation of Data Items

id Alias here size what used where used for default data
1 ATOM_x 12 integer BT_mapdata, BT_obstacles, IT_gameobject width, x-pos
2 ATOM_y 12 integer BT_mapdata, BT_obstacles, IT_gameobject height, y-pos
3 ATOM_obj 20 3-tuple BT_objectives ???
4 ATOM_Z 12 integer BT_obstacles ??? depth, z-pos
5 ATOM_type 12 integer BT_obstacles, BT_region, IT_gameobject type (flags)
6 ATOM_radius 12 integer BT_obstacles, IT_gameobject radius
7 ATOM_dir 12 integer BT_obstacles, IT_gameobject ??? direction usually 0
8 ATOM_mem 12 integer BT_gameobject ??? # reserved memory slots
9 ATOM_regiondata 16 2-tuple BT_mapdata regions metadata
10 ATOM_startpos 16 2-tuple BT_region start position
11 ATOM_id1 16 integer IT_gameobject ??? node ID
12 ATOM_unitid 16 integer IT_gameobject unit ID
13 ATOM_id3 16 integer IT_gameobject ??? script ID
501 IT_obstacle 80 sub-block BT_obstacles obstacle data
502 ATOM_line 24 4-tuple BT_region line segment
503 IT_gameobject 104 sub-block BT_gameobject game object data
1001 ATOM_mercs 40 string BT_mapdata merc army file name (w/o ext)
1002 ATOM_enemy 40 string BT_mapdata enemy army file name (w/o ext)
1003 ATOM_ctl 40 string BT_mapdata CTL file filename (w/o ext)
1004 ATOM_unkn1 40 string BT_mapdata ??? "/0"
1005 ATOM_unkn2 40 string BT_mapdata ??? "/0"
1006 ATOM_regname 40 string BT_region Region name

Note 1: that the size member of all data items include the 8-byte header. Thus, a 12-byte integer item consists of 8 bytes of header and four bytes of data.

Note 2: There are duplicates of data types, especially integer. This is because the item ID does not only indicate data type but also intended usage. Thus, types 1 and 2 are used in different blocks, but are always integers and always used to express X and Y (or WIDTH and HEIGHT) values.

Tabulations of Contents of Atoms

<multicol cols=2>

Integer items

Size Function Value
4 Identification 1--2, 4--8, 11--13
4 Size of entire item 12
4 Integer value

String items

Size Function Value
4 Identification 1001--1006
4 Size of entire item 40
4 Character array 32


2-tuple

Size Function Value
4 Identification 9 10
4 Size of entire item 16
4 Integer value # regions in file start x-pos
4 Integer value # line segments in all regions start y-pos


3-tuple

Size Function Value
4 Identification 3
4 Size of entire item 20
4 Integer value
4 Integer value
4 Integer value


4-tuple

Size Function Value
4 Identification 502
4 Size of entire item 24
4 Integer value x1
4 Integer value y1
4 Integer value x2
4 Integer value y2

</multicol>


Tabulations of Contents of Blocks and Records

Map data block
ID Size Type Value/function
1 BL_mapdata 8 Header [1, 240]
1 ATOM_x 12 Integer item (divide by 8) map width
2 ATOM_y 12 Integer item (divide by 8) map height
1001 ATOM_merc 40 String item Merc army filename (w/o ext)
1002 ATOM_enemy 40 String item Ememy army filename (w/o ext)
1003 ATOM_ctl 40 String item CTL filename (w/o ext)
1004 ATOM_unkn1 40 String item "/0"
1005 ATOM_unkn2 40 String item "/0"
9 ATOM_regiondata 16 2-tuple [Num. of regions, Total num. of line segments]


Obstacle record
ID Size Function Value
501 IT_obstacle 8 Header [501, 80]
5 ATOM_type 12 Integer item (flags)
1 ATOM_x 12 Integer item (divide by 8) x-pos
2 ATOM_y 12 Integer item (divide by 8) y-pos
4 ATOM_z 12 Integer item (divide?)  ??? z-pos
6 ATOM_radius 12 Integer item (divide by 8) radius
7 ATOM_dir 12 Integer item  ??? direction


Obstacles block
ID Size Function Value
3 BL_obstacles 8 Header [3, size]
8 ATOM_counter 12 Integer item Counter for memory spaces, must be > the number of obstacles
501 IT_obstacle 80 Obstacle item
The number of records is not explicitly given, but can be calculated as (size - 20) / 80
... (more IT_obstacle records)
501 IT_obstacle 80 Obstacle item



Gameobject record
ID Size Function Value
503 IT_gameobject 8 Header [503, 104]
5 ATOM_type 12 Integer item (flags)
1 ATOM_x 12 Integer item (divide by 8) x-pos
2 ATOM_y 12 Integer item (divide by 8) y-pos
6 ATOM_radius 12 Integer item (divide by 8) radius
7 ATOM_dir 12 Integer item  ??? direction
11 ATOM_id1 12 Integer item  ??? node ID
12 ATOM_unitid 12 Integer item Unit ID
13 ATOM_id3 12 Integer item  ??? script ID

Linear Layout and Building Blocks

The BTB file consists of chunks of the form: 

struct CHUNK_HEADER
{
  unsigned int chunkType;
  unsigned int chunkSize; // excluding header
};

Each chunk consists of 'records' which are similar to chunks, but the record size is inclusive of the header. 

struct RECORD_HEADER
{
  unsigned int recordType;
  unsigned int recordSize; // including header
};

When coordinates are referenced in the BTB file, divide them by eight to get into the same coordinates as the terrain mesh.

Overall File Structure

The observed format of the BTB files in Dark Omen follows in order: 

START/END CHUNK, type=0xBEAFEED0, size=0

HEADER CHUNK, type=1, size=240
UNKNOWN CHUNK, type=2, size=<varies>
OBSTACLES CHUNK, type=3, size=<varies>
   
REGION CHUNK 0, type=4, size=<varies>
REGION CHUNK 1, type=4, size=<varies>
.
.
.
REGION CHUNK n, type=4, size=<varies>
   
GAME OBJECT CHUNK, type=5, size=<varies>

START/END CHUNK, type=0xBEAFEED0, size=0

Chunk Descriptions

Start/End Chunk

This chunk is just a marker of the start/end of the file; it contains no data


Header Chunk 

HEADER CHUNK, type=1, size=240
   INTEGER RECORD (Map width) type=1, size=12
   INTEGER RECORD (Map height) type=2, size=12
   STRING RECORD (Mercenary Army file name without extension) type=1001, size=40
   STRING RECORD (Enemy Army file name without extension) type=1002, size=40
   STRING RECORD (CTL filename without extension) type=1003, size=40
   STRING RECORD ("/0") type=1004, size=40
   STRING RECORD ("/0") type=1005, size=40
   2-TUPLE RECORD ( [Number of Regions in file, Number of line segments in all regions] ) type=9, size=16


Objectives Chunk

This chunk is made up of several 3-tuples, which contain information about the objectives for this scenario. 

OBJECTIVES CHUNK, type=2, size=<varies>
   3-TUPLE RECORD 0 (unknown) type=3, size=20
   3-TUPLE RECORD 1 (unknown) type=3, size=20 
   .
   .
   .
   3-TUPLE RECORD n (unknown) type=3, size=20

Each tuple is interpreted as: 

(Objective Code, data1, data2)

In SotHR, the objective code is a letter from A-Z, I haven't seen an Objective Code that is greater than 26, so it seems like this may carry over.

Objective
Code 		Description Data 1 Data 2 Effect
C Defines Critical Unit Lose Condition Unique unit ID of critical unit Unknown ex (C, 1, 0) states that Morgan Bernhardt (unit id 1) must not die.


Obstacles Chunk

This chunk seems to contain information about obstacles on the map (e.g. trees). Increase the Integer Record by a higher value (e.g. +10) to avoid crashes in non-official Multiplayer maps. This might imply that the number (type=8) corresponds to an amount of memory to allocate for something. 

OBSTACLES CHUNK, type=3, size=<varies>
   INTEGER RECORD (unknown) type=8, size=12

   COMPOUND RECORD 0 (contains sub-records) type=501, size=80
      INTEGER RECORD (type of obstacle - might be bit flags - see table below) type=5, size=12
      INTEGER RECORD (x position) type=1, size=12
      INTEGER RECORD (y position) type=2, size=12
      INTEGER RECORD (z position) type=4, size=12
      INTEGER RECORD (radius of bounding sphere) type=6, size=12
      INTEGER RECORD (direction - normally 0) type=7, size=12
   COMPOUND RECORD 1 (contains sub-records) type=501, size=80
   .
   .
   .
   COMPOUND RECORD n (contains sub-records) type=501, size=80
Type Description
1 This obstacle is active
2 This obstacle blocks movement into its area
4 This obstacle blocks movement and projectiles into its area

n.b. some of the above information is guessed by analogy to the text script files found in SotHR


Region Chunk

This chunk contains information which delimits an area or path. It primarily consists of a list of line segments which define the path or polygon. These areas and paths seem to be used for a variety of reasons, some of which are listed below. 

REGION CHUNK, type=4, size=<varies>
   STRING RECORD (the human-readable name of the region) type=1006, size=40
   INTEGER RECORD (type code - might be bit flags - see table below) type=5, size=12
   2-TUPLE RECORD ([starting X position, starting Y position]) type=10, size=16
   4-TUPLE RECORD 0 ([ line start X, line start Y, line end X, line end Y]) type=502, size=24
   4-TUPLE RECORD 1 ([ line start X, line start Y, line end X, line end Y]) type=502, size=24
   .
   .
   .
   4-TUPLE RECORD n ([ line start X, line start Y, line end X, line end Y]) type=502, size=24


Bit Value Description
0 1 Always seems to be set
1 2 Closed areas have this bit set
2 4 Paths have this bit set
3 8 Unknown at this time
4 16 About half of the movement boundaries have this bit set
5 32 The Battle Region has this bit set
6 64 Unknown at this time
7 128 The other half of the movement boundaries have this bit set
8 256 Player 1 deployment area has this bit set
9 512 Player 2 deployment area has this bit set
10 1024 The Visible Region has this bit set


Game Objects Chunk

This chunk seems to hold a lot of the game-related info, for example initial enemy deployment, triggers for mission events, movement targets for the enemy AI. 

GAME OBJECTS CHUNK, type=5, size=<varies>
   INTEGER RECORD (the number of game object compound records in this chunk) type=8, size=12

   COMPOUND RECORD 0 (contains sub-records and represents a game object) type=503, size=104
      INTEGER RECORD (type of game object - might be bit flags - see table below) type=5, size=12
      INTEGER RECORD (x position) type=1, size=12
      INTEGER RECORD (y position) type=2, size=12
      INTEGER RECORD (radius of area) type=6, size=12
      INTEGER RECORD (direction) type=7, size=12
      INTEGER RECORD (Script ID?) type=11, size=12
      INTEGER RECORD (Unit ID) type=12, size=12
      INTEGER RECORD (Node ID?) type=13, size=12
   COMPOUND RECORD 1 (contains sub-records and represents a game object) type=503, size=104
   .
   .
   .
   COMPOUND RECORD n (contains sub-records and represents a game object) type=503, size=104

Questions

1) What does the "direction" value say? There is a orientation value in PRJ->TERR for each graphical instance, but what extra information does BTB->ITEM->direction bring?

Well, it seems to me that quite often it will not be used, but for the initial positions of troops etc. the orientation is probably relevant Rob 14:01, 1 January 2009 (UTC)

2) Is the Z position also multiplied by 8 by default?

3) Not having the SotHR data files on my computer, the A--Z interpretation sounds plausible. If we assume that the basic framework from SotHR is carried over do DO (SotHR in fact has more varied mission types than DO, so it is unlikely that DO has extended the SotHR objectives model), do we have the SotHR objectives in more-or-less plaintext?

Retrieved from "http://wiki.dark-omen.org/do/DO/BTB"
Personal tools
communication