Körperbewegung

mods/modlib/doc/minetest/conf.md

@@ -0,0 +1,31 @@
+# Configuration
+
+## Legacy
+
+1. Configuration is loaded from `<worldpath>/config/<modname>.<extension>`, the following extensions are supported and loaded (in the given order), with loaded configurations overriding properties of previous ones:
+   1. [`json`](https://json.org)
+   2. [`lua`](https://lua.org)
+   3. [`luon`](https://github.com/appgurueu/luon), Lua but without the `return`
+   4. [`conf`](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt)
+2. Settings are loaded from `minetest.conf` and override configuration values
+
+## Locations
+
+0. Default configuration: `<modfolder>/conf.lua`
+1. World configuration: `config/<modname>.<format>`
+2. Mod configuration: `<modfolder>/conf.<format>`
+3. Minetest configuration: `minetest.conf`
+
+## Formats
+
+1. [`lua`](https://lua.org)
+   * Lua, with the environment being the configuration object
+   * `field = value` works
+   * Return new configuration object to replace
+2. [`luon`](https://github.com/appgurueu/luon)
+   * Single Lua literal
+   * Booleans, numbers, strings and tables
+3. [`conf`](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt)
+   * Minetest-like configuration files
+4. [`json`](https://json.org)
+   * Not recommended

mods/modlib/doc/minetest/schematic.md

@@ -0,0 +1,79 @@
+# 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.

mods/modlib/doc/minetest/texmod.md

@@ -0,0 +1,39 @@
+# Texture Modifiers
+
+## Specification
+
+Refer to the following "specifications", in this order of precedence:
+
+1. [Minetest Docs](https://github.com/minetest/minetest_docs/blob/master/doc/texture_modifiers.adoc)
+2. [Minetest Lua API](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt), section "texture modifiers"
+3. [Minetest Sources](https://github.com/minetest/minetest/blob/master/src/client/tile.cpp)
+
+## Implementation
+
+### Constructors ("DSL")
+
+Constructors are kept close to the original forms and perform basic validation. Additionally, texture modifiers can directly be created using `texmod{type = "...", ...}`, bypassing the checks.
+
+### Writing
+
+The naive way to implement string building would be to have a
+`tostring` function recursively `tostring`ing the sub-modifiers of the current modifier;
+each writer would only need a stream (often passed in the form of a `write` function).
+
+The problem with this is that applying escaping quickly makes this run in quadratic time.
+
+A more efficient approach passes the escaping along with the `write` function. Thus a "writer" object `w` encapsulating this state is passed around.
+
+The writer won't necessarily produce the *shortest* or most readable texture modifier possible; for example, colors will be converted to hexadecimal representation, and texture modifiers with optional parameters may have the default values be written.
+You should not rely on the writer to produce any particular of the various valid outputs.
+
+### Reading
+
+**The reader does not attempt to precisely match the behavior of Minetest's shotgun "parser".** It *may* be more strict in some instances, rejecting insane constructs Minetest's parser allows.
+It *may* however sometimes also be more lenient (though I haven't encountered an instance of this yet), accepting sane constructs which Minetest's parser rejects due to shortcomings in its implementation.
+
+The parser is written *to spec*, in the given order of precedence.
+If a documented construct is not working, that's a bug. If a construct which is incorrect according to the docs is accepted, that's a bug too.
+Compatibility with Minetest's parser for all reasonable inputs is greatly valued. If an invalid input is notably used in the wild (or it is reasonable that it may occur in the wild) and supported by Minetest, this parser ought to support it too.
+
+Recursive descent parsing is complicated by the two forms of escaping texture modifiers support: Reading each character needs to handle escaping. The current depth and whether the parser is inside an inventorycube need to be saved in state variables. These could be passed on the stack, but it's more comfortable (and possibly more efficient) to just share them across all functions and restore them after leaving an inventorycube / moving to a lower level.