documented media paths

This commit is contained in:
FatalErr42O 2024-01-08 19:31:05 -08:00
parent 8cbe7fc4b6
commit 0251176f4f
5 changed files with 534 additions and 243 deletions

View File

@ -28,252 +28,40 @@
<h2>Contents</h2>
<ul>
<li><a href="#reading_binary_inputs">reading binary inputs </a></li>
<li><a href="#misc_binary_helpers">misc binary helpers </a></li>
<li><a href="#expected_function_inputs">expected function inputs </a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><strong>binary</strong></li>
<li><a href="modules/binary.html">binary</a></li>
<li><a href="modules/paths.html">paths</a></li>
</ul>
</div>
<div id="content">
<h1>Module <code>binary</code></h1>
<p>read and write (little endian) binary.</p>
<p> located in <code>mtul.binary</code>.</p>
<h2>implements core dependencies and tools, especially for the MTUL libraries.</h2>
<h2><a href="#reading_binary_inputs">reading binary inputs </a></h2>
<table class="function_list">
<h2>Modules</h2>
<table class="module_list">
<tr>
<td class="name" nowrap><a href="#read_single">read_single (function)</a></td>
<td class="summary">read an IEEE 754 single precision (32-bit) floating point number</td>
<td class="name" nowrap><a href="modules/binary.html">binary</a></td>
<td class="summary">read and write (little endian) binary.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#read_double">read_double (function)</a></td>
<td class="summary">read an IEEE 754 double-precision (64-bit) floating point number</td>
</tr>
<tr>
<td class="name" nowrap><a href="#read_uint">read_uint (function, int)</a></td>
<td class="summary">read an unsigned integer of any given length</td>
</tr>
<tr>
<td class="name" nowrap><a href="#read_uint">read_uint (function, int)</a></td>
<td class="summary">read a signed integer of any given length</td>
<td class="name" nowrap><a href="modules/paths.html">paths</a></td>
<td class="summary">mod utilities
find the paths
find mod information</td>
</tr>
</table>
<h2><a href="#misc_binary_helpers">misc binary helpers </a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#fround">fround (number)</a></td>
<td class="summary">"returns nearest 32-bit single precision float representation of a number" (or something)</td>
</tr>
</table>
<h2><a href="#expected_function_inputs">expected function inputs </a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#read_byte">read_byte ()</a></td>
<td class="summary"><code>read_byte</code> is a param name which refers to a function which reads the next byte- returning a whole number between 0-255.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#write_byte">write_byte ()</a></td>
<td class="summary"><code>write_byte</code> is similar to read_byte, however it is given an input and expected to write it to the file.</td>
</tr>
</table>
<br/>
<br/>
<h2 class="section-header has-description"><a name="reading_binary_inputs"></a>reading binary inputs </h2>
<div class="section-description">
read a binary inputs using a <code>read_byte</code> function.
</div>
<dl class="function">
<dt>
<a name = "read_single"></a>
<strong>read_single (function)</strong>
</dt>
<dd>
read an IEEE 754 single precision (32-bit) floating point number
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">function</span>
<a href="index.html#read_byte">read_byte</a>
</li>
</ul>
</dd>
<dt>
<a name = "read_double"></a>
<strong>read_double (function)</strong>
</dt>
<dd>
read an IEEE 754 double-precision (64-bit) floating point number
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">function</span>
<a href="index.html#read_byte">read_byte</a>
</li>
</ul>
</dd>
<dt>
<a name = "read_uint"></a>
<strong>read_uint (function, int)</strong>
</dt>
<dd>
read an unsigned integer of any given length
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">function</span>
<a href="index.html#read_byte">read_byte</a>
</li>
<li><span class="parameter">int</span>
length in bytes of unsigned integer
</li>
</ul>
</dd>
<dt>
<a name = "read_uint"></a>
<strong>read_uint (function, int)</strong>
</dt>
<dd>
read a signed integer of any given length
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">function</span>
<a href="index.html#read_byte">read_byte</a>
</li>
<li><span class="parameter">int</span>
length in bytes of integer
</li>
</ul>
</dd>
</dl>
<h2 class="section-header "><a name="misc_binary_helpers"></a>misc binary helpers </h2>
<dl class="function">
<dt>
<a name = "fround"></a>
<strong>fround (number)</strong>
</dt>
<dd>
"returns nearest 32-bit single precision float representation of a number" (or something)
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">number</span>
</li>
</ul>
<h3>Returns:</h3>
<ol>
nearest 32-bit single precision float representation of a number
</ol>
</dd>
</dl>
<h2 class="section-header has-description"><a name="expected_function_inputs"></a>expected function inputs </h2>
<div class="section-description">
functions will expect either a <code>read_byte</code> or <code>write_byte</code> function as inputs
</div>
<dl class="function">
<dt>
<a name = "read_byte"></a>
<strong>read_byte ()</strong>
</dt>
<dd>
<p><code>read_byte</code> is a param name which refers to a function which reads the next byte- returning a whole number between 0-255. </p>
<pre><code>function byte()
left = left - 1
return assert(file_handle:read(1):byte())
--reads the next chracter, and converts it to a "numerical code" using string.byte()
--it's important that this function moves forward in the file stream (as :read(1) does)
end
</code></pre>
<h3>Returns:</h3>
<ol>
a bytecode (an int between 0 and 255.)
</ol>
</dd>
<dt>
<a name = "write_byte"></a>
<strong>write_byte ()</strong>
</dt>
<dd>
<code>write_byte</code> is similar to read_byte, however it is given an input and expected to write it to the file.
(example needed)
</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-08 18:14:41 </i>
<i style="float:right;">Last updated 2024-01-08 19:24:47 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

