luanti-extended-engine-features/leef-b3d-cd2025
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

expand documentation for b3d I/O, verified, enabled and fixed b3d writer (output) module

Browse Source
This commit is contained in:
FatalErr42O 2024-07-14 13:04:52 -07:00
parent 0ff4bced49
commit 9c20beabc6
10 changed files with 574 additions and 290 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
LICENSE
View File

@ -1,8 +1,5 @@
"/modlib/" sub directory: Copright (c) respective owner(s), see the directory
for it's respective license (License.txt). Once again note that the "/modlib/"
directory in this case is explicitly exempt from the following MIT License.
for all other files outside of "/modlib/" directory:
"/modlib/" directory: Copright (c) respective owners, see License.txt within the "/modlib/" directory.
All files outside of the modlib directory fall under the following license:
MIT License

7
docs/index.html
View File

@ -33,6 +33,7 @@
<h2>Modules</h2>
<ul class="nowrap">
<li><a href="modules/b3d_reader.html">b3d_reader</a></li>
<li><a href="modules/b3d_writer.html">b3d_writer</a></li>
<li><a href="modules/b3d_nodes.html">b3d_nodes</a></li>
</ul>
@ -49,6 +50,10 @@
<td class="name" nowrap><a href="modules/b3d_reader.html">b3d_reader</a></td>
<td class="summary">parse .b3d files into a lua table.</td>
</tr>
<tr>
<td class="name" nowrap><a href="modules/b3d_writer.html">b3d_writer</a></td>
<td class="summary">writes b3d models in the same format as outputted by the b3d reader module</td>
</tr>
<tr>
<td class="name" nowrap><a href="modules/b3d_nodes.html">b3d_nodes</a></td>
<td class="summary">allows you to get information about nodes (bones or meshes) within a b3d table (generated with <code>b3d_reader</code>)
@ -60,7 +65,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/lunarmodules/ldoc">LDoc 1.5.0</a></i>
<i style="float:right;">Last updated 2024-01-06 20:41:04 </i>
<i style="float:right;">Last updated 2024-07-12 19:17:47 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

33
docs/modules/b3d_nodes.html
View File

@ -40,6 +40,7 @@
<h2>Modules</h2>
<ul class="nowrap">
<li><a href="../modules/b3d_reader.html">b3d_reader</a></li>
<li><a href="../modules/b3d_writer.html">b3d_writer</a></li>
<li><strong>b3d_nodes</strong></li>
</ul>
@ -56,23 +57,23 @@
<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#get_node_by_name">get_node_by_name (self, node_name, is_bone)</a></td>
<td class="name" nowrap><a href="#mtul.b3d_nodes.get_node_by_name">mtul.b3d_nodes.get_node_by_name (self, node_name, is_bone)</a></td>
<td class="summary">get a node by it's name</td>
</tr>
<tr>
<td class="name" nowrap><a href="#get_animated_local_trs">get_animated_local_trs (node, target_frame)</a></td>
<td class="name" nowrap><a href="#mtul.b3d_nodes.get_animated_local_trs">mtul.b3d_nodes.get_animated_local_trs (node, target_frame)</a></td>
<td class="summary">get the local "TRS" (translation, rotation, scale) of a bone in animation.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#get_node_global_transform">get_node_global_transform (node, frame, outputs)</a></td>
<td class="name" nowrap><a href="#mtul.b3d_nodes.get_node_global_transform">mtul.b3d_nodes.get_node_global_transform (node, frame, outputs)</a></td>
<td class="summary">get a node's global mat4 transform and rotation.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#get_node_global_position">get_node_global_position (self, node, is_bone, frame)</a></td>
<td class="name" nowrap><a href="#mtul.b3d_nodes.get_node_global_position">mtul.b3d_nodes.get_node_global_position (self, node, is_bone, frame)</a></td>
<td class="summary">find the position of a node in global model space.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#get_node_rotation">get_node_rotation (self, node, is_bone, frame)</a></td>
<td class="name" nowrap><a href="#mtul.b3d_nodes.get_node_rotation">mtul.b3d_nodes.get_node_rotation (self, node, is_bone, frame)</a></td>
<td class="summary">find the global rotation of a node in model space.</td>
</tr>
</table>
@ -85,8 +86,8 @@
<dl class="function">
<dt>
<a name = "get_node_by_name"></a>
<strong>get_node_by_name (self, node_name, is_bone)</strong>
<a name = "mtul.b3d_nodes.get_node_by_name"></a>
<strong>mtul.b3d_nodes.get_node_by_name (self, node_name, is_bone)</strong>
</dt>
<dd>
get a node by it's name
@ -116,8 +117,8 @@
</dd>
<dt>
<a name = "get_animated_local_trs"></a>
<strong>get_animated_local_trs (node, target_frame)</strong>
<a name = "mtul.b3d_nodes.get_animated_local_trs"></a>
<strong>mtul.b3d_nodes.get_animated_local_trs (node, target_frame)</strong>
</dt>
<dd>
get the local "TRS" (translation, rotation, scale) of a bone in animation. This is used for global transformation calculations.
@ -150,8 +151,8 @@ outputs need cleaning up.</li>
</dd>
<dt>
<a name = "get_node_global_transform"></a>
<strong>get_node_global_transform (node, frame, outputs)</strong>
<a name = "mtul.b3d_nodes.get_node_global_transform"></a>
<strong>mtul.b3d_nodes.get_node_global_transform (node, frame, outputs)</strong>
</dt>
<dd>
get a node's global mat4 transform and rotation.
@ -183,8 +184,8 @@ outputs need cleaning up.</li>
</dd>
<dt>
<a name = "get_node_global_position"></a>
<strong>get_node_global_position (self, node, is_bone, frame)</strong>
<a name = "mtul.b3d_nodes.get_node_global_position"></a>
<strong>mtul.b3d_nodes.get_node_global_position (self, node, is_bone, frame)</strong>
</dt>
<dd>
find the position of a node in global model space.
@ -221,8 +222,8 @@ outputs need cleaning up.</li>
</dd>
<dt>
<a name = "get_node_rotation"></a>
<strong>get_node_rotation (self, node, is_bone, frame)</strong>
<a name = "mtul.b3d_nodes.get_node_rotation"></a>
<strong>mtul.b3d_nodes.get_node_rotation (self, node, is_bone, frame)</strong>
</dt>
<dd>
find the global rotation of a node in model space.
@ -261,7 +262,7 @@ outputs need cleaning up.</li>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/lunarmodules/ldoc">LDoc 1.5.0</a></i>
<i style="float:right;">Last updated 2024-01-06 20:41:04 </i>
<i style="float:right;">Last updated 2024-07-12 19:17:47 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

332
docs/modules/b3d_reader.html
View File

@ -35,13 +35,13 @@
<ul>
<li><a href="#Functions">Functions</a></li>
<li><a href="#Tables">Tables</a></li>
<li><a href="#Fields">Fields</a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><strong>b3d_reader</strong></li>
<li><a href="../modules/b3d_writer.html">b3d_writer</a></li>
<li><a href="../modules/b3d_nodes.html">b3d_nodes</a></li>
</ul>
@ -51,32 +51,69 @@
<h1>Module <code>b3d_reader</code></h1>
<p>parse .b3d files into a lua table.</p>
<p> located in <code>mtul.b3d_reader</code>.</p>
<p> note: capitlization of name indicates a "chunk" defined by the blitz3d format (see b3d_specification.txt)</p>
<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#read_model">read_model (modelname, node_only)</a></td>
<td class="name" nowrap><a href="#mtul.b3d_reader.read_model">mtul.b3d_reader.read_model (modelname, node_only)</a></td>
<td class="summary">read b3d models by their name.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#read_from_stream">read_from_stream (stream, ignore_chunks)</a></td>
<td class="name" nowrap><a href="#mtul.b3d_reader.read_from_stream">mtul.b3d_reader.read_from_stream (stream, ignore_chunks)</a></td>
<td class="summary">read directly from file</td>
</tr>
</table>
<h2><a href="#Tables">Tables</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#ignore_chunks">ignore_chunks</a></td>
<td class="name" nowrap><a href="#chunks">chunks</a></td>
<td class="summary">an unordered list of the following string chunks.</td>
</tr>
</table>
<h2><a href="#Fields">Fields</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#VRTS">VRTS</a></td>
<td class="summary">vertices</td>
</tr>
<tr>
<td class="name" nowrap><a href="#TRIS">TRIS</a></td>
<td class="summary">triangle/poly sets</td>
</tr>
<tr>
<td class="name" nowrap><a href="#MESH">MESH</a></td>
<td class="summary">the mesh chunk table</td>
</tr>
<tr>
<td class="name" nowrap><a href="#BONE">BONE</a></td>
<td class="summary">bone table
a list of vertex weights indexed by their vertex_id</td>
</tr>
<tr>
<td class="name" nowrap><a href="#KEYS">KEYS</a></td>
<td class="summary">keyframes</td>
</tr>
<tr>
<td class="name" nowrap><a href="#keyframe">keyframe</a></td>
<td class="summary">table which specifies a keyframe</td>
</tr>
<tr>
<td class="name" nowrap><a href="#ANIM">ANIM</a></td>
<td class="summary">defines the animation of a model</td>
</tr>
<tr>
<td class="name" nowrap><a href="#NODE">NODE</a></td>
<td class="summary">node
a node chunk possibly containing the following chunks.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#BB3D">BB3D</a></td>
<td class="summary">b3d table
note: in the b3d writer the node_paths field is ignored</td>
</tr>
<tr>
<td class="name" nowrap><a href="#node_paths">node_paths</a></td>
<td class="summary">b3d table</td>
<td class="summary">node paths
a list of nodes indexed by a hieracrchy of nodes i.e.</td>
</tr>
</table>
@ -88,8 +125,8 @@
<dl class="function">
<dt>
<a name = "read_model"></a>
<strong>read_model (modelname, node_only)</strong>
<a name = "mtul.b3d_reader.read_model"></a>
<strong>mtul.b3d_reader.read_model (modelname, node_only)</strong>
</dt>
<dd>
read b3d models by their name. This simplifies read<em>from</em>stream.
@ -116,8 +153,8 @@
</dd>
<dt>
<a name = "read_from_stream"></a>
<strong>read_from_stream (stream, ignore_chunks)</strong>
<a name = "mtul.b3d_reader.read_from_stream"></a>
<strong>mtul.b3d_reader.read_from_stream (stream, ignore_chunks)</strong>
</dt>
<dd>
read directly from file
@ -129,14 +166,14 @@
the file object (from the io library) to read from. Make sure you open it as "rb" (read binary.)
</li>
<li><span class="parameter">ignore_chunks</span>
a list of chunks to be ignored (documentation needed)
a list of <a href="../modules/b3d_reader.html#chunks">chunks</a> to be ignored (documentation needed)
</li>
</ul>
<h3>Returns:</h3>
<ol>
b3d table (documentation needed!)
<a href="../modules/b3d_reader.html#BB3D">BB3D</a> (documentation needed!)
</ol>
@ -148,8 +185,8 @@
<dl class="function">
<dt>
<a name = "ignore_chunks"></a>
<strong>ignore_chunks</strong>
<a name = "chunks"></a>
<strong>chunks</strong>
</dt>
<dd>
an unordered list of the following string chunks.
@ -189,23 +226,266 @@
</dd>
</dl>
<h2 class="section-header "><a name="Fields"></a>Fields</h2>
<dt>
<a name = "VRTS"></a>
<strong>VRTS</strong>
</dt>
<dd>
vertices
<dl class="function">
<h3>Fields:</h3>
<ul>
<li><span class="parameter">flags</span>
uknown
</li>
<li><span class="parameter">tex_coord_sets</span>
the number of texture coordinate sets
</li>
<li><span class="parameter">tex_coord_set_size</span>
unknown
</li>
<li><span class="parameter">...</span>
a list of vertices, the integer index defines their vertex<em>ids { pos={x,y,z}, color={r, g, b, a}, tex</em>coords=... }
</li>
</ul>
</dd>
<dt>
<a name = "TRIS"></a>
<strong>TRIS</strong>
</dt>
<dd>
triangle/poly sets
<h3>Fields:</h3>
<ul>
<li><span class="parameter">brush_id</span>
</li>
<li><span class="parameter">vertex_ids</span>
a list of three vertex IDs {i, j, k} which make it up
</li>
</ul>
</dd>
<dt>
<a name = "MESH"></a>
<strong>MESH</strong>
</dt>
<dd>
the mesh chunk table
<h3>Fields:</h3>
<ul>
<li><span class="parameter">brush_id</span>
(may not exist) brush from brush chunk to use
</li>
<li><span class="parameter">vertices</span>
<a href="../modules/b3d_reader.html#VRTS">VRTS</a> vertices and indexed by their ID and additional info
</li>
<li><span class="parameter">triangle_sets</span>
<a href="../modules/b3d_reader.html#TRIS">TRIS</a> a list of three vertices to be used in
</li>
</ul>
</dd>
<dt>
<a name = "BONE"></a>
<strong>BONE</strong>
</dt>
<dd>
bone table
a list of vertex weights indexed by their vertex_id
</dd>
<dt>
<a name = "KEYS"></a>
<strong>KEYS</strong>
</dt>
<dd>
keyframes
<h3>Fields:</h3>
<ul>
<li><span class="parameter">flags</span>
defines if position rotation and scale exists (further explanation needed)
</li>
<li><span class="parameter">...</span>
a list of <a href="../modules/b3d_reader.html#keyframe">keyframe</a>s
</li>
</ul>
</dd>
<dt>
<a name = "keyframe"></a>
<strong>keyframe</strong>
</dt>
<dd>
table which specifies a keyframe
</dd>
<dt>
<a name = "ANIM"></a>
<strong>ANIM</strong>
</dt>
<dd>
defines the animation of a model
<h3>Fields:</h3>
<ul>
<li><span class="parameter">flags</span>
unused?
</li>
<li><span class="parameter">frames</span>
number of frames
</li>
<li><span class="parameter">fps</span>
framerate of the model
</li>
</ul>
</dd>
<dt>
<a name = "NODE"></a>
<strong>NODE</strong>
</dt>
<dd>
node
a node chunk possibly containing the following chunks.
there are three possible "types" of nodes. All bones will contain the following chunks:
position, rotation, scale. Bones will have a
bone field which will contain IDs from it's parent node's mesh chunk.
<h3>Fields:</h3>
<ul>
<li><span class="parameter">name</span>
</li>
<li><span class="parameter">type</span>
string which is either "pivot", "bone" or "mesh"
</li>
<li><span class="parameter">children</span>
a list of child nodes, Transoformations (position, rotation, scale) will be applied to the children.
</li>
<li><span class="parameter">position</span>
position {x, y, z} of the bone
</li>
<li><span class="parameter">rotation</span>
quaternion {x, y, z, w} rotation of the bone at rest
</li>
<li><span class="parameter">scale</span>
{x, y, z} scale of the bone at rest
</li>
<li><span class="parameter">mesh</span>
<a href="../modules/b3d_reader.html#MESH">MESH</a> chunk. Found in <strong>mesh</strong> node
</li>
<li><span class="parameter">bone</span>
<a href="../modules/b3d_reader.html#BONE">BONE</a> chunk. Found in <strong>bone</strong> node
</li>
<li><span class="parameter">keys</span>
<a href="../modules/b3d_reader.html#KEYS">KEYS</a> chunk. Found in <strong>bone</strong> node
</li>
<li><span class="parameter">animation</span>
<a href="../modules/b3d_reader.html#ANIM">ANIM</a> chunk. Typically found in root node (uknown wether it can be elsewhere.)
</li>
<li><span class="parameter">parent</span>
the parent node. (The node in which this node is in the children table)
</li>
</ul>
</dd>
<dt>
<a name = "BB3D"></a>
<strong>BB3D</strong>
</dt>
<dd>
b3d table
note: in the b3d writer the node_paths field is ignored
<h3>Fields:</h3>
<ul>
<li><span class="parameter">node_paths</span>
all of the nodes in the model <a href="../modules/b3d_nodes.html#">b3d_nodes</a>
</li>
<li><span class="parameter">node</span>
a table containing the root <a href="../modules/b3d_reader.html#NODE">NODE</a> of the model.
</li>
<li><span class="parameter">textures</span>
??? texture information
</li>
<li><span class="parameter">brushes</span>
??? material information
</li>
<li><span class="parameter">version</span>
<code>{major=float, minor=float}</code> this functionally means nothing, but it's version information.
</li>
</ul>
</dd>
<dt>
<a name = "node_paths"></a>
<strong>node_paths</strong>
</dt>
<dd>
b3d table
node paths
a list of nodes indexed by a hieracrchy of nodes i.e. "path.to.node"
<h3>Fields:</h3>
<ul>
<li><span class="parameter">node_paths</span>
<li><span class="parameter">...</span>
) node
</li>
</ul>
@ -221,7 +501,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/lunarmodules/ldoc">LDoc 1.5.0</a></i>
<i style="float:right;">Last updated 2024-01-06 20:41:04 </i>
<i style="float:right;">Last updated 2024-07-12 19:17:47 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

136
docs/modules/b3d_writer.html Normal file
View File

@ -0,0 +1,136 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
<title>MTUL b3d reader/writer documentation</title>
<link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"></div>
<div id="product_name"><big><b></b></big></div>
<div id="product_description"></div>
</div> <!-- id="product" -->
<div id="main">
<!-- Menu -->
<div id="navigation">
<br/>
<h1>MTUL b3d</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><a href="../modules/b3d_reader.html">b3d_reader</a></li>
<li><strong>b3d_writer</strong></li>
<li><a href="../modules/b3d_nodes.html">b3d_nodes</a></li>
</ul>
</div>
<div id="content">
<h1>Module <code>b3d_writer</code></h1>
<p>writes b3d models in the same format as outputted by the b3d reader module</p>
<p>
</p>
<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#mtul.b3d_writer.write_string">mtul.b3d_writer.write_string (self)</a></td>
<td class="summary">output a string of binary in the blitz 3d format</td>
</tr>
<tr>
<td class="name" nowrap><a href="#mtul.b3d_writer.write_model_to_file">mtul.b3d_writer.write_model_to_file (self, stream)</a></td>
<td class="summary">output in the blitz3d format file reference</td>
</tr>
</table>
<br/>
<br/>
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
<dl class="function">
<dt>
<a name = "mtul.b3d_writer.write_string"></a>
<strong>mtul.b3d_writer.write_string (self)</strong>
</dt>
<dd>
output a string of binary in the blitz 3d format
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">self</span>
???
</li>
</ul>
<h3>Returns:</h3>
<ol>
string containing the binary file
</ol>
</dd>
<dt>
<a name = "mtul.b3d_writer.write_model_to_file"></a>
<strong>mtul.b3d_writer.write_model_to_file (self, stream)</strong>
</dt>
<dd>
output in the blitz3d format file reference
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">self</span>
???
</li>
<li><span class="parameter">stream</span>
io file object to write to
</li>
</ul>
</dd>
</dl>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/lunarmodules/ldoc">LDoc 1.5.0</a></i>
<i style="float:right;">Last updated 2024-07-12 19:17:47 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

198
docs/modules/modlib.read_b3d.html
View File

@ -1,198 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
<title>MTUL b3d reader/writer documentation</title>
<link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"></div>
<div id="product_name"><big><b></b></big></div>
<div id="product_description"></div>
</div> <!-- id="product" -->
<div id="main">
<!-- Menu -->
<div id="navigation">
<br/>
<h1>MTUL b3d</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
<li><a href="#Tables">Tables</a></li>
<li><a href="#Fields">Fields</a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><strong>modlib.read_b3d</strong></li>
<li><a href="../modules/b3d_nodes.html">b3d_nodes</a></li>
</ul>
</div>
<div id="content">
<h1>Module <code>modlib.read_b3d</code></h1>
<p>[[parse .b3d files into a lua table</p>
<p>
</p>
<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#read_from_stream">read_from_stream (stream, ignore_chunks)</a></td>
<td class="summary">read directly from file</td>
</tr>
</table>
<h2><a href="#Tables">Tables</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#ignore_chunks">ignore_chunks</a></td>
<td class="summary">an unordered list of the following string chunks.</td>
</tr>
</table>
<h2><a href="#Fields">Fields</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#node_paths">node_paths</a></td>
<td class="summary">b3d table</td>
</tr>
</table>
<br/>
<br/>
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
<dl class="function">
<dt>
<a name = "read_from_stream"></a>
<strong>read_from_stream (stream, ignore_chunks)</strong>
</dt>
<dd>
read directly from file
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">stream</span>
the file object (from the io library) to read from. Make sure you open it as "rb" (read binary.)
</li>
<li><span class="parameter">ignore_chunks</span>
a list of chunks to be ignored (documentation needed)
</li>
</ul>
<h3>Returns:</h3>
<ol>
b3d table (documentation needed!)
</ol>
</dd>
</dl>
<h2 class="section-header "><a name="Tables"></a>Tables</h2>
<dl class="function">
<dt>
<a name = "ignore_chunks"></a>
<strong>ignore_chunks</strong>
</dt>
<dd>
an unordered list of the following string chunks.
"NODE" and "BB3D" are ommitted as they are not allowed.
<h3>Fields:</h3>
<ul>
<li><span class="parameter">1</span>
"TEXS" texture information
</li>
<li><span class="parameter">2</span>
"BRUS" brushes (materials)
</li>
<li><span class="parameter">3</span>
"MESH" (sub-chunks of "MESH" include "VERTS" &amp; "TRIS")
</li>
<li><span class="parameter">4</span>
"TRIS" sets of triangles
</li>
<li><span class="parameter">5</span>
"VRTS" vertices
</li>
<li><span class="parameter">6</span>
"BONE" node vertex weights
</li>
<li><span class="parameter">7</span>
"ANIM" animation information
</li>
<li><span class="parameter">8</span>
"KEYS" keyframes
</li>
</ul>
</dd>
</dl>
<h2 class="section-header "><a name="Fields"></a>Fields</h2>
<dl class="function">
<dt>
<a name = "node_paths"></a>
<strong>node_paths</strong>
</dt>
<dd>
b3d table
<ul>
<li><span class="parameter">node_paths</span>
</li>
</ul>
</dd>
</dl>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/lunarmodules/ldoc">LDoc 1.5.0</a></i>
<i style="float:right;">Last updated 2024-01-06 20:39:53 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

3
init.lua
View File

@ -10,12 +10,13 @@
]]
mtul.b3d_reader = {}
mtul.b3d_writer = {}
mtul.loaded_modules.b3d = true
local modpath = minetest.get_modpath("mtul_b3d")
--placed in a seperate directory for the license
dofile(modpath.."/modlib/read_b3d.lua")
--dofile(modpath.."/modlib/write_b3d.lua") --this is untested, could be very broken.
dofile(modpath.."/modlib/write_b3d.lua")
--dofile(modpath.."/modlib/to_gltf.lua")
--prevent accidental access of unavailable features:

