Skip to content

Instantly share code, notes, and snippets.

@Loupau38

Loupau38/S2-blueprint-codes-specifications.md

Last active July 22, 2025 16:24
Show Gist options
  • Save Loupau38/77907c80c7be3dd9f00a62d416581bb3 to your computer and use it in GitHub Desktop.
Save Loupau38/77907c80c7be3dd9f00a62d416581bb3 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
S2-blueprint-codes-specifications.md

Shapez 2 blueprint codes specifications

NOT from the devs
aka Loupau's understanding of blueprint codes

Last updated : 0.1.0-pre8-rc1

To sart, a blueprint code is structured as follows :

prefix + separator + version + separator + blueprint + suffix

Note : + are not included, instead all parts are joined together without anything inbetween

With :

  • prefix : SHAPEZ2
  • separator : -
  • version : 3 starting from 0.1.0-pre1, 2 starting from 0.0.9, 1 before
  • blueprint : the blueprint json, gzip compressed then base64 encoded
  • suffix : $

The blueprint is a json object with the following keys :

  • "V" : number
    The version number like 1027 or 1015
  • "BP" : object
    A blueprint

Blueprint

type : object

Keys :

  • "$type" : string
    The blueprint type, can be "Building" or "Island"
  • "Icon" : object
    Icon information, contains a single "Data" key with its value being a list of 4 values representing each icon. Each value can be :
    • null : no icon
    • A string starting with icon: followed by an icon ID : a regular icon
    • A string starting with shape: followed by a shape code : a shape icon
  • "Entries" : list
    A list of building entries or island entries depending on the type
  • "BinaryVersion" : number
    Only for blueprints of "$type" : "Building", specifies the version of the building entries' additional data. Uses the same numbers as the main json object's "V" key

Building entry

type : object

Keys :

  • "X" : number
    The x offset from the blueprint center, can be omitted if 0
  • "Y" : number
    The y offset from the blueprint center, can be omitted if 0
  • "L" : number
    The layer/height/z offset from the blueprint center, can be omitted if 0
  • "R" : number
    The building's rotation ranging from 0 to 3, can be omitted if 0
  • "T" : string
    The building's type referred by it's internal name like "BeltDefaultForwardInternalVariant"
  • "C" : string
    The building's additional data (like text in labels, shape in producers), base64 encoded, can be omitted if empty (null / ""). More info

Island entry

type : object

Keys :

  • "X" : number
    The x offset from the blueprint center, can be omitted if 0
  • "Y" : number
    The y offset from the blueprint center, can be omitted if 0
  • "Z" : number
    The z offset from the blueprint center, can be omitted if 0
  • "R" : number
    The island's rotation ranging from 0 to 3, can be omitted if 0
  • "T" : string
    The island's type referred by it's internal name like "Layout_Normal_1"
  • "S" : string
    The island's additional data (like a rail's colors), base64 encoded, can be omitted if null. More info
  • "B" : object
    A blueprint of "$type" : "Building" representing the buildings on the island, omitted if there are none

Blueprint center

Blueprint centers work on building and island scale, they are a point to which the coordinates of buildings and islands refer to. For example, a building with coordinate X/Y/L : 0,0,0 is right on the blueprint center and with 1,0,0 it is 1 tile away from it in the positive X direction. Ingame, the X axis increases going from West to East, the Y axis from North to South and the Z axis from down to up. The game selects the blueprint center to be in the middle of the blueprint, but it is worth noting that it can be anywhere, even outside the blueprint.

Note : in the case of island blueprints, to be able to know where the buildings are on the island, an island entry's building blueprint has it's blueprint center in the north-west corner of the building grid of the island's center tile.

image

Entries additional data

The "C" key of building entries and the "S" key of island entries is base64 encoded bytes. What is called here the "standard encoding" is used in some entries' additional data, it consists of two starting bytes that contain the string's length (signed, little endian) then the string itself. If the string is empty then the length will be -1 (so \xff\xff).

