Difference between revisions of "Minetest Schematic File Format"
m (→Overview: simplify) |
Rubenwardy (talk | contribs) (lua_api.txt -> lua_api.md) |
||
(6 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | The '''Minetest Schematic File Format''' if the file format used when schematics are seralized by e.g. | + | The '''Minetest Schematic File Format''' if the file format used when schematics are seralized by e.g. minetest.create_schematic. Schematic files are supposed to have “.mts” as a file name suffix. This document describes the MTS format native to Minetest. |
== Informal definition == | == Informal definition == | ||
Warning: This definition has not been proofread yet! Don't rely on it 100% yet. | Warning: This definition has not been proofread yet! Don't rely on it 100% yet. | ||
Line 62: | Line 62: | ||
Each node ID is stored on a big endian 2 bytes. Orientation is '''not''' defined in any way, there's absolutely no convention. | Each node ID is stored on a big endian 2 bytes. Orientation is '''not''' defined in any way, there's absolutely no convention. | ||
− | Probability values in <code>param1</code> are encoded | + | Probability values in <code>param1</code> are encoded in unsigned 8 bits. They are indexed the same way as node IDs. Probability ranges from 0 (0%) to 127 (100%). Bit 7 means force node placement, i.e. the node will be able to replace non-air nodes as well. |
− | (In legacy version 3, <code>param1</code>'s probability range | + | (In legacy version 3, <code>param1</code>'s probability range was from 0 to 0xFF, there's no force placement.) |
− | <code>param2</code> is an 8-bit value (0-255), the meaning depends on the node definition. See <code>lua_api. | + | <code>param2</code> is an 8-bit value (0-255), the meaning depends on the node definition. See <code>lua_api.md</code> to learn more about <code>param2</code> (keywords: “param2”, “paramtype2”). |
== Official definition == | == Official definition == | ||
− | The official definition of version 4 of this file format follows | + | The official definition of version 4 of this file format follows and has been copied from [https://github.com/minetest/minetest/blob/5.1.0/src/mapgen/mg_schematic.h /src/mapgen/mg_schematic.h] in the Minetest 5.1.0 source code. |
<pre> | <pre> | ||
Line 95: | Line 95: | ||
} | } | ||
</pre> | </pre> | ||
+ | |||
+ | * Source code 5.1.0: [https://github.com/minetest/minetest/blob/5.1.0/src/mapgen/mg_schematic.h /src/mapgen/mg_schematic.h] | ||
+ | * Source code bleeding edge: [https://github.com/minetest/minetest/blob/master/src/mapgen/mg_schematic.h /src/mapgen/mg_schematic.h] | ||
== Version changes == | == Version changes == | ||
Line 103: | Line 106: | ||
* 3—Added y-slice probabilities; this allows for variable height structures | * 3—Added y-slice probabilities; this allows for variable height structures | ||
* 4—Compressed range of node occurence probability, added per-node force placement bit (used since 0.4.16 or earlier) | * 4—Compressed range of node occurence probability, added per-node force placement bit (used since 0.4.16 or earlier) | ||
+ | |||
+ | [[Category:Core Engine]] |
Latest revision as of 11:18, 1 May 2023
The Minetest Schematic File Format if the file format used when schematics are seralized by e.g. minetest.create_schematic. Schematic files are supposed to have “.mts” as a file name suffix. This document describes the MTS format native to Minetest.
Informal definition
Warning: This definition has not been proofread yet! Don't rely on it 100% yet.
Overview
An MTS file has 3 sections, in this order:
- Header
- Name ID Table
- Node Definitions Section
All values are stored in big endian format.
Header
| Offset | Length | Description | |---------|--------|------------------------------------------| | 0 | 4 | magic number, ASCII letters "MTSM" | | 4 | 2 | file format version, currently 4 | | 6 | 2 | size X | | 8 | 2 | size Y | | 10 | 2 | size Z | | 12 | Y | layer probability values | | 12+Y | 2 | number of strings in Name ID Table |
Layer probability values: This is a sequence of unsigned 8-bit numbers (0-255) for each Y layer. Each Y layer has a chance of appearing with the given probability. The probability ranges from 0 to 127, with 0 meaning 0% probability and 127 meaning 100% probability. Bit 7 is reserved and must be 0, meaning that values greater than 127 should be avoided.
The header is followed by the Name ID Table, which is followed by the Node Definitons section.
Name ID Table
For each string, the following record format repeats:
| Offset | Length | Description | |--------|--------|--------------------------| | 0 | 2 | length of the string (N) | | 2 | N | string, node itemstring |
The node IDs in the next section reference these.
Node Definitons Section
This part of the file is zlib compressed, with the deflate algorithm using gz header bytes RFC 1950, but not with the gzip header which has magic bytes too. After uncompressing, the format is as follows:
| Offset | Length | Description | |---------|------------|------------------------------------------| | 0 | 2*X*Y*Z | node IDs (param0) | | 2*X*Y*Z | X*Y*Z | probability values (param1) | | 3*X*Y*Z | X*Y*Z | param2 |
To get the node ID from param0
for a given coordinate (x,y,z), you should calculate the index param0[(Z-z)*Z*Y + y*X + x]
.
That's right, the Z axis is mirrored.
Each node ID is stored on a big endian 2 bytes. Orientation is not defined in any way, there's absolutely no convention.
Probability values in param1
are encoded in unsigned 8 bits. They are indexed the same way as node IDs. Probability ranges from 0 (0%) to 127 (100%). Bit 7 means force node placement, i.e. the node will be able to replace non-air nodes as well.
(In legacy version 3, param1
's probability range was from 0 to 0xFF, there's no force placement.)
param2
is an 8-bit value (0-255), the meaning depends on the node definition. See lua_api.md
to learn more about param2
(keywords: “param2”, “paramtype2”).
Official definition
The official definition of version 4 of this file format follows and has been copied from /src/mapgen/mg_schematic.h in the Minetest 5.1.0 source code.
All values are stored in big-endian byte order. [u32] signature: 'MTSM' [u16] version: 4 [u16] size X [u16] size Y [u16] size Z For each Y: [u8] slice probability value [Name-ID table] Name ID Mapping Table [u16] name-id count For each name-id mapping: [u16] name length [u8[]] name ZLib deflated { For each node in schematic: (for z, y, x) [u16] content For each node in schematic: [u8] param1 bit 0-6: probability bit 7: specific node force placement For each node in schematic: [u8] param2 }
- Source code 5.1.0: /src/mapgen/mg_schematic.h
- Source code bleeding edge: /src/mapgen/mg_schematic.h
Version changes
As of Minetest 5.1.0, the current version of the MTS file format is 4.
- 1—Initial version
- 2—Fixed messy never/always place; the probability of
0
is now never, and0xFF
is always - 3—Added y-slice probabilities; this allows for variable height structures
- 4—Compressed range of node occurence probability, added per-node force placement bit (used since 0.4.16 or earlier)