diff --git a/modlib/read_b3d.lua b/modlib/read_b3d.lua index 8369873..6aed92f 100644 --- a/modlib/read_b3d.lua +++ b/modlib/read_b3d.lua @@ -1,4 +1,7 @@ --- parse .b3d files into a lua table. +-- +-- This is apart of the [LEEF-b3d](https://github.com/Luanti-Extended-Engine-Features/LEEF-b3d) module +-- -- note: capitlization of name indicates a "chunk" defined by the blitz3d format (see b3d_specification.txt) --@module b3d_reader @@ -20,7 +23,7 @@ end --reads a model directly (based on name). Note that "node_only" abstracts chunks not necessary to finding the position/transform of a bone/node. --- read b3d models by their name. This simplifies read_from_stream. --- @function leef.b3d_reader.read_model +-- @function read_model -- @param modelname string, the name of model you are trying to read. -- @param node_only bool, specifies wether to ignore textures, meshes, or anything else. Use this if you're only trying to solve bone transforms. -- @return b3d table (documentation needed!) @@ -68,14 +71,24 @@ end -- @field 8 "KEYS" keyframes -- @table chunks +--- table which specifies a keyframe. This is apart of the node chunk +--@field position position relative to parent {x,y,z} +--@field rotation quaternion rotation {x,y,z,w} +--@field scale scale of the node {x,y,z} +--@table keyframe + +--- node paths +-- a list of nodes indexed by a hieracrchy of nodes i.e. "path.to.node" +--@field (...) node +--@table node_paths + --- read directly from file --- @function leef.b3d_reader.read_from_stream --- @param stream the file object (from the io library) to read from. Make sure you open it as "rb" (read binary.) --- @param ignore_chunks a list of @{chunks} to be ignored (documentation needed) --- @return @{BB3D} (documentation needed!) +--@function read_from_stream +--@param stream the file object (from the io library) to read from. Make sure you open it as "rb" (read binary.) +--@param ignore_chunks a list of @{chunks} to be ignored (documentation needed) +--@return @{BB3D} (documentation needed!) function leef.b3d_reader.read_from_stream(stream, ignore_chunks) local left = 8 - local ignored = {} if ignore_chunks then for i, v in pairs(ignore_chunks) do @@ -160,10 +173,13 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks) local node_chunk_types = { } + --- chunks + --@section chunks local chunk local chunks = { TEXS = function() + local textures = {} while content() do local tex = {} @@ -295,12 +311,8 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks) local bone = { flags = flags } + --see keyframe documentation while content() do - --- table which specifies a keyframe - --@position position relative to parent {x,y,z} - --@rotation quaternion rotation {x,y,z,w} - --@scale = {x,y,z} - --@table keyframe local frame = {} --minetest uses a zero indexed frame system, so for consistency, we offset it by 1 frame.frame = int()-1 @@ -399,15 +411,15 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks) end) return node end, - --- b3d table - -- note: in the b3d writer the node_paths field is ignored - -- @field node_paths all of the nodes in the model @{b3d_nodes} - -- @field node a table containing the root @{NODE} of the model. - -- @field textures @{TEXS} texture information - -- @field brushes @{BRUS} material information - -- @field version `{major=float, minor=float}` this functionally means nothing, but it's version information. - -- @table BB3D BB3D = function() + --- b3d table + -- note: in the b3d writer the node_paths field is ignored + -- @field node_paths all of the nodes in the model @{b3d_nodes} + -- @field node a table containing the root @{NODE} of the model. + -- @field textures TEXS texture information. TEXS not currently documented as not currently useful for minetest purposes + -- @field brushes BRUS material information. BRUS not currently documented as not currently useful for minetest purposes + -- @field version `{major=float, minor=float}` this functionally means nothing, but it's version information. + -- @table BB3D local version = int() local self = { version = { @@ -476,6 +488,7 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks) end local self = chunk{BB3D = true} + -- see node_paths documentation self.node_paths = {} self.excluded_chunks = ignore_chunks and table.copy(ignore_chunks) or {} assert(self.node, "no root node - model improperly exported. If using blender, ensure all objects are selected before exporting.") @@ -483,9 +496,4 @@ function leef.b3d_reader.read_from_stream(stream, ignore_chunks) --b3d metatable unimplemented return setmetatable(self, leef._b3d_metatable or {}) -end - ---- node paths --- a list of nodes indexed by a hieracrchy of nodes i.e. "path.to.node" --- @field (...) node --- @table node_paths \ No newline at end of file +end \ No newline at end of file diff --git a/modlib/to_gltf.lua b/modlib/to_gltf.lua index b8c738d..f3d89d4 100644 --- a/modlib/to_gltf.lua +++ b/modlib/to_gltf.lua @@ -3,7 +3,7 @@ --THIS FILE IS INACTIVE, VERY BROKEN ---possibly unreliable, appgurueu (creator) says: +--appgurueu: -- B3D to glTF converter -- See https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html --! Highly experimental; expect bugs! diff --git a/modlib/write_b3d.lua b/modlib/write_b3d.lua index 42eb84d..3c6d0c5 100644 --- a/modlib/write_b3d.lua +++ b/modlib/write_b3d.lua @@ -1,4 +1,7 @@ ---- writes b3d models in the same format as outputted by the b3d reader module +--- writes b3d models in the same format as outputted by the b3d reader modul +-- +-- This is apart of the [LEEF-b3d](https://github.com/Luanti-Extended-Engine-Features/LEEF-b3d) module +-- --@module b3d_writer @@ -218,7 +221,7 @@ local function write_rope(self) end --- output a string of binary in the blitz 3d format --- @function leef.b3d_writer.write_string +-- @function write_string -- @param self @{BB3D} -- @return string containing the binary file function leef.b3d_writer.write_string(self) @@ -226,7 +229,7 @@ function leef.b3d_writer.write_string(self) end --- output in the blitz3d format file reference --- @function leef.b3d_writer.write_model_to_file +-- @function write_model_to_file -- @param self @{BB3D} -- @param stream io file object to write to function leef.b3d_writer.write_model_to_file(self, stream) diff --git a/nodes.lua b/nodes.lua index c9f8476..4093989 100644 --- a/nodes.lua +++ b/nodes.lua @@ -1,6 +1,8 @@ --- allows you to get information about nodes (bones or meshes) within a b3d table (generated with `b3d_reader`) ---- located in `leef.b3d_nodes`. ---- WARNING! leef_math must be present for this module to run! +-- +-- This is apart of the [LEEF-b3d](https://github.com/Luanti-Extended-Engine-Features/LEEF-b3d) module +-- +-- WARNING! This LEEF-b3d submodule depends on the [LEEF-math](https://github.com/Luanti-Extended-Engine-Features/LEEF-math) --@module b3d_nodes --@warning for this module leef_math is required, trying to use these functions without leef_math ran will error. @@ -12,7 +14,6 @@ local mat4 = leef.math.mat4 local quat = leef.math.quat --- get a node by it's name --- @function leef.b3d_nodes.get_node_by_name -- @param self the b3d table (from b3d_reader) -- @param node_name the name of the node to fine -- @param is_bone (optional) bool to indicate wether the node is a bone or not (incase there's a mesh named the same thing). False will only return meshes and pivots, true will only return bones. Nil will return any. @@ -45,7 +46,6 @@ end --- get the local "TRS" (translation, rotation, scale) of a bone in animation. This is used for global transformation calculations. --- quaternion is returned as a string indexed table because it needs to be a math object to be interpolated, also has to be usable anyway. --- @function leef.b3d_nodes.get_animated_local_trs -- @param node table, the node from within a b3d table to read (as outputed by b3d_reader). -- @param target_frame float, the frame to find the TRS in, can be inbetween frames/keyframes (of course). -- @return `position` ordered table: {x, y, z} @@ -90,7 +90,6 @@ end --param 3 (outputs) is either "rotation" or "transform"- determines what's calculated. You can use this if you dont want uncessary calculations. If nil outputs both --- get a node's global mat4 transform and rotation. --- @function leef.b3d_nodes.get_node_global_transform -- @param node table, the node from within a b3d table to read (as outputed by `b3d_reader`). -- @param frame float, the frame to find the transform and rotation in. -- @param outputs (optional) string, either "1" or "2" where 1 will output the transform alone and 2 will output the rotation alone. Set to nil to return both. @@ -137,7 +136,6 @@ end --Returns X, Y, Z. is_bone is optional, if "node" is the name of a node (and not the node table), parameter 1 (self) and parameter 3 (is_bone) is used to find it. --- find the position of a node in global model space. ---@function leef.b3d_nodes.get_node_global_position --@param self b3d table, (optional if node is a node table and not name) --@param node string or table, either the node from b3d table or a the name of the node to find. --@param is_bone (optional) if node is string, this is used to find it (see `get_node_by_name`) @@ -156,7 +154,6 @@ function b3d_nodes.get_node_global_position(self, node, is_bone, frame) return transform[13], transform[14], transform[15] end --- find the global rotation of a node in model space. ---@function leef.b3d_nodes.get_node_rotation --@param self b3d table, (optional if node is a node table and not name) --@param node string or table, either the node from b3d table or a the name of the node to find. --@param is_bone (optional) if node is string, this is used to find it (see `get_node_by_name`)