Add b3d module documentation

doc/b3d.md

@@ -0,0 +1,79 @@
+# B3D Reader & Writer
+
+## `b3d.read(file)`
+
+Reads from `file`, which is expected to provide `file:read(nbytes)`. `file` is not closed.
+
+Returns a B3D model object.
+
+## `:write(file)`
+
+Writes the B3D model object `self` to `file`.
+
+`file` must provide `file:write(bytestr)`. It should be in binary mode.
+It is not closed after writing.
+
+## `:write_string()`
+
+Writes the B3D model object to a bytestring, which is returned.
+
+## `:to_gltf()`
+
+Returns a glTF JSON representation of `self` in Lua table format.
+
+## `:write_gltf(file)`
+
+Convenience function to write the glTF representation to `file` using modlib's `json` writer.
+
+`file` must provide `file:write(str)`. It is not closed afterwards.
+
+## Examples
+
+### Converting B3D to glTF
+
+This example loops over all files in `dir_path`, converting them to glTFs which are stored in `out_dir_path`.
+
+```lua
+local modpath = minetest.get_modpath(minetest.get_current_modname())
+local dir_path = modpath .. "/b3d"
+local out_dir_path = modpath .. "/gltf"
+for _, filename in ipairs(minetest.get_dir_list(dir_path, false --[[only files]])) do
+	-- First read the B3D
+	local in_file = assert(io.open(dir_path .. "/" .. filename, "rb"))
+	local model = assert(b3d.read(in_file))
+	in_file:close()
+	-- Then write the glTF
+	local out_file = io.open(out_dir_path .. "/" .. filename .. ".gltf", "wb")
+	model:write_gltf(out_file)
+	out_file:close()
+end
+```
+
+### [Round-trip (minifying B3Ds)](https://github.com/appgurueu/modlib_test/blob/f11c8e580e90454bc1adaa11a58e0c0217217d90/b3d.lua)
+
+This example from [`modlib_test`](https://github.com/appgurueu/modlib_test) reads, writes, and then reads again,
+in order to verify that no data is lost through writing.
+
+Simply re-writing a model using modlib's B3D writer often reduces model sizes,
+since for example modlib does not write `0` weights for bones.
+
+Keep in mind to use the `rb` and `wb` modes for I/O operations
+to force Windows systems to not perform a line feed normalization.
+
+### [Extracting triangle sets](https://github.com/appgurueu/ghosts/blob/42a9eb9ee81fc6760a0278d23e4c47bc68bb4919/init.lua#L41-L79)
+
+The [Ghosts](https://github.com/appgurueu/ghosts/) mod extracts triangle sets using the B3D module
+to then approximate the player shape using particles picked from these triangles.
+
+### [Animating the player](https://github.com/appgurueu/character_anim/blob/c48b282c0b42b32294ec2fddc03aa93141cbd894/init.lua#L213)
+
+[`character_anim`](https://github.com/appgurueu/character_anim/) uses the B3D module to determine the bone overrides required
+for animating the player entirely Lua-side using bone overrides.
+
+### [Generating a Go board](https://github.com/appgurueu/go/blob/997ce85260d232a05dd668c32c6854bf34e3d5be/build/generate_models.lua)
+
+This example from the [Go](https://github.com/appgurueu/go) mod generates a Go board
+where for each spot on the board there are two pieces (black and white),
+both of which can be moved out of the board using a bone.
+
+It demonstrates how to use the writer (and how the table structure roughly looks like).