File format

This article is a stub. You can help us by expanding it

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.


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.


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.

VECTOR4f Tag (15)

Four float values. This tag has never been seen in starmade files but it's deduced from tag 241 used to encode color data (RGBA).

FLOAT16 Tag (16)

Sixteen float values.

Anonym FLOAT16 Tag (240)

Same as FLOAT16 Tag(16) but there's no name.

Anonym VECTOR4f Tag (241)

Same as VECTOR4f Tag(15) but there's no name.

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 VECTOR3b Tag (245)

Same as VECTOR3b Tag(11) 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 BYTE ARRAY Tag (249)

Same as BYTE ARRAY Tag(7) 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.

start type
0 int unknown int
4 int entity type
8 float[3] 3d float vector (bounding box of ship)
20 float[3] 3d float vector (bounding box of ship)
32 int number of block table entries (N)
36 blockEntry[N] block entry

blockEntry is a 6 byte value

start type
0 short blockID
2 int blockQuantity

Known entity types:

value type
0 ship
2 spacestation
3 asteroid

Logic Files (.smbpl)

Logic files are associated with a blueprint. It contains the list of controller and controlled blocks.

start type
0 int unknown int
4 int numControllers (N)
8 controllerEntry[N]

controllerEntry is a variable length struct

0 short[3] Position of the controller block, for example the core is defined at (8, 8, 8)
12 int Number of groups of controlled blocks. (M)
16 groupEntry[M] Example

groupEntry is a variable length struct

start type
0 short Block ID for all blocks in this group
2 int Number of blocks in the group (I)
6 short[3][I] Array of blocks positions for each of the I blocks

Meta Files (.smbpm)

start type
0 int Unknown int
4 byte Unknown byte
5 int number of dockEntry (docked ship/turrets)
9 dockEntry[N] Data about each docked ship/turret.
vary byte Unknown byte
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:

start type
0 int Length of the string giving attached ship's subfolder
4 wchar[N] Ship Subfolder given in modified UTF-8 encoding
vary int[3] q vector, the location of the dock block
vary float[3] a vector, ???

tagStruct encodes variety of data types in a tree structure

start type
0 byte tag type
1 int length of the tag name string
5 wchar[N] tag name string in modified UTF-8 encoding
vary vary tag data

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)

start type
0 int unknown int
4 chunkIndex[16][16][16] chunkIndex struct (see below) arranged in a 16x16x16 array
32772 long[16][16][16] 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

start type
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

start type
long timestamp Unix timestamp in milliseconds
int[3] q Relative chunk position
byte type Chunk type (?) usually 0x1
int inlen Compressed data length
byte data[inlen] ZLIB-compressed data of rawChunkData[16][16][16]
byte padding[] Zero padded to 5120 byte boundary

rawChunkData is a 3 byte bitfield

23-21 orientation
20-13 hitpoints
12 isActive
11-0 blockID

Corner block use 256 extra hp to define its orientation

See also

Code for reading and writing these file formats can be found in the GIT repository here.

Need wiki hosting?

Do you need a wiki for your Minecraft mod/gaming wiki? We'll host it for free! Contact us.

Other wikis

Indie-game wikis
Powered by Indie Wikis
Looking for a server?

Join Techworld - an amazing custom modpack server.