Add Support for Generating HTML Documentation with LDoc (#58)

* Add Python scripts to generate temp files that can be parsed by LDoc
* Add config & script for generating HTML docs with LDoc...
* Add Lua docstrings for API & items
* Add workflow for building API reference docs on gh-pages branch
* Add LDoc's default stylesheet
* LDoc: make navigation panel fixed
This commit is contained in:
Jordan Irwin 2021-07-30 07:12:29 -07:00 committed by GitHub
parent a897f7e72f
commit c790b20169
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 1967 additions and 7 deletions

33
.github/workflows/reference.yml vendored Normal file
View File

@ -0,0 +1,33 @@
name: Build Reference
on:
push:
branches:
- master
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup Lua
uses: leafo/gh-actions-lua@v8
with:
luaVersion: 5.4
- name: Setup Lua Rocks
uses: leafo/gh-actions-luarocks@v4
- name: Setup LDoc dependencies
run: luarocks install --only-deps https://raw.githubusercontent.com/lunarmodules/LDoc/master/ldoc-scm-3.rockspec
- name: Setup LDoc
run: git clone --single-branch --branch=custom https://github.com/AntumDeluge/ldoc.git .ldoc/ldoc && chmod +x .ldoc/ldoc/ldoc.lua
- name: Generate temp files
run: chmod +x .ldoc/parse_*.py && ./.ldoc/parse_src.py && ./.ldoc/parse_settings.py && ./.ldoc/parse_crafts.py
- name: Generate docs
run: ./.ldoc/ldoc/ldoc.lua --UNSAFE_NO_SANDBOX -c .ldoc/config.ld -d 3d_armor/docs/reference "$(pwd)"
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./3d_armor/docs

344
.ldoc/config.ld Normal file
View File

@ -0,0 +1,344 @@
-- Place this file in mod "docs" directory
local print, type, string, table, tostring, tonumber, error, pairs, ipairs
if import then
print = import("print")
type = import("type")
string = import("string")
table = import("table")
tostring = import("tostring")
tonumber = import("tonumber")
error = import("error")
pairs = import("pairs")
ipairs = import("ipairs")
end
project = "3d_armor"
title = "3D Armor"
format = "markdown"
not_luadoc = true
boilerplate = false
wrap = false
style = true
file = {
"3d_armor/api.lua",
".ldoc/settings.luadoc",
--".ldoc/armors.luadoc",
".ldoc/helmets.luadoc",
".ldoc/chestplates.luadoc",
".ldoc/leggings.luadoc",
".ldoc/boots.luadoc",
".ldoc/shields.luadoc",
".ldoc/crafting.luadoc",
}
new_type("setting", "Settings")
new_type("armor", "Armors")
new_type("craft", "Craft Recipes")
alias("helmet", "armor")
alias("chestplate", "armor")
alias("leggings", "armor")
alias("boots", "armor")
alias("shield", "armor")
alias("grp", "group")
-- function declarations
local format_text
local format_group
custom_tags = {
-- settings
{
"settype",
title = "Type",
hidden = true,
},
{
"min",
title = "Minimum Value",
hidden = true,
},
{
"max",
title = "Maximum Value",
hidden = true,
},
{
"default",
title = "Default Value",
hidden = true,
},
-- craft items/tools
{
-- specify image basename only
"img",
title = "Image",
format = function(value)
local img = "<img src=\"https://raw.githubusercontent.com/minetest-mods/3d_armor/master/"
if string then
if string.find(value, "shields_") == 1 then
img = img .. "shields/"
else
img = img .. "3d_armor/"
end
end
return img .. "textures/" .. value .. "\" style=\"width:32px; height:32px;\" />"
end,
},
{
-- specify full (relative or absolute) image path
"image",
title = "Image",
format = function(value)
return "<img src=\"" .. value .. "\" style=\"width:32px; height:32px;\" />"
end,
},
{
"group",
title = "Groups",
format = function(value)
return format_group(value)
end,
},
{
"armorgrp",
title = "Armor Groups",
format = function(value)
return format_group(value)
end,
},
{
"damagegrp",
title = "Damage Groups",
format = function(value)
return format_group(value)
end,
},
}
if string then
string.trim = function(st, delim)
if not delim then
delim = " "
end
while string.find(st, delim) == 1 do
st = st:sub(2)
end
while string.sub(st, string.len(st)) == delim do
st = st:sub(1, string.len(st)-1)
end
return st
end
string.split = function(st, delim)
local list = {}
local idx = string.find(st, delim)
while idx do
table.insert(list, st:sub(1, idx-1))
st = st:sub(idx+1)
idx = string.find(st, delim)
end
-- add remaining item
table.insert(list, st)
return list
end
end
if table then
if not table.copy then
table.copy = function(orig_table)
local new_table = {}
for k, v in pairs(orig_table) do
new_table[k] = v
end
return new_table
end
end
end
format_text = function(text, flags)
local ret = "<"
local ttype = "span"
if flags.code then
ttype = "code"
end
ret = ret .. ttype .. " style=\""
if flags.size then
ret = ret .. "font-size:" .. flags.size .. ";"
end
if flags.mono then
ret = ret .. "font-family:monospace;"
end
if flags.italic then
ret = ret .. "font-style:italic;"
end
if flags.bold then
ret = ret .. "font-weight:bold;"
end
if flags.color then
ret = ret .. "color:" .. flags.color .. ";"
end
if flags.bgcolor then
ret = ret .. "background-color:" .. flags.bgcolor .. ";"
end
ret = ret .. "\">" .. text .. "</" .. ttype .. ">"
return ret
end
format_group = function(text)
if string then
local idx, k, v = string.find(text, " ")
if idx then
text = format_text(string.sub(text, 1, idx-1) .. ": ", {mono=true, color="darkgreen"})
.. string.sub(text, idx)
end
end
return text
end
local function format_setting_tag(desc, value)
return "\n- <span style=\"font-size:80%;\">`" .. desc .. ":`</span> `" .. value .. "`"
end
local registered = {
settings = {},
}
local function setting_handler(item)
if not ipairs or not type then
return item
end
local tags = {
{"settype", "type"},
{"default"},
{"min", "minimum value"},
{"max", "maximum value"},
}
local def = {
["settype"] = format_setting_tag("type", "string"),
}
for _, t in ipairs(tags) do
local name = t[1]
local desc = t[2]
if not desc then desc = name end
local value = item.tags[name]
if type(value) == "table" then
if #value > 1 then
local msg = item.file.filename .. " (line " .. item.lineno
.. "): multiple instances of tag \"" .. name .. "\" found"
if error then
error(msg)
elseif print then
print("WARNING: " .. msg)
end
end
if value[1] then
def[name] = format_setting_tag(desc, value[1])
end
end
end
item.description = item.description .. "\n\n**Definition:**\n" .. def.settype
for _, t in ipairs({def.default, def.min, def.max}) do
if t then
item.description = item.description .. t
end
end
registered.settings[item.name] = true
return item
end
function custom_display_name_handler(item, default_handler)
if item.type == "setting" then
-- avoid parsing again
if not registered.settings[item.name] then
item = setting_handler(item)
end
elseif item.type == "armor" and string then
-- HACK: not sure why "shields:" is being trimmed from item name
if string.find(item.name, "shield_") == 1 then
item.name = "shields:" .. item.name
end
end
if item then
return default_handler(item)
end
end
local custom_see_links = {
["ObjectRef"] = "https://minetest.gitlab.io/minetest/class-reference/#objectref",
["PlayerMetaRef"] = "https://minetest.gitlab.io/minetest/class-reference/#playermetaref",
["ItemDef"] = "https://minetest.gitlab.io/minetest/definition-tables/#item-definition",
["ItemStack"] = "https://minetest.gitlab.io/minetest/class-reference/#itemstack",
["groups"] = "https://minetest.gitlab.io/minetest/groups/",
["entity_damage_mechanism"] = "https://minetest.gitlab.io/minetest/entity-damage-mechanism/",
["vector"] = "https://minetest.gitlab.io/minetest/representations-of-simple-things/#positionvector",
}
local function format_custom_see(name, section)
local url = custom_see_links[name]
if not url then
url = ""
end
if not name then
name = ""
end
return name, url
end
custom_see_handler("^(ObjectRef)$", function(name, section)
return format_custom_see(name, section)
end)
custom_see_handler("^(PlayerMetaRef)$", function(name, section)
return format_custom_see(name, section)
end)
custom_see_handler("^(ItemDef)$", function(name, section)
return format_custom_see(name, section)
end)
custom_see_handler("^(groups)$", function(name, section)
return format_custom_see(name, section)
end)
custom_see_handler("^(entity_damage_mechanism)$", function(name, section)
return format_custom_see(name, section)
end)
custom_see_handler("^(ItemStack)$", function(name, section)
return format_custom_see(name, section)
end)
custom_see_handler("^(vector)$", function(name, section)
return name, "https://minetest.gitlab.io/minetest/representations-of-simple-things/#positionvector"
end)

304
.ldoc/ldoc.css Normal file
View File

@ -0,0 +1,304 @@
/* BEGIN RESET
Copyright (c) 2010, Yahoo! Inc. All rights reserved.
Code licensed under the BSD License:
http://developer.yahoo.com/yui/license.html
version: 2.8.2r1
*/
html {
color: #000;
background: #FFF;
}
body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
margin: 0;
padding: 0;
}
table {
border-collapse: collapse;
border-spacing: 0;
}
fieldset,img {
border: 0;
}
address,caption,cite,code,dfn,em,strong,th,var,optgroup {
font-style: inherit;
font-weight: inherit;
}
del,ins {
text-decoration: none;
}
li {
margin-left: 20px;
}
caption,th {
text-align: left;
}
h1,h2,h3,h4,h5,h6 {
font-size: 100%;
font-weight: bold;
}
q:before,q:after {
content: '';
}
abbr,acronym {
border: 0;
font-variant: normal;
}
sup {
vertical-align: baseline;
}
sub {
vertical-align: baseline;
}
legend {
color: #000;
}
input,button,textarea,select,optgroup,option {
font-family: inherit;
font-size: inherit;
font-style: inherit;
font-weight: inherit;
}
input,button,textarea,select {*font-size:100%;
}
/* END RESET */
body {
margin-left: 1em;
margin-right: 1em;
font-family: arial, helvetica, geneva, sans-serif;
background-color: #ffffff; margin: 0px;
}
code, tt { font-family: monospace; font-size: 1.1em; }
span.parameter { font-family:monospace; }
span.parameter:after { content:":"; }
span.types:before { content:"("; }
span.types:after { content:")"; }
.type { font-weight: bold; font-style:italic }
body, p, td, th { font-size: .95em; line-height: 1.2em;}
p, ul { margin: 10px 0 0 0px;}
strong { font-weight: bold;}
em { font-style: italic;}
h1 {
font-size: 1.5em;
margin: 20px 0 20px 0;
}
h2, h3, h4 { margin: 15px 0 10px 0; }
h2 { font-size: 1.25em; }
h3 { font-size: 1.15em; }
h4 { font-size: 1.06em; }
a:link { font-weight: bold; color: #004080; text-decoration: none; }
a:visited { font-weight: bold; color: #006699; text-decoration: none; }
a:link:hover { text-decoration: underline; }
hr {
color:#cccccc;
background: #00007f;
height: 1px;
}
blockquote { margin-left: 3em; }
ul { list-style-type: disc; }
p.name {
font-family: "Andale Mono", monospace;
padding-top: 1em;
}
pre {
background-color: rgb(245, 245, 245);
border: 1px solid #C0C0C0; /* silver */
padding: 10px;
margin: 10px 0 10px 0;
overflow: auto;
font-family: "Andale Mono", monospace;
}
pre.example {
font-size: .85em;
}
table.index { border: 1px #00007f; }
table.index td { text-align: left; vertical-align: top; }
#container {
margin-left: 1em;
margin-right: 1em;
background-color: #f0f0f0;
}
#product {
text-align: center;
border-bottom: 1px solid #cccccc;
background-color: #ffffff;
}
#product big {
font-size: 2em;
}
#main {
background-color: #f0f0f0;
border-left: 2px solid #cccccc;
}
#navigation {
float: left;
width: 14em;
vertical-align: top;
background-color: #f0f0f0;
overflow: visible;
position: fixed;
}
#navigation h2 {
background-color:#e7e7e7;
font-size:1.1em;
color:#000000;
text-align: left;
padding:0.2em;
border-top:1px solid #dddddd;
border-bottom:1px solid #dddddd;
}
#navigation ul
{
font-size:1em;
list-style-type: none;
margin: 1px 1px 10px 1px;
}
#navigation li {
text-indent: -1em;
display: block;
margin: 3px 0px 0px 22px;
}
#navigation li li a {
margin: 0px 3px 0px -1em;
}
#content {
margin-left: 14em;
padding: 1em;
width: 700px;
border-left: 2px solid #cccccc;
border-right: 2px solid #cccccc;
background-color: #ffffff;
}
#about {
clear: both;
padding: 5px;
border-top: 2px solid #cccccc;
background-color: #ffffff;
}
@media print {
body {
font: 12pt "Times New Roman", "TimeNR", Times, serif;
}
a { font-weight: bold; color: #004080; text-decoration: underline; }
#main {
background-color: #ffffff;
border-left: 0px;
}
#container {
margin-left: 2%;
margin-right: 2%;
background-color: #ffffff;
}
#content {
padding: 1em;
background-color: #ffffff;
}
#navigation {
display: none;
}
pre.example {
font-family: "Andale Mono", monospace;
font-size: 10pt;
page-break-inside: avoid;
}
}
table.module_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.module_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.module_list td.name { background-color: #f0f0f0; min-width: 200px; }
table.module_list td.summary { width: 100%; }
table.function_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.function_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.function_list td.name { background-color: #f0f0f0; min-width: 200px; }
table.function_list td.summary { width: 100%; }
ul.nowrap {
overflow:auto;
white-space:nowrap;
}
dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
dl.table h3, dl.function h3 {font-size: .95em;}
/* stop sublists from having initial vertical space */
ul ul { margin-top: 0px; }
ol ul { margin-top: 0px; }
ol ol { margin-top: 0px; }
ul ol { margin-top: 0px; }
/* make the target distinct; helps when we're navigating to a function */
a:target + * {
background-color: #FF9;
}
/* styles for prettification of source */
pre .comment { color: #558817; }
pre .constant { color: #a8660d; }
pre .escape { color: #844631; }
pre .keyword { color: #aa5050; font-weight: bold; }
pre .library { color: #0e7c6b; }
pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
pre .string { color: #8080ff; }
pre .number { color: #f8660d; }
pre .operator { color: #2239a8; font-weight: bold; }
pre .preprocessor, pre .prepro { color: #a33243; }
pre .global { color: #800080; }
pre .user-keyword { color: #800080; }
pre .prompt { color: #558817; }
pre .url { color: #272fc2; text-decoration: underline; }

46
.ldoc/parse_crafts.py Executable file
View File

@ -0,0 +1,46 @@
#!/usr/bin/env python
# This script will parse source files for craft recipes.
import sys, os, codecs, errno
path = os.path.realpath(__file__)
script = os.path.basename(path)
d_root = os.path.dirname(os.path.dirname(path))
d_ldoc = os.path.join(d_root, ".ldoc")
craftfile = os.path.realpath(os.path.join(d_root, "3d_armor/armor.lua"))
if not os.path.isfile(craftfile):
print("ERROR: craft file does not exist for parsing: {}".format(craftfile))
sys.exit(errnor.ENOENT)
buffer = codecs.open(craftfile, "r", "utf-8")
if not buffer:
print("ERROR: could not open file for reading: {}".format(craftfile))
sys.exit(errno.EIO)
data_in = buffer.read()
buffer.close()
craft = ""
data_in = data_in.replace("\r\n", "\n").replace("\r", "\n")
for sect in data_in.split("\n---"):
if "@craft armor" in sect:
sect = "---{}".format(sect)
for li in sect.split("\n"):
if li.startswith("--"):
craft = "{}\n{}".format(craft, li)
outfile = os.path.join(d_ldoc, "crafting.luadoc")
buffer = codecs.open(outfile, "w", "utf-8")
if not buffer:
print("ERROR: could not open file for writing: {}".format(outfile))
sys.exit(errno.EIO)
buffer.write("\n--- 3D Armor Crafting\n--\n-- @topic crafting\n\n{}\n".format(craft))
buffer.close()
print("crafts exported to\t{}".format(outfile))

118
.ldoc/parse_settings.py Executable file
View File

@ -0,0 +1,118 @@
#!/usr/bin/env python
# This script will format "settingtypes.txt" file found at the root
# of 3d_armor modpack into a format readable by LDoc.
import sys, os, errno, codecs
path = os.path.realpath(__file__)
script = os.path.basename(path)
d_root = os.path.dirname(os.path.dirname(path))
d_ldoc = os.path.join(d_root, ".ldoc")
f_settings = os.path.join(d_root, "settingtypes.txt")
if not os.path.isfile(f_settings):
print("settingtypes.txt does not exist")
sys.exit(errno.ENOENT)
i_stream = codecs.open(f_settings, "r", "utf-8")
data_in = i_stream.read()
i_stream.close()
data_in = data_in.replace("\r", "")
sets = data_in.split("\n\n")
for idx in reversed(range(len(sets))):
set = sets[idx]
lines = set.split("\n")
for idx2 in reversed(range(len(lines))):
li = lines[idx2].strip(" \t")
if li == "" or li[0] == "[":
lines.pop(idx2)
if len(lines) == 0:
sets.pop(idx)
else:
sets[idx] = "\n".join(lines)
filtered = []
for set in sets:
comment = False
lines = set.split("\n")
new_lines = []
for li in lines:
if li[0] == "#":
new_lines.append(li)
else:
new_lines.append(li)
filtered.append("\n".join(new_lines))
new_lines = []
settings = []
def parse_setting(set):
desc = []
setting = summary = stype = sdefault = soptions = None
for li in set.split("\n"):
if li[0] == "#":
desc.append("-- {}".format(li.lstrip(" #")))
else:
setting = li.split(" ")[0]
summary = li.split(")")[0].split("(")[-1]
li = li.split(")")[-1].strip()
rem = li.split(" ")
stype = rem[0]
rem.pop(0)
if len(rem) > 0:
sdefault = rem[0]
rem.pop(0)
if len(rem) > 0:
soptions = " ".join(rem)
if not setting:
return
st = "---"
if summary:
if summary[-1] != ".":
summary = "{}.".format(summary)
st = "{} {}".format(st, summary)
st = "{}\n--".format(st)
if len(desc) > 0:
st = "{}\n{}\n--".format(st, "\n".join(desc))
st = "{}\n-- @setting {}".format(st, setting)
if stype:
st = "{}\n-- @settype {}".format(st, stype)
if sdefault:
st = "{}\n-- @default {}".format(st, sdefault)
# TODO: add options
settings.append(st)
for f in filtered:
parse_setting(f)
outfile = os.path.join(d_ldoc, "settings.luadoc")
data_out = "\n--- 3D Armor Settings\n--\n-- @topic settings\n\n\n{}\n".format("\n\n".join(settings))
o_stream = codecs.open(outfile, "w", "utf-8")
if not o_stream:
print("ERROR: could not open file for writing: {}".format(outfile))
sys.exit(errno.EIO)
o_stream.write(data_out)
o_stream.close()
print("settings exported to\t{}".format(outfile))

90
.ldoc/parse_src.py Executable file
View File

@ -0,0 +1,90 @@
#!/usr/bin/env python
# This script will parse source files for docstring.
import os, codecs
path = os.path.realpath(__file__)
script = os.path.basename(path)
d_root = os.path.dirname(os.path.dirname(path))
d_ldoc = os.path.join(d_root, ".ldoc")
armor_types = {
"armor": {"topic": "Armors", "values": []},
"helmet": {"topic": "Helmets", "values": []},
"chestplate": {"topic": "Chestplates", "values": []},
"leggings": {"topic": "Leggings", "values": []},
"boots": {"topic": "Boots", "values": []},
"shield": {"topic": "Shields", "values": []},
}
def parse_file(f):
buffer = codecs.open(f, "r", "utf-8")
if not buffer:
print("ERROR: could not open file for reading: {}".format(f))
return
data_in = buffer.read()
buffer.close()
# format to LF (Unix)
data_in = data_in.replace("\r\n", "\n").replace("\r", "\n")
current_item = []
item_type = None
new_item = False
for li in data_in.split("\n"):
li = li.strip()
if li.startswith("---"):
new_item = True
elif not li.startswith("--"):
new_item = False
if new_item:
current_item.append(li)
if not item_type:
for a_type in armor_types:
if "@{} ".format(a_type) in li:
item_type = a_type
break
elif item_type and len(current_item):
armor_types[item_type]["values"].append("\n".join(current_item))
item_type = None
current_item = []
else:
current_item = []
to_parse = []
for obj in os.listdir(d_root):
fullpath = os.path.join(d_root, obj)
if not obj.startswith(".") and os.path.isdir(fullpath):
for root, dirs, files in os.walk(fullpath):
for f in files:
if f.endswith(".lua"):
to_parse.append(os.path.join(root, f))
for p in to_parse:
if not os.path.isfile(p):
print("ERROR: {} is not a file".format(p))
else:
parse_file(p)
for t in armor_types:
topic = armor_types[t]["topic"]
items = armor_types[t]["values"]
if len(items):
outfile = os.path.join(d_ldoc, "{}.luadoc".format(topic.lower()))
buffer = codecs.open(outfile, "w", "utf-8")
if not buffer:
print("ERROR: could not open file for writing: {}".format(outfile))
continue
buffer.write("\n--- 3D Armor {}\n--\n-- @topic {}\n\n\n{}\n".format(topic, topic.lower(), "\n\n".join(items)))
buffer.close()
print("{} exported to\t{}".format(topic.lower(), outfile))

View File

@ -396,6 +396,8 @@ If all of the above were made of material "wood" the player would recieve an ***
## Armor Functions
See also: [API Reference](https://minetest-mods.github.io/3d_armor/reference/)
### armor set_player_armor
armor:set_player_armor(player)

View File

@ -1,3 +1,82 @@
--- 3D Armor API
--
-- @topic api
local transparent_armor = minetest.settings:get_bool("armor_transparent", false)
--- Tables
--
-- @section tables
--- Armor definition table used for registering armor.
--
-- @table ArmorDef
-- @tfield string description Human-readable name/description.
-- @tfield string inventory_image Image filename used for icon.
-- @tfield table groups See: `ArmorDef.groups`
-- @tfield table armor_groups See: `ArmorDef.armor_groups`
-- @tfield table damage_groups See: `ArmorDef.damage_groups`
-- @see ItemDef
-- @usage local def = {
-- description = "Wood Helmet",
-- inventory_image = "3d_armor_inv_helmet_wood.png",
-- groups = {armor_head=1, armor_heal=0, armor_use=2000, flammable=1},
-- armor_groups = {fleshy=5},
-- damage_groups = {cracky=3, snappy=2, choppy=3, crumbly=2, level=1},
-- }
--- Groups table.
--
-- General groups defining item behavior.
--
-- Some commonly used groups: ***armor\_&lt;type&gt;***, ***armor\_heal***, ***armor\_use***
--
-- @table ArmorDef.groups
-- @tfield int armor_type The armor type. "head", "torso", "hands", "shield", etc.
-- (**Note:** replace "type" with actual type).
-- @tfield int armor_heal Healing value of armor when equipped.
-- @tfield int armor_use Amount of uses/damage before armor "breaks".
-- @see groups
-- @usage groups = {
-- armor_head = 1,
-- armor_heal = 5,
-- armor_use = 2000,
-- flammable = 1,
-- }
--- Armor groups table.
--
-- Groups that this item is effective against when taking damage.
--
-- Some commonly used groups: ***fleshy***
--
-- @table ArmorDef.armor_groups
-- @usage armor_groups = {
-- fleshy = 5,
-- }
--- Damage groups table.
--
-- Groups that this item is effective on when used as a weapon/tool.
--
-- Some commonly used groups: ***cracky***, ***snappy***, ***choppy***, ***crumbly***, ***level***
--
-- @table ArmorDef.damage_groups
-- @see entity_damage_mechanism
-- @usage damage_groups = {
-- cracky = 3,
-- snappy = 2,
-- choppy = 3,
-- crumbly = 2,
-- level = 1,
-- }
--- @section end
-- support for i18n
local S = minetest.get_translator(minetest.get_current_modname())
@ -105,8 +184,23 @@ armor.config = {
punch_damage = true,
}
-- Armor Registration
--- Methods
--
-- @section methods
--- Registers a new armor item.
--
-- @function armor:register_armor
-- @tparam string name Armor item technical name (ex: "3d\_armor:helmet\_gold").
-- @tparam ArmorDef def Armor definition table.
-- @usage armor:register_armor("3d_armor:helmet_wood", {
-- description = "Wood Helmet",
-- inventory_image = "3d_armor_inv_helmet_wood.png",
-- groups = {armor_head=1, armor_heal=0, armor_use=2000, flammable=1},
-- armor_groups = {fleshy=5},
-- damage_groups = {cracky=3, snappy=2, choppy=3, crumbly=2, level=1},
-- })
armor.register_armor = function(self, name, def)
def.on_secondary_use = function(itemstack, player)
return armor:equip(player, itemstack)
@ -132,6 +226,11 @@ armor.register_armor = function(self, name, def)
minetest.register_tool(name, def)
end
--- Registers a new armor group.
--
-- @function armor:register_armor_group
-- @tparam string group Group ID.
-- @tparam int base Base armor value.
armor.register_armor_group = function(self, group, base)
base = base or 100
self.registered_groups[group] = base
@ -140,38 +239,92 @@ armor.register_armor_group = function(self, group, base)
end
end
-- Armor callbacks
--- Armor Callbacks Registration
--
-- @section callbacks
--- Registers a callback for when player visuals are update.
--
-- @function armor:register_on_update
-- @tparam function func Function to be executed.
-- @see armor:update_player_visuals
-- @usage armor:register_on_update(function(player, index, stack)
-- -- code to execute
-- end)
armor.register_on_update = function(self, func)
if type(func) == "function" then
table.insert(self.registered_callbacks.on_update, func)
end
end
--- Registers a callback for when armor is equipped.
--
-- @function armor:register_on_equip
-- @tparam function func Function to be executed.
-- @usage armor:register_on_equip(function(player, index, stack)
-- -- code to execute
-- end)
armor.register_on_equip = function(self, func)
if type(func) == "function" then
table.insert(self.registered_callbacks.on_equip, func)
end
end
--- Registers a callback for when armor is unequipped.
--
-- @function armor:register_on_unequip
-- @tparam function func Function to be executed.
-- @usage armor:register_on_unequip(function(player, index, stack)
-- -- code to execute
-- end)
armor.register_on_unequip = function(self, func)
if type(func) == "function" then
table.insert(self.registered_callbacks.on_unequip, func)
end
end
--- Registers a callback for when armor is damaged.
--
-- @function armor:register_on_damage
-- @tparam function func Function to be executed.
-- @see armor:damage
-- @usage armor:register_on_damage(function(player, index, stack)
-- -- code to execute
-- end)
armor.register_on_damage = function(self, func)
if type(func) == "function" then
table.insert(self.registered_callbacks.on_damage, func)
end
end
--- Registers a callback for when armor is destroyed.
--
-- @function armor:register_on_destroy
-- @tparam function func Function to be executed.
-- @see armor:damage
-- @usage armor:register_on_destroy(function(player, index, stack)
-- -- code to execute
-- end)
armor.register_on_destroy = function(self, func)
if type(func) == "function" then
table.insert(self.registered_callbacks.on_destroy, func)
end
end
--- @section end
--- Methods
--
-- @section methods
--- Runs callbacks.
--
-- @function armor:run_callbacks
-- @tparam function callback Function to execute.
-- @tparam ObjectRef player First parameter passed to callback.
-- @tparam int index Second parameter passed to callback.
-- @tparam ItemStack stack Callback owner.
armor.run_callbacks = function(self, callback, player, index, stack)
if stack then
local def = stack:get_definition() or {}
@ -187,6 +340,10 @@ armor.run_callbacks = function(self, callback, player, index, stack)
end
end
--- Updates visuals.
--
-- @function armor:update_player_visuals
-- @tparam ObjectRef player
armor.update_player_visuals = function(self, player)
if not player then
return
@ -202,10 +359,10 @@ armor.update_player_visuals = function(self, player)
self:run_callbacks("on_update", player)
end
-- armor is not visible on player model if enabled
local transparent_armor = minetest.settings:get_bool("armor_transparent", false)
--- Sets player's armor attributes.
--
-- @function armor:set_player_armor
-- @tparam ObjectRef player
armor.set_player_armor = function(self, player)
local name, armor_inv = self:get_valid_player(player, "[set_player_armor]")
if not name then
@ -366,6 +523,13 @@ armor.set_player_armor = function(self, player)
self:update_player_visuals(player)
end
--- Action when armor is punched.
--
-- @function armor:punch
-- @tparam ObjectRef player Player wearing the armor.
-- @tparam ObjectRef hitter Entity attacking player.
-- @tparam[opt] int time_from_last_punch Time in seconds since last punch action.
-- @tparam[opt] table tool_capabilities See `entity_damage_mechanism`.
armor.punch = function(self, player, hitter, time_from_last_punch, tool_capabilities)
local name, armor_inv = self:get_valid_player(player, "[punch]")
if not name then
@ -451,6 +615,13 @@ armor.punch = function(self, player, hitter, time_from_last_punch, tool_capabili
self.def[name].count = count
end
--- Action when armor is damaged.
--
-- @function armor:damage
-- @tparam ObjectRef player
-- @tparam int index Inventory index where armor is equipped.
-- @tparam ItemStack stack Armor item receiving damaged.
-- @tparam int use Amount of wear to add to armor item.
armor.damage = function(self, player, index, stack, use)
local old_stack = ItemStack(stack)
local worn_armor = armor:get_weared_armor_elements(player)
@ -469,6 +640,11 @@ armor.damage = function(self, player, index, stack, use)
end
end
--- Get elements of equipped armor.
--
-- @function armor:get_weared_armor_elements
-- @tparam ObjectRef player
-- @treturn table List of equipped armors.
armor.get_weared_armor_elements = function(self, player)
local name, inv = self:get_valid_player(player, "[get_weared_armor]")
local weared_armor = {}
@ -485,6 +661,12 @@ armor.get_weared_armor_elements = function(self, player)
return weared_armor
end
--- Equips a piece of armor to a player.
--
-- @function armor:equip
-- @tparam ObjectRef player Player to whom item is equipped.
-- @tparam ItemStack itemstack Armor item to be equipped.
-- @treturn ItemStack Leftover item stack.
armor.equip = function(self, player, itemstack)
local name, armor_inv = self:get_valid_player(player, "[equip]")
local armor_element = self:get_element(itemstack:get_name())
@ -509,6 +691,12 @@ armor.equip = function(self, player, itemstack)
return itemstack
end
--- Unequips a piece of armor from a player.
--
-- @function armor:unequip
-- @tparam ObjectRef player Player from whom item is removed.
-- @tparam string armor_element Armor type identifier associated with the item
-- to be removed ("head", "torso", "hands", "shield", "legs", "feet", etc.).
armor.unequip = function(self, player, armor_element)
local name, armor_inv = self:get_valid_player(player, "[unequip]")
if not name then
@ -534,6 +722,10 @@ armor.unequip = function(self, player, armor_element)
end
end
--- Removes all armor worn by player.
--
-- @function armor:remove_all
-- @tparam ObjectRef player
armor.remove_all = function(self, player)
local name, inv = self:get_valid_player(player, "[remove_all]")
if not name then
@ -546,6 +738,11 @@ end
local skin_mod
--- Retrieves player's current skin.
--
-- @function armor:get_player_skin
-- @tparam string name Player name.
-- @treturn string Skin filename.
armor.get_player_skin = function(self, name)
if (skin_mod == "skins" or skin_mod == "simple_skins") and skins.skins[name] then
return skins.skins[name]..".png"
@ -557,6 +754,10 @@ armor.get_player_skin = function(self, name)
return armor.default_skin..".png"
end
--- Updates skin.
--
-- @function armor:update_skin
-- @tparam string name Player name.
armor.update_skin = function(self, name)
minetest.after(0, function()
local pplayer = minetest.get_player_by_name(name)
@ -567,10 +768,19 @@ armor.update_skin = function(self, name)
end)
end
--- Adds preview for armor inventory.
--
-- @function armor:add_preview
-- @tparam string preview Preview image filename.
armor.add_preview = function(self, preview)
skin_previews[preview] = true
end
--- Retrieves preview for armor inventory.
--
-- @function armor:get_preview
-- @tparam string name Player name.
-- @treturn string Preview image filename.
armor.get_preview = function(self, name)
local preview = string.gsub(armor:get_player_skin(name), ".png", "_preview.png")
if skin_previews[preview] then
@ -579,6 +789,12 @@ armor.get_preview = function(self, name)
return "character_preview.png"
end
--- Retrieves armor formspec.
--
-- @function armor:get_armor_formspec
-- @tparam string name Player name.
-- @tparam[opt] bool listring Use `listring` formspec element (default: `false`).
-- @treturn string Formspec formatted string.
armor.get_armor_formspec = function(self, name, listring)
if armor.def[name].init_time == 0 then
return "label[0,0;Armor not initialized!]"
@ -601,6 +817,11 @@ armor.get_armor_formspec = function(self, name, listring)
return formspec
end
--- Retrieves element.
--
-- @function armor:get_element
-- @tparam string item_name
-- @return Armor element.
armor.get_element = function(self, item_name)
for _, element in pairs(armor.elements) do
if minetest.get_item_group(item_name, "armor_"..element) > 0 then
@ -609,6 +830,11 @@ armor.get_element = function(self, item_name)
end
end
--- Serializes armor inventory.
--
-- @function armor:serialize_inventory_list
-- @tparam table list Inventory contents.
-- @treturn string
armor.serialize_inventory_list = function(self, list)
local list_table = {}
for _, stack in ipairs(list) do
@ -617,6 +843,11 @@ armor.serialize_inventory_list = function(self, list)
return minetest.serialize(list_table)
end
--- Deserializes armor inventory.
--
-- @function armor:deserialize_inventory_list
-- @tparam string list_string Serialized inventory contents.
-- @treturn table
armor.deserialize_inventory_list = function(self, list_string)
local list_table = minetest.deserialize(list_string)
local list = {}
@ -626,6 +857,11 @@ armor.deserialize_inventory_list = function(self, list_string)
return list
end
--- Loads armor inventory.
--
-- @function armor:load_armor_inventory
-- @tparam ObjectRef player
-- @treturn bool
armor.load_armor_inventory = function(self, player)
local _, inv = self:get_valid_player(player, "[load_armor_inventory]")
if inv then
@ -639,6 +875,12 @@ armor.load_armor_inventory = function(self, player)
end
end
--- Saves armor inventory.
--
-- Inventory is stored in `PlayerMetaRef` string "3d\_armor\_inventory".
--
-- @function armor:save_armor_inventory
-- @tparam ObjectRef player
armor.save_armor_inventory = function(self, player)
local _, inv = self:get_valid_player(player, "[save_armor_inventory]")
if inv then
@ -648,10 +890,22 @@ armor.save_armor_inventory = function(self, player)
end
end
--- Updates inventory.
--
-- DEPRECATED: Legacy inventory support.
--
-- @function armor:update_inventory
-- @param player
armor.update_inventory = function(self, player)
-- DEPRECATED: Legacy inventory support
end
--- Sets inventory stack.
--
-- @function armor:set_inventory_stack
-- @tparam ObjectRef player
-- @tparam int i Armor inventory index.
-- @tparam ItemStack stack Armor item.
armor.set_inventory_stack = function(self, player, i, stack)
local _, inv = self:get_valid_player(player, "[set_inventory_stack]")
if inv then
@ -660,6 +914,13 @@ armor.set_inventory_stack = function(self, player, i, stack)
end
end
--- Checks for a player that can use armor.
--
-- @function armor:get_valid_player
-- @tparam ObjectRef player
-- @tparam string msg Additional info for log messages.
-- @treturn list Player name & armor inventory.
-- @usage local name, inv = armor:get_valid_player(player, "[equip]")
armor.get_valid_player = function(self, player, msg)
msg = msg or ""
if not player then
@ -681,6 +942,10 @@ armor.get_valid_player = function(self, player, msg)
return name, inv
end
--- Drops armor item at given position.
--
-- @tparam vector pos
-- @tparam ItemStack stack Armor item to be dropped.
armor.drop_armor = function(pos, stack)
local node = minetest.get_node_or_nil(pos)
if node then
@ -694,6 +959,8 @@ end
--- Allows skin mod to be set manually.
--
-- Useful for skin mod forks that do not use the same name.
--
-- @tparam string mod Name of skin mod. Recognized names are "simple\_skins", "u\_skins", & "wardrobe".
armor.set_skin_mod = function(mod)
skin_mod = mod
end

View File

@ -1,6 +1,23 @@
--- Registered armors.
--
-- @topic armor
-- support for i18n
local S = armor.get_translator
--- Admin Helmet
--
-- @helmet 3d_armor:helmet_admin
-- @img 3d_armor_inv_helmet_admin.png
-- @grp armor_head 1
-- @grp armor_heal 100
-- @grp armor_use 0
-- @grp armor_water 1
-- @grp not_in_creative_inventory 1
-- @armorgrp fleshy 100
armor:register_armor("3d_armor:helmet_admin", {
description = S("Admin Helmet"),
inventory_image = "3d_armor_inv_helmet_admin.png",
@ -12,6 +29,15 @@ armor:register_armor("3d_armor:helmet_admin", {
end,
})
--- Admin Chestplate
--
-- @chestplate 3d_armor:chestplate_admin
-- @img 3d_armor_inv_chestplate_admin.png
-- @grp armor_torso 1
-- @grp armor_heal 100
-- @grp armor_use 0
-- @grp not_in_creative_inventory 1
-- @armorgrp fleshy 100
armor:register_armor("3d_armor:chestplate_admin", {
description = S("Admin Chestplate"),
inventory_image = "3d_armor_inv_chestplate_admin.png",
@ -23,6 +49,15 @@ armor:register_armor("3d_armor:chestplate_admin", {
end,
})
--- Admin Leggings
--
-- @leggings 3d_armor:leggings_admin
-- @img 3d_armor_inv_leggings_admin.png
-- @grp armor_legs 1
-- @grp armor_heal 100
-- @grp armor_use 0
-- @grp not_in_creative_inventory 1
-- @armorgrp fleshy 100
armor:register_armor("3d_armor:leggings_admin", {
description = S("Admin Leggings"),
inventory_image = "3d_armor_inv_leggings_admin.png",
@ -34,6 +69,15 @@ armor:register_armor("3d_armor:leggings_admin", {
end,
})
--- Admin Boots
--
-- @boots 3d_armor:boots_admin
-- @img 3d_armor_inv_boots_admin.png
-- @grp armor_feet 1
-- @grp armor_heal 100
-- @grp armor_use 0
-- @grp not_in_creative_inventory 1
-- @armorgrp fleshy 100
armor:register_armor("3d_armor:boots_admin", {
description = S("Admin Boots"),
inventory_image = "3d_armor_inv_boots_admin.png",
@ -50,7 +94,28 @@ minetest.register_alias("adminhelmet", "3d_armor:helmet_admin")
minetest.register_alias("adminchestplate", "3d_armor:chestplate_admin")
minetest.register_alias("adminleggings", "3d_armor:leggings_admin")
--- Wood
--
-- Requires setting `armor_material_wood`.
--
-- @section wood
if armor.materials.wood then
--- Wood Helmet
--
-- @helmet 3d_armor:helmet_wood
-- @img 3d_armor_inv_helmet_wood.png
-- @grp armor_head 1
-- @grp armor_heal 0
-- @grp armor_use 2000
-- @grp flammable 1
-- @armorgrp fleshy 5
-- @damagegrp cracky 3
-- @damagegrp snappy 2
-- @damagegrp choppy 3
-- @damagegrp crumbly 2
-- @damagegrp level 1
armor:register_armor("3d_armor:helmet_wood", {
description = S("Wood Helmet"),
inventory_image = "3d_armor_inv_helmet_wood.png",
@ -58,6 +123,20 @@ if armor.materials.wood then
armor_groups = {fleshy=5},
damage_groups = {cracky=3, snappy=2, choppy=3, crumbly=2, level=1},
})
--- Wood Chestplate
--
-- @chestplate 3d_armor:chestplate_wood
-- @img 3d_armor_inv_chestplate_wood.png
-- @grp armor_torso 1
-- @grp armor_heal 0
-- @grp armor_use 2000
-- @grp flammable 1
-- @armorgrp fleshy 10
-- @damagegrp cracky 3
-- @damagegrp snappy 2
-- @damagegrp choppy 3
-- @damagegrp crumbly 2
-- @damagegrp level 1
armor:register_armor("3d_armor:chestplate_wood", {
description = S("Wood Chestplate"),
inventory_image = "3d_armor_inv_chestplate_wood.png",