284
docs/modules/binary.html Normal file
View File

@ -0,0 +1,284 @@
<!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 core</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 core</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<h2>Contents</h2>
<ul>
<li><a href="#reading_binary_inputs">reading binary inputs </a></li>
<li><a href="#misc_binary_helpers">misc binary helpers </a></li>
<li><a href="#expected_function_inputs">expected function inputs </a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><strong>binary</strong></li>
<li><a href="../modules/paths.html">paths</a></li>
</ul>
</div>
<div id="content">
<h1>Module <code>binary</code></h1>
<p>read and write (little endian) binary.</p>
<p> located in <code>mtul.binary</code>.</p>
<h2><a href="#reading_binary_inputs">reading binary inputs </a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#read_single">read_single (function)</a></td>
<td class="summary">read an IEEE 754 single precision (32-bit) floating point number</td>
</tr>
<tr>
<td class="name" nowrap><a href="#read_double">read_double (function)</a></td>
<td class="summary">read an IEEE 754 double-precision (64-bit) floating point number</td>
</tr>
<tr>
<td class="name" nowrap><a href="#read_uint">read_uint (function, int)</a></td>
<td class="summary">read an unsigned integer of any given length</td>
</tr>
<tr>
<td class="name" nowrap><a href="#read_uint">read_uint (function, int)</a></td>
<td class="summary">read a signed integer of any given length</td>
</tr>
</table>
<h2><a href="#misc_binary_helpers">misc binary helpers </a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#fround">fround (number)</a></td>
<td class="summary">"returns nearest 32-bit single precision float representation of a number" (or something)</td>
</tr>
</table>
<h2><a href="#expected_function_inputs">expected function inputs </a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#read_byte">read_byte ()</a></td>
<td class="summary"><code>read_byte</code> is a param name which refers to a function which reads the next byte- returning a whole number between 0-255.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#write_byte">write_byte ()</a></td>
<td class="summary"><code>write_byte</code> is similar to read_byte, however it is given an input and expected to write it to the file.</td>
</tr>
</table>
<br/>
<br/>
<h2 class="section-header has-description"><a name="reading_binary_inputs"></a>reading binary inputs </h2>
<div class="section-description">
read a binary inputs using a <code>read_byte</code> function.
</div>
<dl class="function">
<dt>
<a name = "read_single"></a>
<strong>read_single (function)</strong>
</dt>
<dd>
read an IEEE 754 single precision (32-bit) floating point number
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">function</span>
<a href="../modules/binary.html#read_byte">read_byte</a>
</li>
</ul>
</dd>
<dt>
<a name = "read_double"></a>
<strong>read_double (function)</strong>
</dt>
<dd>
read an IEEE 754 double-precision (64-bit) floating point number
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">function</span>
<a href="../modules/binary.html#read_byte">read_byte</a>
</li>
</ul>
</dd>
<dt>
<a name = "read_uint"></a>
<strong>read_uint (function, int)</strong>
</dt>
<dd>
read an unsigned integer of any given length
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">function</span>
<a href="../modules/binary.html#read_byte">read_byte</a>
</li>
<li><span class="parameter">int</span>
length in bytes of unsigned integer
</li>
</ul>
</dd>
<dt>
<a name = "read_uint"></a>
<strong>read_uint (function, int)</strong>
</dt>
<dd>
read a signed integer of any given length
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">function</span>
<a href="../modules/binary.html#read_byte">read_byte</a>
</li>
<li><span class="parameter">int</span>
length in bytes of integer
</li>
</ul>
</dd>
</dl>
<h2 class="section-header "><a name="misc_binary_helpers"></a>misc binary helpers </h2>
<dl class="function">
<dt>
<a name = "fround"></a>
<strong>fround (number)</strong>
</dt>
<dd>
"returns nearest 32-bit single precision float representation of a number" (or something)
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">number</span>
</li>
</ul>
<h3>Returns:</h3>
<ol>
nearest 32-bit single precision float representation of a number
</ol>
</dd>
</dl>
<h2 class="section-header has-description"><a name="expected_function_inputs"></a>expected function inputs </h2>
<div class="section-description">
functions will expect either a <code>read_byte</code> or <code>write_byte</code> function as inputs
</div>
<dl class="function">
<dt>
<a name = "read_byte"></a>
<strong>read_byte ()</strong>
</dt>
<dd>
<p><code>read_byte</code> is a param name which refers to a function which reads the next byte- returning a whole number between 0-255. </p>
<pre><code>function byte()
left = left - 1
return assert(file_handle:read(1):byte())
--reads the next chracter, and converts it to a "numerical code" using string.byte()
--it's important that this function moves forward in the file stream (as :read(1) does)
end
</code></pre>
<h3>Returns:</h3>
<ol>
a bytecode (an int between 0 and 255.)
</ol>
</dd>
<dt>
<a name = "write_byte"></a>
<strong>write_byte ()</strong>
</dt>
<dd>
<code>write_byte</code> is similar to read_byte, however it is given an input and expected to write it to the file.
(example needed)
</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-08 19:24:47 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

