modlib/doc/b3d.md

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.

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)

This example from 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

The Ghosts mod extracts triangle sets using the B3D module to then approximate the player shape using particles picked from these triangles.

Animating the player

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

This example from the 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).