- 1 Entity Files (.ent)
- 1.1 FINISH Tag (0)
- 1.2 BYTE Tag (1)
- 1.3 SHORT Tag (2)
- 1.4 INT Tag (3)
- 1.5 LONG Tag (4)
- 1.6 FLOAT Tag (5)
- 1.7 DOUBLE Tag (6)
- 1.8 BYTE_ARRAY Tag (7)
- 1.9 STRING Tag (8)
- 1.10 VECTOR3f Tag (9)
- 1.11 VECTOR3i Tag (10)
- 1.12 VECTOR3b Tag (11)
- 1.13 LIST Tag (12)
- 1.14 STRUCT Tag (13)
- 1.15 SERIALIZABLE Tag (14)
- 1.16 UNKNOWN Tag (241)
- 1.17 Anonym STRUCT Tag (243)
- 1.18 Anonym LIST Tag (244)
- 1.19 Anonym VECTOR3i Tag (246)
- 1.20 Anonym VECTOR3f Tag (247)
- 1.21 Anonym STRING Tag (248)
- 1.22 Anonym DOUBLE Tag (250)
- 1.23 Anonym FLOAT Tag (251)
- 1.24 Anonym LONG Tag (252)
- 1.25 Anonym INT Tag (253)
- 1.26 Anonym SHORT Tag (254)
- 1.27 Anonym BYTE Tag (255)
- 2 Header Files (.smbph)
- 3 Logic Files (.smbpl)
- 4 Meta Files (.smbpm)
- 5 Ship Files (.smd2)
- 6 See also
Entity Files (.ent)
Entity files used a tagged format and include meta-data on a wide variety of object types. They mostly live in the "server-database" directory of StarMade.
The first two bytes of the file indicate if the file is saved with GZIP compression. If they are decimal 37, -117, then the remainder are zipped. If not, they can be read in the clear.
An entity file is composed of tags. Tags represent various primitive types, and aggregations of other tags or primitive types. A tag is composed of a single tag identifying the tag type, a name (in Java UTF format), and then specific data depending on the tag type. Unless specified otherwise, formats are per the Java standard for a DataInputStream.
FINISH Tag (0)
This tag marks the end of a sequence. It is special in that there is no data value associated with it.
BYTE Tag (1)
A single byte.
SHORT Tag (2)
A single short.
INT Tag (3)
A single int.
LONG Tag (4)
A single long.
FLOAT Tag (5)
A single float.
DOUBLE Tag (6)
A single double.
BYTE_ARRAY Tag (7)
An int, followed by that number of bytes.
STRING Tag (8)
A single UTF format String.
VECTOR3f Tag (9)
Three float values.
VECTOR3i Tag (10)
Three int values.
VECTOR3b Tag (11)
Three byte values.
LIST Tag (12)
First there is a byte, which is the tag type the list contains. Second is an int, which contains the number of elements in the list. Then there are that many value segments, according to the type given.
STRUCT Tag (13)
Struct is the main aggregate type. It is basically a sequence of other tags, and continues until a FINISH tag is given. Note: A STRUCT tag can contain other STRUCT tags.
SERIALIZABLE Tag (14)
This tag represents a data object that serializes itself in its own custom format. It is not self describing. There is no ID to indicate what sort of object it is. There is no length packet to work out how long it is to conveniently skip it if unknown. This information is encoded in the Java code that reads and writes specific files, not the data format itself.
The only known SERIALIZABLE tag at the moment is a ControlElement. This is effectively equal to the Logic File format given below, except that the initial int is, instead, a byte.
UNKNOWN Tag (241)
This tag marks is actually unknown, it's come with dev0.1 and the lenght is 136 bits.
Anonym STRUCT Tag (243)
Same as STRUCT Tag(13) but there's no name.
Anonym LIST Tag (244)
Same as LIST Tag(12) but there's no name.
Anonym VECTOR3i Tag (246)
Same as VECTOR3i Tag(10) but there's no name.
Anonym VECTOR3f Tag (247)
Same as VECTOR3f Tag(9) but there's no name.
Anonym STRING Tag (248)
Same as STRING Tag(8) but there's no name.
Anonym DOUBLE Tag (250)
Same as DOUBLE Tag(6) but there's no name.
Anonym FLOAT Tag (251)
Same as FLOAT Tag(5) but there's no name.
Anonym LONG Tag (252)
Same as LONG Tag(4) but there's no name.
Anonym INT Tag (253)
Same as INT Tag(3) but there's no name.
Anonym SHORT Tag (254)
Same as SHORT Tag(2) but there's no name.
Anonym BYTE Tag (255)
Same as BYTE Tag(1) but there's no name.
Header Files (.smbph)
Header files are associated with a blueprint. It contains the range for the contained blocks, and a manifest of the types and quantities.
|8||float||3d float vector (bounding box of ship)|
|20||float||3d float vector (bounding box of ship)|
|32||int||number of block table entries (N)|
blockEntry is a 6 byte value
Known entity types:
Logic Files (.smbpl)
Logic files are associated with a blueprint. It contains the list of controller and controlled blocks.
controllerEntry is a variable length struct
|0||short||Position of the controller block, for example the core is defined at (8, 8, 8)|
|12||int||Number of groups of controlled blocks. (M)|
groupEntry is a variable length struct
|0||short||Block ID for all blocks in this group|
|2||int||Number of blocks in the group (I)|
|6||short[I]||Array of blocks positions for each of the I blocks|
Meta Files (.smbpm)
|5||int||number of dockEntry (docked ship/turrets)|
|9||dockEntry[N]||Data about each docked ship/turret.|
|vary||short||Specifies if gzip compression is used on the tagStruct|
|vary||tagStruct||additional metadata in a tag structure|
dockEntry is a variable length struct:
|0||int||Length of the string giving attached ship's subfolder|
|4||wchar[N]||Ship Subfolder given in modified UTF-8 encoding|
|vary||int||q vector, the location of the dock block|
|vary||float||a vector, ???|
tagStruct encodes variety of data types in a tree structure
|1||int||length of the tag name string|
|5||wchar[N]||tag name string in modified UTF-8 encoding|
special tag types (see code for full list and encoding):
- 0x0 - End of tag struct marker -- no tag name or data follows this
- 0xD - Start of new tag struct
- 0xE - Serialized object (not yet implemented here)
Ship Files (.smd2)
|4||chunkIndex||chunkIndex struct (see below) arranged in a 16x16x16 array|
|32772||long||chunk timestamp information arranged in a 16x16x16 array|
Note that there may exist chunk timestamps and chunks that are not referenced in the chunkIndex table and seemingly serve no purpose.
chunkIndex is an 8 byte struct
|int||chunkId||Index into the chunkData array. If no chunk exists for this point in the array, chunkId = -1|
|int||chunklen||The total chunk size in bytes (excluding the zero padding). Equal to the chunk's "inlen" field plus 25 (the chunk header size)|
chunkData is a 5120 byte structure
|long||timestamp||Unix timestamp in milliseconds|
|int||q||Relative chunk position|
|byte||type||Chunk type (?) usually 0x1|
|int||inlen||Compressed data length|
|byte||data[inlen]||ZLIB-compressed data of rawChunkData|
|byte||padding||Zero padded to 5120 byte boundary|
rawChunkData is a 3 byte bitfield
Corner block use 256 extra hp to define its orientation
Code for reading and writing these file formats can be found in the GIT repository here.