185
docs/modules/paths.html Normal file
View File

@ -0,0 +1,185 @@
<!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 core</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 core</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<h2>Contents</h2>
<ul>
<li><a href="#Tables">Tables</a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><a href="../modules/binary.html">binary</a></li>
<li><strong>paths</strong></li>
</ul>
</div>
<div id="content">
<h1>Module <code>paths</code></h1>
<p>mod utilities
find the paths
find mod information</p>
<p>
</p>
<h2><a href="#Tables">Tables</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#media_paths">media_paths</a></td>
<td class="summary">paths of loaded media.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#modname_by_media">modname_by_media</a></td>
<td class="summary">modname by media.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#overriden_media_paths">overriden_media_paths</a></td>
<td class="summary">overriden media paths.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#overriden_media_paths">overriden_media_paths</a></td>
<td class="summary">mods with overriden media (indexed by media).</td>
</tr>
</table>
<br/>
<br/>
<h2 class="section-header "><a name="Tables"></a>Tables</h2>
<dl class="function">
<dt>
<a name = "media_paths"></a>
<strong>media_paths</strong>
</dt>
<dd>
paths of loaded media.
a list of filepaths of loaded media, i.e:</p>
<pre><code>{
["model.b3d"] = "C:/path/minetest/mods/mod2/models/model.b3d"
["img.png"] = "C:/path/minetest/mods/mod2/textures/img.png"
}
</code></pre>
<p> NOTE: "loaded" meaning the final mediapath- what the client loads.
</dd>
<dt>
<a name = "modname_by_media"></a>
<strong>modname_by_media</strong>
</dt>
<dd>
<p>modname by media.
a list of mods by indexed by the name of loaded media</p>
<pre><code>{
["model.b3d"] = "mod2"
}
</code></pre>
</dd>
<dt>
<a name = "overriden_media_paths"></a>
<strong>overriden_media_paths</strong>
</dt>
<dd>
<p>overriden media paths.
a list of media paths that were overriden by conflicting model names- the unloaded media, i.e:</p>
<pre><code>{
["model.b3d"] = {
"C:/path/minetest/mods/mod1/models/model.b3d"
}
}
</code></pre>
</dd>
<dt>
<a name = "overriden_media_paths"></a>
<strong>overriden_media_paths</strong>
</dt>
<dd>
<p>mods with overriden media (indexed by media).
a list of mods that have overriden media, by media names</p>
<pre><code>{
["model.b3d"] = {
"mod1",
}
}
</code></pre>
</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-08 19:24:47 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

