modlib/doc/minetest/schematic.md

Schematic

A schematic format with support for metadata and baked light data.

Table Format

The table format uses a table with the following mandatory fields:

• size: Size of the schematic in nodes, vector
• node_names: List of node names
• nodes: List of node indices (into the node_names table)
• param2s: List of node param2 values (numbers)

and the following optional fields:

• light_values: List of node param1 (light) values (numbers)
• metas: Map from indices in the cuboid to metadata tables as produced by minetest.get_meta(pos):to_table()

A "vector" is a table with fields x, y, z for the 3 coordinates.

The nodes, param2s and light_values lists are in the order dictated by VoxelArea:iterp (Z-Y-X).

The cuboid indices for the metas table are calculated as (z * size.y) + y * size.x + x where x, y, z are relative to the min pos of the cuboid.

Binary Format

The binary format uses modlib's Bluon to write the table format.

Since param2s (and optionally light_values) are all bytes, they are converted from lists of numbers to (byte)strings before writing.

For uncompressed files, it uses MLBS (short for "ModLib Bluon Schematic") for the magic bytes, followed by the raw Bluon binary data.

For compressed files, it uses MLZS (short for "ModLib Zlib-compressed Schematic") for the magic bytes, followed by the zlib-compressed Bluon binary data.

API

schematic.setmetatable(obj)

Sets the metatable of a table obj to the schematic metatable. Useful if you've deserialized a schematic or want to create a schematic from the table format.

schematic.create(params, pos_min, pos_max)

Creates a schematic from a map cuboid

• params: Table with fields
  • metas (default true): Whether to store metadata
  • light_values: Whether to bake light values (param1). Usually not recommended, default false.
• pos_min: Minimum position of the cuboid, inclusive
• pos_max: Maximum position of the cuboid, inclusive

schematic:place(pos_min)

"Inverse" to schematic.create: Places the schematic self starting at pos_min.

Content IDs (nodes), param1s, param2s, and metadata in the area will be completely erased and replaced; if light data is present, param1s will simply be set, otherwise they will be recalculated.

schematic:write_zlib_bluon(path)

Write a binary file containing the schematic in zlib-compressed binary format to path. You should generally prefer this over schematic:write_bluon: zlib compression comes with massive size reductions.

schematic.read_zlib_bluon(path)

"Inverse": Read a binary file containing a schematic in zlib-compressed binary format from path, returning a schematic instance. You should generally prefer this over schematic.read_bluon: zlib compression comes with massive size reductions.

schematic:write_bluon(path)

Write a binary file containing the schematic in uncompressed binary format to path. Useful only if you want to eliminate the time spent compressing.

schematic.read_bluon(path)

"Inverse": Read a binary file containing a schematic in uncompressed binary format from path, returning a schematic instance. Useful only if you want to eliminate the time spent decompressing.