View source for Blotter File Format/v7

The Blotter File Format, successor to the format known as ".tung files", is a system for storing the components and wires of a Logic World world. It is used for both full world saves as well as partial worlds (the data structure used by Subassemblies), but there are slight differences between the two.

= File types =

* '''World files:'''
** Represent a full, playable world space
** May have zero or more root components at different positions/rotations in the world
** Use <code>.logicworld</code> file extension
** All circuit states are stored contiguously, from circuit state 0 through the highest state.
* '''PartialWorld files:'''
** Represent a substructure within a playable world space; can be loaded and added to a world with each root at an arbitrary position/rotation
** Must have at least one root component
** Use <code>.partialworld</code> file extension
** Has a list of circuit state indexes that are On. All indexes not listed here are inferred as being Off.

== File structure ==

* [[#Header|Header]] (16 bytes)
* '''Save info'''
** [[#Save_Format_Version|Save Format Version]] (1 byte)
** [[#Game_version|Game version]] (16 bytes)
** [[#Save_type|Save type]] (1 byte)
** [[#Component_and_wire_counts|Number of components and wires]] (8 bytes)
** [[#Mod_versions|Mod versions]] (4+ bytes, dependent on the number of mods in the save)
** [[#Component_IDs_Map|Component IDs Map]] (4+ bytes, dependent on the number of loaded component IDs)
* '''Object data'''
** [[#Components_data|Components data]] (0+ bytes, dependent on the number of components)
** [[#Wires_data|Wires data]] (0+ bytes, dependent on the number of wires)
** [[#Circuit_states|Circuit states]] (4+ bytes, variable, has a different format for Worlds and PartialWorlds)
* [[#Footer|Footer]] (16 bytes)

The "Save Info" data is at the beginning of the file so that it is easy to extract as metadata. This is done by the game itself in a few places, as well as logicworld.net when uploading a save there.

== Header and footer ==

=== Header ===
The first 16 bytes of every Blotter file are <code>4C-6F-67-69-63-20-57-6F-72-6C-64-20-73-61-76-65</code>, which is UTF-8 for “Logic World save”.

=== Footer ===
The final 16 bytes of every Blotter file are <code>72-65-64-73-74-6F-6E-65-20-73-75-78-20-6C-6F-6C</code> , which is UTF-8 for “redstone sux lol”.

The header and footer exist to protect against save corruption. If the file does not have them, we know that something is wrong with the file.

== Save Format Version ==
One byte specifies the save format version. Currently this is <code>07</code>.

== Game version ==
16 bytes store the game [[#version|version]] that this save was created in.

== Save type ==
There are two types of file that use the Blotter format, Worlds and PartialWorlds. One byte specifies which type of file this is.
{| class="wikitable"
!Byte
!Meaning
|-
|<code>00</code>
|Unknown/error
|-
|<code>01</code>
|World
|-
|<code>02</code>
|PartialWorld
|-
|<code>03</code> - <code>FF</code>
|Reserved for future use
|}

== Component and wire counts ==
Here there are two [[#int|ints]]. The first specifies the number of components in the save, the second specifies the number of wires.

== Mod versions ==
Mods will be included if components they provide are used in this save. This is so that if a later mod version has changes, older save files can be converted.

* An [[#int|int]] for the number of mod versions stored in this file
* For each mod version:
** A [[#string|string]] for the text ID of the mod
** A [[#version|version]] for the version of the mod that this save was created with

== Component IDs Map ==
When humans add component types to Logic World, they use text IDs like <code>MHG.CircuitBoard</code>. To make save files and network packets small in size, the game internally uses numeric IDs to reference component types. The relationship between text IDs and numeric IDs is not deterministic or consistent between different save files, so the map from text IDs to numeric IDs must be stored with the save.

First we write an [[#int|int]] for the number of component IDs in this file.

One by one the mappings are written to the file:

* A 2-byte unsigned integer for the numeric ID of the component
* A [[#string|string]] for the text ID of the component

== Components data ==
One by one, every component is listed in the file. The first component must be a root component -- i.e. have an address of <code>C-0</code> for its parent -- and every subsequent component must have a parent that was listed before it.

It is explicitly okay to have a World file with no components in it (i.e. an empty world). However, a PartialWorld file must have at least one component.

Each component is written like so:

* The [[#component_address|component address]] of this component
* The [[#component_address|component address]] of the component's parent
* 2 bytes for the numeric ID of the component's type (see [[#Component_IDs_Map|Component IDs Map]])
* Three [[#int|ints]] for the local fixed position of the component; <code>x y z</code>
** One unit in the fixed position corresponds to a distance of 0.001 game units, or 1mm
* Four [[#float|floats]] for the local rotation of the component as a quaternion; <code>x y z w</code>
* Information about the component's inputs:
** An [[#int|int]] for the number of inputs the component has
** For each input:
*** An [[#int|int]] for the input's circuit state ID
* Information about the component's outputs:
** An [[#int|int]] for the number of outputs the component has
** For each output:
*** An [[#int|int]] for the output's circuit state ID
* The component's custom data:
** An [[#int|int]] for the number of bytes in the custom data
*** If the component has no custom data, <code>-1</code> may be written instead of <code>0</code>
** All the bytes of the custom data, in order

== Wires data ==
One by one, every wire is listed in the file.

* The [[#peg_address|peg address]] of the wire's first point
* The [[#peg_address|peg address]] of the wire's second point
* An [[#int|int]] for the wire's circuit state ID
* A [[#float|float]] for the wire's rotation, relative to the default rotation it would have

We do not need to save wire addresses; nothing in the save file needs to reference them, and there is no need for them to be consistent between save loads. Instead, wire addresses are dynamically assigned when the save is loaded.

== Circuit states ==
We've saved the circuit state IDs of all the pegs and wires in the save. Now we need to save the values of those state IDs, so states can be looked up.

A state is either on or off. At runtime, the game stores all circuit states from zero through the highest state in a contiguous block of memory.

=== World files ===
Worlds are large, and generally use most circuit states, starting from state 0. All circuit states are listed.

* First an [[#int|int]] for the number of bytes in this sequence
* Then, that number of bytes. Each bit represents the value of the next circuit state; each byte contains 8 states.
** If, when saving the game, the number of circuit states is not divisible by 8, the last byte will be padded.

=== PartialWorld files ===
PartialWorlds represent a subset of a World. Most of the circuit states in a world will be irrelevant to a particular PartialWorld, so it would be silly and wasteful to save all of them with every PartialWorld.
Instead, we save a list of circuit state IDs which are both used in this PartialWorld and have a state of on. All unlisted state IDs are assumed to be in the off state.

* First an [[#int|int]] for the number of ints in this sequence
* Then, that number of ints. Each int signifies a state ID with a value of on.

== Sub-standards ==

==== '''Int''' (4 bytes) <span id="int"></span> ====
32 bit signed integers, little endian.

==== '''Float''' (4 bytes) <span id="float"></span> ====
32 bit floating point values, little endian.

==== '''Boolean''' (1 byte) <span id="boolean"></span> ====
An entire byte that is either <code>00</code> for false or <code>01</code> for true.

==== '''String''' (4+ bytes) <span id="string"></span> ====
An int for the number of bytes in the string, followed by that number of bytes, representing that string in UTF-8.

==== '''Version''' (16 bytes) <span id="version"></span> ====
Versions contain four numbers (i.e. 1.0.3.1069). These four numbers are written to the file in order, each as a 4-byte int. Thus, 4x4 bytes = 16 bytes for this. Note: if any of these four numbers are missing, they will be saved as <code>-1</code>. So if your mod defines its version as <code>1.2</code>, the four numbers will be <code>1</code>, <code>2</code>, <code>-1</code>, <code>-1</code>. This is not our fault, it's just how System.Version works.

==== '''Component Address''' <span id="component_address"></span> (4 bytes) ====
Component Addresses are written as 32 bit unsigned integers, little endian.

==== '''Peg Address''' (9 bytes) <span id="peg_address"></span> ====

* One byte to indicate the peg type:

{| class="wikitable"
!Byte
!Meaning
|-
|<code>00</code>
|Undefined
|-
|<code>01</code>
|Input peg
|-
|<code>02</code>
|Output peg
|-
|<code>03</code> - <code>FF</code>
|Reserved for future use
|}
Any value other than <code>01</code> or <code>02</code> is invalid.

* A component address for the component of the peg
* An int for the zero-based index of the peg (i.e. is it the 0th input, the 1st input, etc)

== A note on seemingly-bizarre design choices ==
This file structure is not the most efficient, most beautiful, or most logical way to lay out the data. The primary purpose of the design of the Blotter format is that it is easy to integrate them with the game code. Therefore, the format uses the exact same data structures used by the game. This makes it fast and simple to convert the game state to a save file and vice versa, but since these data structures are optimized for runtime, the files do look a little weird.

* '''"Why are circuit states stored so weirdly? Why not directly save the state of an input/output, instead of a reference to a state index?"'''
** This is how the game stores circuit states at runtime, for performance and for ease of synchronization between the client and server. Storing it this way in the file makes for easy interoperability with the runtime game code, and allows us to use the same component/wire data structures in the saves and in the game.
* '''"Must all the circuit states be stored? Surely you only need the states of the inputs or outputs, and everything else (including the wires) can be inferred from those."'''
** This is true for the server, but the client has no ability to run a simulation and infer other states. However, the client needs to know all the states so that it can render a PartialWorld correctly before it is placed and added to the server's world/simulation. Storing all the states is also just simpler, and requires fewer steps when loading a save.
* '''"Why in god's name are all the integers signed when come on they really should be unsigned?"'''
** Logic World is written in C#. The .NET runtime has a few weird quirks, and one of those quirks is that most integers are signed, even things that can never be below zero like array lengths and indexes. Since this file format is designed for maximum interoperability with the code, this quirk is copied, and we use signed ints a lot.