View File

@ -4,15 +4,10 @@ mtul = mtul or {
--initialize namespace vars if not present.
mtul.binary = mtul.binary or {}
mtul.utils = mtul.utils or {}
mtul.paths = mtul.paths or {}
mtul.loaded_modules.filesystem = true
--optionally allow user to overset local math with mtul while still keeping core funcs & consts.
mtul.math = {}
for i, v in pairs(math) do
mtul.math[i] = v
end
--run files. These will directly modify the mtul sub tables.
mtul.path = minetest.get_modpath("mtul_filesystem")
dofile(mtul.path.."/modlib/binary.lua")
dofile(mtul.path.."/modlib/mod_utils.lua")
dofile(mtul.path.."/modlib/mod_utils_media.lua")
local path = minetest.get_modpath("mtul_filesystem")
dofile(path.."/modlib/binary.lua")
dofile(path.."/modlib/mod_utils.lua")
dofile(path.."/modlib/paths.lua")

View File

@ -1,5 +1,10 @@
--felt this was big enough that it practically deserved it's own file.
-- TODO support for server texture packs (and possibly client TPs in singleplayer?)
--- mod utilities
--find the paths
--- find mod information
-- @module paths
local media_foldernames = {"textures", "sounds", "media", "models", "locale"}
local media_extensions = {
-- Textures
@ -7,14 +12,14 @@ local media_extensions = {
-- Sounds
"ogg";
-- Models
"x", "b3d", "md2", "obj";
"x", "b3d", "md2", "obj", "gltf";
-- Translations
"tr";
}
local function split_extension(filename)
return filename:match"^(.*)%.(.*)$"
end
--mmmm yes, according to modlib we should make this loop it's own global function apart of modlib. Foolish me thinking we can just make case specific
--make it a set.
for i, v in pairs(media_extensions) do
media_extensions[v] = true
end
@ -47,21 +52,55 @@ end
local paths = {}
local mods = {}
local overridden_paths = {}
local overridden_mods = {}
local mods_with_overriden_media = {}
for _, mod in ipairs(mtul.utils.get_mod_load_order()) do
local mod_media = collect_media(mod.name)
for medianame, path in pairs(mod_media) do
if paths[medianame] then
overridden_paths[medianame] = overridden_paths[medianame] or {}
table.insert(overridden_paths[medianame], paths[medianame])
overridden_mods[medianame] = overridden_mods[medianame] or {}
table.insert(overridden_mods[medianame], mods[medianame])
mods_with_overriden_media[medianame] = mods_with_overriden_media[medianame] or {}
table.insert(mods_with_overriden_media[medianame], mods[medianame])
end
paths[medianame] = path
mods[medianame] = mod.name
end
end
mtul.media_paths = paths
mtul.overriden_media_paths = paths
mtul.modname_by_media = paths
mtul.overriden_modnames_by_media = paths
--- paths of loaded media.
-- a list of filepaths of loaded media, i.e:
-- {
-- ["model.b3d"] = "C:/path/minetest/mods/mod2/models/model.b3d"
-- ["img.png"] = "C:/path/minetest/mods/mod2/textures/img.png"
-- }
-- NOTE: "loaded" meaning the final mediapath- what the client loads.
-- @table media_paths
mtul.paths.media_paths = paths
---modname by media.
-- a list of mods by indexed by the name of loaded media
-- {
-- ["model.b3d"] = "mod2"
-- }
-- @table modname_by_media
-- NOTE: "loaded" meaning the final mediapath- what the client loads.
mtul.paths.modname_by_media = mods
--- overriden media paths.
-- a list of media paths that were overriden by conflicting model names- the unloaded media, i.e:
-- {
-- ["model.b3d"] = {
-- "C:/path/minetest/mods/mod1/models/model.b3d"
-- }
-- }
-- @table overriden_media_paths
mtul.paths.overriden_media_paths = overridden_paths
--- mods with overriden media (indexed by media).
-- a list of mods that have overriden media, by media names
-- {
-- ["model.b3d"] = {
-- "mod1",
-- }
-- }
-- @table overriden_media_paths
mtul.paths.mods_with_overriden_media = mods_with_overriden_media