Each type of building/island then has its own format :

  • Labels :
    The label's text uses the standard encoding except if its text is empty, it will be encoded with a length of 0 instead of -1 (so \x00\x00)

  • Item producers :
    For the item producer, the first two bytes indicate what item type is produced, currently can only be \x01\x01 for shapes, then the shape code will use the standard encoding. If the item producer produces nothing, it will be a single \x00 byte instead.

  • Fluid producers:
    For the fluid producer, the first byte will be \x01 then the next byte will be the fluid one letter color code. If the fluid producer produces nothing, it will be a single \x00 byte instead

  • Signal producers :
    For the signal producer, the first byte will indicate what type of signal it is generating then the potential next bytes will indicate the signal's value. Below is a table of what the first byte value corresponds to and what type of data it should have after :

    • 0 : recognized as valid by the game but doesn't correspond to anything
    • 1 : null
    • 2 : conflict
    • 3 : integer : next 4 bytes is the integer value (signed, little endian)
    • 4 : false (integer 0)
    • 5 : true (integer 1)
    • 6 : shape : next bytes represent the shape, encoded like in item producers
    • 7 : fluid : next bytes represent the fluid, encoded like in fluid producers

  • Buttons :
    Buttons encode their state as a single byte : 0 for off and 1 for on

  • Global signal receivers:
    The additional data will be \x00\x00\x00\x02

  • Operator signal receivers:
    The additional data will be \x00\x00\x00\x02 if the ROS#0 channel is selected, otherwise \x01\x00\x00\x02

  • Comparison gates :
    Comparison gates encode their compare mode as an int on one byte with :

    • 1 : Equal
    • 2 : GreaterEqual
    • 3 : Greater
    • 4 : Less
    • 5 : LessEqual
    • 6 : NotEqual

  • Train colors :
    Train colors are encoded as an unsigned little endian integer on 4 bytes :

    • the 64s place is set to 1 if yellow is selected
    • the 32s place for magenta
    • the 16s place for cyan
    • the 8s place for white
    • the 4s place for red
    • the 2s place for green
    • the 1s place for blue

  • Rails :
    The first byte is the number of inputs or outputs (whichever one is bigger) then the next bytes are as many train colors (encoded like indicated above) as what that first byte is, each one corresponding to which train colors are allowed for each connection.

  • Train unloaders, wagon transfers :
    The additional data is a series of integers, each encoded on 4 bytes, little endian. The first is the number of floors disabled for unloading, then the rest is all the disabled floor numbers (0-indexed).

Version differences

Older than alpha 8 :

  • Island blueprints don't exist
  • "$type" key of blueprints doesn't exist
  • The game never omits keys

Alpha 8 and newer :

  • The game always omits keys when possible

Older than alpha 19 :

  • Shape and fluid crates exist, this means when a shape code like shape:CuCuCuCu is expected, it can also be something like shapecrate:CuCuCuCu or fluidcrate:color-r
  • Magenta (color code m) is named purple (color code p)

Older than alpha 20 :

  • When a shape is encoded it has a shape: prefix
  • Item producers use the standard encoding for the item they produce
  • Fluid producers use the standard encoding for the color they produce with the color string being like color-r
  • The two points above also apply to signal producers producing shape or fluid signals
  • The color code k is valid

Older than alpha 22.2 :

  • Space belts, pipes and rails don't have the first byte in their additional data
  • Train loaders, unloaders, stops and depots don't have additional data

Older than alpha 22.3 :

  • The "$type" key of blueprints is optional and defaults to "Building"
  • The "Icon" key of blueprints doesn't exist
  • Islands with no additional data don't have a "C" key instead of the \x00 default

Older than alpha 23 :

  • Wire receivers don't have a 5th byte in their additional data

Older than alpha 23.2 :

  • The "BinaryVersion" key of blueprints doesn't exist

Older than 0.0.2 :

  • Train locomotives will have rails additonal data like loaders/unloaders

Older than 0.0.9 :

  • The key for additionnal data of islands is "C" instead of "S"
  • Global wire transmitters encoded their channel on 4 bytes and don't have anything else after them
  • Global wire receivers encode their channel on 4 bytes and the 5th byte is 2 for regular channels and 1 for OL
  • Space belt/pipes : The first byte is \x14, the next byte indicates the type of layout : 1 : regular connection (straight/corner), 2 : 2 way split/merge, 3 : 3 way split/merge, the next bytes are a concatenated list of pairs of bytes, each pair being the input and output of a connection, and each byte being a rotation ranging from 0 to 3
  • Space belt/pipe tunnels don't have any additionnal data
  • Rails use the same format as pre-0.0.9 space belts/pipes like described above, except that the first byte is \x0a and that there is train color bytes after each pair of byte representing which colors are allowed on that connection
  • Train loaders, unloaders, stops have the additionnal data of their rail
  • Belt/Pipe launchers/catchers, wire transmitters/receivers have no additionnal data
  • Islands default additionnal data is \x00 instead of null

Older than 0.1.0-pre1 :

  • Belt/Pipe launchers/catchers, wire transmitters/receivers have 5 bytes of additional data, undetermined format
  • Global wire tansmitters have a bunch of extra bytes at the end of their additional data, undetermined format
  • Space Belts/Pipes have some bytes of additional data, undetermined format
  • Train unloaders have no additional data

Older than 0.1.0-pre2 :

  • Global wire transmitters and receivers encode their channel number as a signed little endian integer on 3 bytes, with a 4th byte that can be either 1 if it uses the regular channels, or 2 if it uses operator level random shape lines. This last byte can thus only be 1 for transmitters.

Older than 0.1.0-pre3 :

  • Island entries have no "Z" key

External links

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment