From 8453de9caf50dffb83fd5f6470532f0e331bd615 Mon Sep 17 00:00:00 2001
From: FatalErr42O <58855799+FatalError42O@users.noreply.github.com>
Date: Sat, 3 Aug 2024 16:25:17 -0700
Subject: [PATCH] update documentation

---
 docs/index.html                |   2 +-
 docs/modules/b3d_nodes.html    |   2 +-
 docs/modules/b3d_reader.html   | 128 +++++++++++++++++++++++++++------
 docs/modules/b3d_writer.html   |   6 +-
 ldoc/index.html - Shortcut.lnk | Bin 0 -> 2118 bytes
 modlib/read_b3d.lua            |  43 +++++++----
 modlib/write_b3d.lua           |   7 +-
 7 files changed, 145 insertions(+), 43 deletions(-)
 create mode 100644 ldoc/index.html - Shortcut.lnk

diff --git a/docs/index.html b/docs/index.html
index db30b8c..b54fedb 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -65,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-07-14 13:05:02 </i>
+<i style="float:right;">Last updated 2024-08-03 16:24:48 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/b3d_nodes.html b/docs/modules/b3d_nodes.html
index 6ed3182..d48160b 100644
--- a/docs/modules/b3d_nodes.html
+++ b/docs/modules/b3d_nodes.html
@@ -262,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-07-14 13:05:02 </i>
+<i style="float:right;">Last updated 2024-08-03 16:24:48 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/b3d_reader.html b/docs/modules/b3d_reader.html
index d78eece..afbcec7 100644
--- a/docs/modules/b3d_reader.html
+++ b/docs/modules/b3d_reader.html
@@ -68,10 +68,18 @@
 <h2><a href="#Tables">Tables</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#chunks">chunks</a></td>
+	<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>
 	<tr>
+	<td class="name" nowrap><a href="#TEXS">TEXS</a></td>
+	<td class="summary">textures</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#BRUS">BRUS</a></td>
+	<td class="summary">brushes (materials)</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#VRTS">VRTS</a></td>
 	<td class="summary">vertices</td>
 	</tr>
@@ -102,18 +110,16 @@
 	</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>
+	<td class="summary">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>
+	<td class="summary">note: in <code>b3d_writer</code> the node_paths field is ignored</td>
 	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#node_paths">node_paths</a></td>
 	<td class="summary">node paths
- a list of nodes indexed by a hieracrchy of nodes i.e.</td>
+ a list of nodes indexed by a list which containing every related parent node aswell as itself.</td>
 	</tr>
 </table>
 
@@ -166,14 +172,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 <a href="../modules/b3d_reader.html#chunks">chunks</a> to be ignored (documentation needed)
+         a list of <a href="../modules/b3d_reader.html#ignore_chunks">ignore_chunks</a> to be ignored
         </li>
     </ul>
 
     <h3>Returns:</h3>
     <ol>
 
-        <a href="../modules/b3d_reader.html#BB3D">BB3D</a> (documentation needed!)
+        <a href="../modules/b3d_reader.html#BB3D">BB3D</a>
     </ol>
 
 
@@ -185,8 +191,8 @@
 
     <dl class="function">
     <dt>
-    <a name = "chunks"></a>
-    <strong>chunks</strong>
+    <a name = "ignore_chunks"></a>
+    <strong>ignore_chunks</strong>
     </dt>
     <dd>
     an unordered list of the following string chunks.
@@ -225,6 +231,86 @@
 
 
 
+</dd>
+    <dt>
+    <a name = "TEXS"></a>
+    <strong>TEXS</strong>
+    </dt>
+    <dd>
+    textures
+
+
+    <h3>Fields:</h3>
+    <ul>
+        <li><span class="parameter">file</span>
+
+
+
+        </li>
+        <li><span class="parameter">flags</span>
+
+
+
+        </li>
+        <li><span class="parameter">pos</span>
+         table {float, float}
+        </li>
+        <li><span class="parameter">pos</span>
+         table {float, float}
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "BRUS"></a>
+    <strong>BRUS</strong>
+    </dt>
+    <dd>
+    brushes (materials)
+
+
+    <h3>Fields:</h3>
+    <ul>
+        <li><span class="parameter">name</span>
+
+
+
+        </li>
+        <li><span class="parameter">color</span>
+
+
+
+        </li>
+        <li><span class="parameter">shininess</span>
+
+
+
+        </li>
+        <li><span class="parameter">blend</span>
+
+
+
+        </li>
+        <li><span class="parameter">fx</span>
+
+
+
+        </li>
+        <li><span class="parameter">texture_id</span>
+
+
+
+        </li>
+    </ul>
+
+
+
+
+
 </dd>
     <dt>
     <a name = "VRTS"></a>
@@ -389,11 +475,12 @@
     <strong>NODE</strong>
     </dt>
     <dd>
-    node
- a node chunk possibly containing the following chunks.
+    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.
+ <code>position</code>, <code>rotation</code>, <code>scale</code>.
+ Bones will have a bone field which will contain IDs from it's parent node's mesh chunk.
+ Meshes will have a mesh field containing information about their mesh.
+ Pivots will have neither of those and simply serve as parents to child nodes. &lt;3
 
 
     <h3>Fields:</h3>
@@ -445,23 +532,22 @@
     <strong>BB3D</strong>
     </dt>
     <dd>
-    b3d table
- note: in the b3d writer the node_paths field is ignored
+    note: in <code>b3d_writer</code> 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>
+         all nodes in the model indexed by a table <a href="../modules/b3d_reader.html#node_paths">node_paths</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
+         a list of <a href="../modules/b3d_reader.html#TEXS">TEXS</a> chunks
         </li>
         <li><span class="parameter">brushes</span>
-         ??? material information
+         a list of <a href="../modules/b3d_reader.html#BRUS">BRUS</a> chunks
         </li>
         <li><span class="parameter">version</span>
          <code>{major=float, minor=float}</code> this functionally means nothing, but it's version information.
@@ -479,7 +565,7 @@
     </dt>
     <dd>
     node paths
- a list of nodes indexed by a hieracrchy of nodes i.e.  "path.to.node"
+ a list of nodes indexed by a list which containing every related parent node aswell as itself.
 
 
     <h3>Fields:</h3>
@@ -501,7 +587,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-07-14 13:05:02 </i>
+<i style="float:right;">Last updated 2024-08-03 16:24:48 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/b3d_writer.html b/docs/modules/b3d_writer.html
index 25cede6..e204f89 100644
--- a/docs/modules/b3d_writer.html
+++ b/docs/modules/b3d_writer.html
@@ -85,7 +85,7 @@
     <h3>Parameters:</h3>
     <ul>
         <li><span class="parameter">self</span>
-         ???
+         <a href="../modules/b3d_reader.html#BB3D">BB3D chunk</a>
         </li>
     </ul>
 
@@ -110,7 +110,7 @@
     <h3>Parameters:</h3>
     <ul>
         <li><span class="parameter">self</span>
-         ???
+         <a href="../modules/b3d_reader.html#BB3D">BB3D chunk</a>
         </li>
         <li><span class="parameter">stream</span>
          io file object to write to
@@ -129,7 +129,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-07-14 13:05:02 </i>
+<i style="float:right;">Last updated 2024-08-03 16:24:48 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/ldoc/index.html - Shortcut.lnk b/ldoc/index.html - Shortcut.lnk
new file mode 100644
index 0000000000000000000000000000000000000000..e39300bbba6a2c6071a3e748627c957eb52dde32
GIT binary patch
literal 2118
zcmds1U1$_n6h51^HnG93uv#0Fy3iKZ>JGbZOw&M0Y9?`&{SkIUcH>YsyE8P~xHIX_
z#H4+Qt!+WXzN9LYU~Ag6zQn((Xb?**E!5DK_=B`cK`7EcB={tV5B<)}>}*Iw+h+&P
zxo7S@_k8Dm=iD15BA2%cnrPb8)Hz1g<b(a&#mkqbuHSTJkFJ?`aOb9LkAGj3$MMH4
zN0&7?dZx-tYq#G{%=-RpDR@5pshZXYgNMB&ygj;p)iveAw>l5@j}ElVRG-LF$lT@5
z<b@!`w#GYB9V3{EPz^1ixv#>>-UfH(>ZAZKHNn~0kPcSeSUtt4Kq@I@Ky+w7^g4K~
zrd>|_j*zDuKP&_T-9$Y$#%Q<uqC0cT#Mpa@1J63qEo0-MaVjpr2+$@Hs2LKZ01cU|
zP1J}D^%S>Jt1|DL_E1rib)psrZK;Fy<L_?xTMSenzklu&&@_^93L-DPYJ1#DkJjT1
zsjg@s$sBds5gWQ!E^}v&pJtB6C#s>JssuBw3yqE7C`DZqMXovxB3tH)85*#o-%a0j
z+0i$1^t2PbYs{T#KhM#>{f6@u&6pLnq4xT`=s5}_b4D?!7gdp=cj7c$AI2+lW8ukK
zejYbGSH{}W#9g(f0%KZF-?@f}8s%+nvb2%73*DK>l#jN?#g6nyNQk6j4m(!N$Q0-Q
z#)}+t+k%)Q$xqDc$;faR_3T6DMdVCW2RR9;hwx4wn<4z2fbc&va^^e#v<G8%L6x;3
zJ&;U_)ZQX>=}JkL;#y9VrG%=8rNS;n61DtbQBe(DiWOAFP;|quuak<l9oQr^qdSKR
zYEz@cjU$=$)&~oQVwt(H9MFwkRqoxXsfxq|N`O^{g+8N*q-${kY0>laQ#-m)LKo;b
zX$e|FH8jeZy(Uq@tdWS70`851RncU65Ns$|Gt3=}-!<uf-w*b*dRv;;HI<&6Kl^XJ
zBsqPMwW@F=jgh~6Ur8$}IZf-g{vRBA`Pp}mcW!<!bl^&MUp&_TLr%%RGPmNR``(_1
z;rG-3weClWYlx2U(-2B-PX_Nje{OC|o#*p=RoVR?|24@k%`%2s3wZ*<kI_GyiD)I(
zo`g^vtIrO9&2K7C*783a<p;GD_7a}tki5{2t}KB!u7nS-V+!0wVJ)l>?_vMtY_vhj
zPc{EHpojSYU%a08w;sH@;_MBYPW-%j)`j_J*n!c8AdhCBEPgBa-2A-+VRBBbDvHNG
z7>FE=v<VZf!}}XB-^UIS$ew{WeY?L5Z8=+WV5WKb3$O9~V>YYN^zC2wp6l6m!MD3d
Yygd2KA6Q$;4$LaQCXXhoe8S52H|wRc9RL6T

literal 0
HcmV?d00001

diff --git a/modlib/read_b3d.lua b/modlib/read_b3d.lua
index 75c41b1..7939aaf 100644
--- a/modlib/read_b3d.lua
+++ b/modlib/read_b3d.lua
@@ -66,13 +66,13 @@ end
 -- @field 6 "BONE" node vertex weights
 -- @field 7 "ANIM" animation information
 -- @field 8 "KEYS" keyframes
--- @table chunks
+-- @table ignore_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!)
+-- @param ignore_chunks a list of @{ignore_chunks} to be ignored
+-- @return @{BB3D}
 function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
 	local left = 8
 
@@ -164,6 +164,12 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
 	local chunk
 	local chunks = {
 		TEXS = function()
+			--- textures
+			--@field file
+			--@field flags
+			--@field pos table {float, float}
+			--@field pos table {float, float}
+			--@table TEXS
 			local textures = {}
 			while content() do
 				local tex = {}
@@ -178,6 +184,14 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
 			return textures
 		end,
 		BRUS = function()
+			--- brushes (materials)
+			-- @field name
+			-- @field color
+			-- @field shininess
+			-- @field blend
+			-- @field fx
+			-- @field texture_id
+			-- @table BRUS
 			local brushes = {}
 			local n_texs = int()
 			assert(n_texs <= 8)
@@ -330,11 +344,13 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
 			return ret
 		end,
 		NODE = function()
-			--- node
-			-- a node chunk possibly containing the following chunks.
+			--- 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.
+			-- `position`, `rotation`, `scale`.
+			-- Bones will have a bone field which will contain IDs from it's parent node's mesh chunk.
+			-- Meshes will have a mesh field containing information about their mesh.
+			-- Pivots will have neither of those and simply serve as parents to child nodes. <3
+			--
 			-- @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.
@@ -399,12 +415,11 @@ 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}
+		--- note: in `b3d_writer` the node_paths field is ignored
+		-- @field node_paths all nodes in the model indexed by a table @{node_paths}
 		-- @field node a table containing the root @{NODE} of the model.
-		-- @field textures @{TEXS} texture information
-		-- @field brushes @{BRUS} material information
+		-- @field textures a list of @{TEXS} chunks
+		-- @field brushes a list of @{BRUS} chunks
 		-- @field version `{major=float, minor=float}` this functionally means nothing, but it's version information.
 		-- @table BB3D
 		BB3D = function()
@@ -458,7 +473,7 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
 	--also, Fatal here: for the sake of my reputation (which is nonexistent), typically I wouldn't nest these functions
 	--because I am not a physcopath and or a german named Lars, but for the sake of consistency it has to happen.
 	--(Not that its *always* a bad idea, but unless you're baking in parameters it's sort of useless and potentially wasteful)
-	local copy_path = mtul.table and mtul.table.shallow_copy or function(tbl)
+	local copy_path = function(tbl)
 		local new_table = {}
 		for i, v in pairs(tbl) do
 			new_table[i] = v
@@ -486,6 +501,6 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
 end
 
 --- node paths
--- a list of nodes indexed by a hieracrchy of nodes i.e. "path.to.node"
+-- a list of nodes indexed by a list which containing every related parent node aswell as itself.
 -- @field (...) node
 -- @table node_paths
\ No newline at end of file
diff --git a/modlib/write_b3d.lua b/modlib/write_b3d.lua
index dec9158..8365ce8 100644
--- a/modlib/write_b3d.lua
+++ b/modlib/write_b3d.lua
@@ -151,7 +151,8 @@ local function write_rope(self)
 					chunk("KEYS", function()
 						int(flags)
 						for _, frame in ipairs(keys) do
-							int(frame.frame)
+							--reader offsets by 1, so writer should to.
+							int(frame.frame+1)
 							if frame.position then vector3(frame.position) end
 							if frame.scale then vector3(frame.scale) end
 							if frame.rotation then quaternion(frame.rotation) end
@@ -219,7 +220,7 @@ end
 
 --- output a string of binary in the blitz 3d format
 -- @function mtul.b3d_writer.write_string
--- @param self @{BB3D}
+-- @param self @{b3d_reader.BB3D|BB3D chunk}
 -- @return string containing the binary file
 function mtul.b3d_writer.write_string(self)
 	return table.concat(write_rope(self))
@@ -227,7 +228,7 @@ end
 
 --- output in the blitz3d format file reference
 -- @function mtul.b3d_writer.write_model_to_file
--- @param self @{BB3D}
+-- @param self @{b3d_reader.BB3D|BB3D chunk}
 -- @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