100
modlib/read_b3d.lua
View File

@ -1,17 +1,5 @@
--this reader has been heavily modified to implement additional needed features.
--implementations include:
--mtul.b3d.read_model()
--ignore_chunks parameter,
--node.parent,
--node.path
--b3d.node_paths
-- Localize globals
--- parse .b3d files into a lua table.
--- located in `mtul.b3d_reader`.
-- note: capitlization of name indicates a "chunk" defined by the blitz3d format (see b3d_specification.txt)
--@module b3d_reader
local read_int, read_single = mtul.binary.read_int, mtul.binary.read_single
@ -32,7 +20,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 read_model
-- @function mtul.b3d_reader.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,12 +56,6 @@ end
--made originally by appgurueu
-- See `b3d_specification.txt` as well as https://github.com/blitz-research/blitz3d/blob/master/blitz3d/loader_b3d.cpp
--- read directly from file
-- @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 b3d table (documentation needed!)
--- an unordered list of the following string chunks.
--- "NODE" and "BB3D" are ommitted as they are not allowed.
-- @field 1 "TEXS" texture information
@ -84,8 +66,13 @@ end
-- @field 6 "BONE" node vertex weights
-- @field 7 "ANIM" animation information
-- @field 8 "KEYS" keyframes
-- @table ignore_chunks
-- @table chunks
--- read directly from file
-- @function mtul.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 mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
local left = 8
@ -210,6 +197,12 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
return brushes
end,
VRTS = function()
--- vertices
--@field flags uknown
--@field tex_coord_sets the number of texture coordinate sets
--@field tex_coord_set_size unknown
--@field ... a list of vertices, the integer index defines their vertex_ids { pos={x,y,z}, color={r, g, b, a}, tex_coords=... }
--@table VRTS
local vertices = {}
vertices.flags = int()
vertices.tex_coord_sets = int()
@ -235,6 +228,10 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
return vertices
end,
TRIS = function()
--- triangle/poly sets
--@field brush_id
--@field vertex_ids a list of three vertex IDs {i, j, k} which make it up
--@table TRIS
local tris = {}
tris.brush_id = id()
tris.vertex_ids = {}
@ -247,6 +244,11 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
return tris
end,
MESH = function()
--- the mesh chunk table
-- @field brush_id (may not exist) brush from brush chunk to use
-- @field vertices @{VRTS} vertices and indexed by their ID and additional info
-- @field triangle_sets @{TRIS} a list of three vertices to be used in
-- @table MESH
local mesh = {}
mesh.brush_id = optional_id()
mesh.vertices = chunk{VRTS = true}
@ -258,6 +260,9 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
return mesh
end,
BONE = function()
--- bone table
-- a list of vertex weights indexed by their vertex_id
-- @table BONE
local bone = {}
while content() do
local vertex_id = id()
@ -270,6 +275,10 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
end
return bone
end,
--- keyframes
--@field flags defines if position rotation and scale exists (further explanation needed)
--@field ... a list of @{keyframe}s
--@table KEYS a list of keyframes
KEYS = function()
local flags = int()
local _flags = flags % 8
@ -287,6 +296,11 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
flags = flags
}
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
@ -303,6 +317,11 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
end
return bone
end,
--- defines the animation of a model
--@field flags unused?
--@field frames number of frames
--@field fps framerate of the model
--@table ANIM
ANIM = function()
local ret = {}
ret.flags = int() -- flags are unused
@ -311,6 +330,23 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
return ret
end,
NODE = function()
--- node
-- a node chunk possibly containing the following chunks.
-- there are three possible "types" of nodes. All bones will contain the following chunks:
-- position, rotation, scale. Bones will have a
-- bone field which will contain IDs from it's parent node's mesh chunk.
-- @field name
-- @field type string which is either "pivot", "bone" or "mesh"
-- @field children a list of child nodes, Transoformations (position, rotation, scale) will be applied to the children.
-- @field position position {x, y, z} of the bone
-- @field rotation quaternion {x, y, z, w} rotation of the bone at rest
-- @field scale {x, y, z} scale of the bone at rest
-- @field mesh @{MESH} chunk. Found in **mesh** node
-- @field bone @{BONE} chunk. Found in **bone** node
-- @field keys @{KEYS} chunk. Found in **bone** node
-- @field animation @{ANIM} chunk. Typically found in root node (uknown wether it can be elsewhere.)
-- @field parent the parent node. (The node in which this node is in the children table)
-- @table NODE
local node = {}
node.name = string()
node.position = vector3()
@ -321,9 +357,9 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
node.rotation = quaternion()
node.children = {}
local node_type
-- See https://github.com/blitz-research/blitz3d/blob/master/blitz3d/loader_b3d.cpp#L263
-- Order is not validated; double occurrences of mutually exclusive node def are
--"are" what appgurueu
--See https://github.com/blitz-research/blitz3d/blob/master/blitz3d/loader_b3d.cpp#L263
--Order is not validated; double occurrences of mutually exclusive node def are
--... they are what appgurueu????
while content() do
local elem, type = chunk()
if type == "MESH" then
@ -350,7 +386,7 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
node.animation = elem
end
else
assert(not node_type, "Appgurueu decided to not put actual comments, so I'm not sure, but your .b3d file is fscked up lol. I dont even think this assert is needed.")
assert(not node_type, "Appgurueu decided to not put actual comments telling me what this means, so I'm not sure, but your .b3d file is fscked up lol. I dont even think this assert is needed.")
node_type = "pivot"
end
end
@ -363,6 +399,14 @@ function mtul.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()
local version = int()
local self = {
@ -441,5 +485,7 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
return setmetatable(self, mtul._b3d_metatable or {})
end
--- b3d table
-- @field node_paths
--- node paths
-- a list of nodes indexed by a hieracrchy of nodes i.e. "path.to.node"
-- @field (...) node
-- @table node_paths

21
modlib/write_b3d.lua
View File

@ -1,5 +1,8 @@
--- writes b3d models in the same format as outputted by the b3d reader module
--@module b3d_writer
-- Writer
--Writer
local write_int, write_single = mtul.binary.write_int, mtul.binary.write_single
local string_char = string.char
@ -84,9 +87,13 @@ local function write_rope(self)
local function NODE(node)
chunk("NODE", function()
assert(node.scale, "a node is missing a name")
string(node.name)
assert(node.scale, "a node is missing position")
vector3(node.position)
assert(node.scale, "a node is missing scale")
vector3(node.scale)
assert(node.scale, "a node is missing rotation")
quaternion(node.rotation)
local mesh = node.mesh
if mesh then
@ -210,11 +217,19 @@ local function write_rope(self)
return rope
end
function mtul.b3d.write_string(self)
--- output a string of binary in the blitz 3d format
-- @function mtul.b3d_writer.write_string
-- @param self @{BB3D}
-- @return string containing the binary file
function mtul.b3d_writer.write_string(self)
return table.concat(write_rope(self))
end
function mtul.b3d.write(self, stream)
--- output in the blitz3d format file reference
-- @function mtul.b3d_writer.write_model_to_file
-- @param self @{BB3D}
-- @param stream io file object to write to
function mtul.b3d_writer.write_model_to_file(self, stream)
for _, str in ipairs(write_rope(self)) do
stream:write(str)
end

27
nodes.lua
View File

@ -12,7 +12,7 @@ local mat4 = mtul.math.mat4
local quat = mtul.math.quat
--- get a node by it's name
-- @function get_node_by_name
-- @function mtul.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.
@ -35,15 +35,6 @@ end
--keep in mind that this returns *raw* info, other then vectorizing quaternions (as slerp has to be performed to interpolate).
--further, quaternions need to have their w inverted.
--- 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 cpml object to be interpolated, also has to be usable anyway.
-- @function 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}
-- @return `rotation` quat from `mtul_cpml`: (example) {w=0,x=0,y=0,z=1}
-- @return `scale` ordered table: {x, y, z}
--outputs need cleaning up.
local interpolate = function(a, b, ratio)
local out = {}
for i, v in pairs(a) do
@ -51,6 +42,16 @@ local interpolate = function(a, b, ratio)
end
return out
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 cpml object to be interpolated, also has to be usable anyway.
-- @function mtul.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}
-- @return `rotation` quat from `mtul_cpml`: (example) {w=0,x=0,y=0,z=1}
-- @return `scale` ordered table: {x, y, z}
--outputs need cleaning up.
function b3d_nodes.get_animated_local_trs(node, target_frame)
assert(target_frame, "no frame specified for TRS calculations")
local frames = node.keys
@ -89,7 +90,7 @@ 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 get_node_global_transform
-- @function mtul.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 "rotation" or "transform". Set to nil to return both.
@ -136,7 +137,7 @@ 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 get_node_global_position
--@function mtul.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`)
@ -155,7 +156,7 @@ 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 get_node_rotation
--@function mtul.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`)