>Rubenwardy: lua_api.txt -> lua_api.md

2023-05-01T11:18:09Z

lua_api.txt -> lua_api.md

New page

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 ===

<pre>
| 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 |
</pre>

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:

<pre>
| Offset | Length | Description |
|--------|--------|--------------------------|
| 0 | 2 | length of the string (N) |
| 2 | N | string, node itemstring |
</pre>

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
[http://tools.ietf.org/html/rfc1950 RFC 1950], but not with the gzip header which has magic bytes too. After uncompressing,
the format is as follows:

<pre>
| 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 |
</pre>

To get the node ID from <code>param0</code> for a given coordinate (x,y,z), you should calculate the index <code>param0[(Z-z)*Z*Y + y*X + x]</code>.
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 <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 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.md</code> to learn more about <code>param2</code> (keywords: “param2”, “paramtype2”).

== Official definition ==
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>
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
}
</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 ==
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 <code>0</code> is now never, and <code>0xFF</code> 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)

[[Category:Core Engine]]

Minetest Schematic File Format - Revision history

>Rubenwardy: lua_api.txt -> lua_api.md