Merge branch 'feature/kattarmor'

This helps prevent armor clipping

.gitattributes

@@ -2,3 +2,4 @@
 *.png filter=lfs diff=lfs merge=lfs -text
 *.ogg filter=lfs diff=lfs merge=lfs -text
 * text=auto
+*.zip filter=lfs diff=lfs merge=lfs -text

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "nulllib"]
+	path = nulllib
+	url = https://gitea.protogen.io/nullbite/nulllib-lua.git
+[submodule ".vim/figuradocs"]
+	path = figuradocs
+	url = https://github.com/GrandpaScout/FiguraRewriteVSDocs
+[submodule "kattarmor"]
+	path = kattarmor
+	url = https://github.com/KitCat962/Figura-KattArmor

.luarc-local.json

@@ -0,0 +1,6 @@
+{
+  "workspace": {
+    "ignoreDir": [ ".**", "figuradocs/**"],
+    "ignoreSubmodules": false
+  }
+}

.luarc.json

@@ -0,0 +1,291 @@
+{
+  "workspace": {
+    "library": [
+      ".vscode/docs",
+      "../../avatars/.vscode/docs",
+      "../../../avatars/.vscode/docs",
+      "../../../../avatars/.vscode/docs",
+      "../../../../../avatars/.vscode/docs",
+      "../../../../../../avatars/.vscode/docs"
+    ],
+    "checkThirdParty": false,
+    "userThirdParty": [],
+    "ignoreDir": [
+      ".**",
+      "figuradocs/**"
+    ],
+    "useGitIgnore": true,
+    "ignoreSubmodules": false,
+    "supportScheme": [
+      "file",
+      "untitled",
+      "git"
+    ],
+    "maxPreload": 5000,
+    "preloadFileSize": 500
+  },
+  "runtime": {
+    "version": "Lua 5.2",
+    "builtin": {
+      "basic": "disable",
+      "bit": "disable",
+      "bit32": "enable",
+      "builtin": "enable",
+      "coroutine": "disable",
+      "debug": "disable",
+      "ffi": "disable",
+      "io": "disable",
+      "jit": "disable",
+      "math": "enable",
+      "os": "disable",
+      "package": "disable",
+      "string": "enable",
+      "table": "enable",
+      "table.clear": "disable",
+      "table.new": "disable",
+      "utf8": "disable"
+    },
+    "path": [
+      "?.lua"
+    ],
+    "pathStrict": true,
+    "fileEncoding": "utf8",
+    "meta": "${version} ${language} ${encoding}",
+    "nonstandardSymbol": [],
+    "plugin": "",
+    "pluginArgs": [],
+    "special": {},
+    "unicodeName": false
+  },
+  "completion": {
+    "enable": true,
+    "keywordSnippet": "Both",
+    "callSnippet": "Disable",
+    "showParams": true,
+    "autoRequire": true,
+    "displayContext": 0,
+    "postfix": "@",
+    "requireSeparator": ".",
+    "showWord": "Disable",
+    "workspaceWord": false
+  },
+  "diagnostics": {
+    "enable": true,
+    "workspaceDelay": 5000,
+    "workspaceRate": 25,
+    "severity": {
+      "ambiguity-1": "Warning",
+      "count-down-loop": "Error",
+      "different-requires": "Error",
+      "newfield-call": "Warning",
+      "newline-call": "Warning",
+      "await-in-sync": "Error",
+      "not-yieldable": "Error",
+      "codestyle-check": "Information",
+      "spell-check": "Hint",
+      "duplicate-index": "Warning",
+      "duplicate-set-field": "Warning",
+      "global-in-nil-env": "Error",
+      "lowercase-global": "Information",
+      "undefined-env-child": "Warning",
+      "undefined-global": "Warning",
+      "circle-doc-class": "Error",
+      "doc-field-no-class": "Error",
+      "duplicate-doc-alias": "Warning",
+      "duplicate-doc-field": "Warning",
+      "duplicate-doc-param": "Warning",
+      "undefined-doc-class": "Warning",
+      "undefined-doc-name": "Error",
+      "undefined-doc-param": "Warning",
+      "unknown-cast-variable": "Error",
+      "unknown-diag-code": "Information",
+      "unknown-operator": "Error",
+      "redefined-local": "Warning",
+      "close-non-object": "Error",
+      "deprecated": "Warning",
+      "discard-returns": "Warning",
+      "no-unknown": "Warning",
+      "assign-type-mismatch": "Warning",
+      "cast-local-type": "Warning",
+      "cast-type-mismatch": "Warning",
+      "need-check-nil": "Warning",
+      "param-type-mismatch": "Warning",
+      "return-type-mismatch": "Warning",
+      "undefined-field": "Warning",
+      "missing-parameter": "Error",
+      "missing-return": "Warning",
+      "missing-return-value": "Warning",
+      "redundant-parameter": "Warning",
+      "redundant-return-value": "Warning",
+      "redundant-value": "Warning",
+      "unbalanced-assignments": "Warning",
+      "code-after-break": "Information",
+      "empty-block": "Hint",
+      "redundant-return": "Warning",
+      "trailing-space": "Hint",
+      "unreachable-code": "Information",
+      "unused-function": "Hint",
+      "unused-label": "Hint",
+      "unused-local": "Hint",
+      "unused-vararg": "Hint",
+      "inject-field": "Warning"
+    },
+    "neededFileStatus": {
+      "codestyle-check": "Any"
+    },
+    "disable": [
+      "different-requires",
+      "await-in-sync",
+      "not-yieldable",
+      "codestyle-check",
+      "spell-check",
+      "duplicate-set-field",
+      "close-non-object",
+      "no-unknown",
+      "cast-local-type",
+      "cast-type-mismatch",
+      "need-check-nil",
+      "trailing-space",
+      "inject-field"
+    ],
+    "groupSeverity": {
+      "ambiguity": "Fallback",
+      "await": "Fallback",
+      "codestyle": "Fallback",
+      "duplicate": "Fallback",
+      "global": "Fallback",
+      "luadoc": "Fallback",
+      "redefined": "Fallback",
+      "strict": "Fallback",
+      "strong": "Fallback",
+      "type-check": "Fallback",
+      "unbalanced": "Fallback",
+      "unused": "Fallback"
+    },
+    "groupFileStatus": {
+      "ambiguity": "Fallback",
+      "await": "Fallback",
+      "codestyle": "Fallback",
+      "duplicate": "Fallback",
+      "global": "Fallback",
+      "luadoc": "Fallback",
+      "redefined": "Fallback",
+      "strict": "Fallback",
+      "strong": "Fallback",
+      "type-check": "Fallback",
+      "unbalanced": "Fallback",
+      "unused": "Fallback"
+    },
+    "disableScheme": [],
+    "ignoredFiles": "Opened",
+    "libraryFiles": "Opened",
+    "globals": [],
+    "unusedLocalExclude": []
+  },
+  "format": {
+    "enable": true,
+    "defaultConfig": {
+      "align_call_args": "false",
+      "align_chained_expression_statement": "false",
+      "align_function_define_params": "false",
+      "align_table_field_to_first_field": "false",
+      "call_arg_parentheses": "keep",
+      "class_name_define_style": "pascal_case",
+      "continuation_indent_size": "2",
+      "continuous_assign_statement_align_to_equal_sign": "true",
+      "continuous_assign_table_field_align_to_equal_sign": "true",
+      "detect_end_of_line": "true",
+      "do_statement_no_indent": "false",
+      "enable_check_codestyle": "true",
+      "enable_name_style_check": "true",
+      "end_of_line": "lf",
+      "function_name_define_style": "camel_case",
+      "function_param_name_style": "snake_case",
+      "global_variable_name_define_style": "upper_case",
+      "if_branch_comments_after_block_no_indent": "false",
+      "if_condition_no_continuation_indent": "false",
+      "indent_size": "2",
+      "indent_style": "space",
+      "insert_final_newline": "true",
+      "keep_line_after_do_statement": "keepLine",
+      "keep_line_after_expression_statement": "keepLine",
+      "keep_line_after_for_statement": "keepLine",
+      "keep_line_after_function_define_statement": "keepLine",
+      "keep_line_after_if_statement": "keepLine",
+      "keep_line_after_local_or_assign_statement": "keepLine",
+      "keep_line_after_repeat_statement": "keepLine",
+      "keep_line_after_while_statement": "keepLine",
+      "keep_one_space_between_namedef_and_attribute": "true",
+      "keep_one_space_between_table_and_bracket": "false",
+      "label_no_indent": "false",
+      "local_assign_continuation_align_to_first_expression": "false",
+      "local_function_name_define_style": "camel_case",
+      "local_name_define_style": "snake_case",
+      "long_chain_expression_allow_one_space_after_colon": "false",
+      "max_continuous_line_distance": "0",
+      "max_line_length": "100",
+      "module_name_define_style": "same('this')|same(filename, snake_case|pascal_case|camel_case)",
+      "quote_style": "double",
+      "remove_empty_header_and_footer_lines_in_function": "true",
+      "remove_expression_list_finish_comma": "true",
+      "require_module_name_style": "off",
+      "space_before_function_open_parenthesis": "false",
+      "space_before_open_square_bracket": "false",
+      "space_inside_function_call_parentheses": "false",
+      "space_inside_function_param_list_parentheses": "false",
+      "space_inside_square_brackets": "false",
+      "statement_inline_comment_space": "1",
+      "table_append_expression_no_space": "true",
+      "table_field_name_define_style": "snake_case",
+      "table_seperator_style": "comma",
+      "trailing_table_separator": "smart"
+    }
+  },
+  "hint": {
+    "enable": true,
+    "setType": true,
+    "paramName": "All",
+    "paramType": true,
+    "await": true,
+    "arrayIndex": "Auto",
+    "semicolon": "Disable"
+  },
+  "hover": {
+    "enable": true,
+    "enumsLimit": 100,
+    "expandAlias": false,
+    "previewFields": 100,
+    "viewNumber": true,
+    "viewString": true,
+    "viewStringMax": 1024
+  },
+  "type": {
+    "castNumberToInteger": true,
+    "weakNilCheck": true,
+    "weakUnionCheck": false
+  },
+  "semantic": {
+    "enable": true,
+    "annotation": true,
+    "keyword": false,
+    "variable": true
+  },
+  "signatureHelp": {
+    "enable": true
+  },
+  "spell": {
+    "dict": [
+      "figura"
+    ]
+  },
+  "telemetry": {
+    "enable": false
+  },
+  "window": {
+    "progressBar": true,
+    "statusBar": true
+  },
+  "misc": {
+    "parameters": []
+  }
+}

.vim/coc-settings.json

@@ -1,48 +0,0 @@
-{
-	"Lua": {
-		"diagnostics": {
-			"globals":[
-				"action_wheel",
-				"animation",
-				"armor_model",
-				"camera",
-				"chat",
-				"client",
-				"data",
-				"elytra_model",
-				"events",
-				"first_person_model",
-				"held_item_model",
-				"host",
-				"keybind",
-				"log",
-				"logJson",
-				"logTable",
-				"matrices",
-				"meta",
-				"model",
-				"models",
-				"nameplate",
-				"parrot_model",
-				"particle",
-				"ping",
-				"player",
-				"print",
-				"printJson",
-				"printTable",
-				"renderer",
-				"require",
-				"sound",
-				"spyglass_model",
-				"vanilla_model",
-				"vec",
-				"vectoros",
-				"vectors",
-				"world"
-			],
-			"disable":[
-				"lowercase-global"
-			]
-		}
-	}
-}

.vscode

@@ -0,0 +1 @@
+figuradocs/src/.vscode

README.md

@@ -0,0 +1,9 @@
+# Figura Protogen
+This is my personal avatar for
+[Figura](https://github.com/Kingdom-of-The-Moon/FiguraRewriteRewrite), a
+Minecraft mod that allows for fully customizable avatars. This avatar is a
+vanilla-style avatar with minor enhancements such as emissive textures, a tail,
+and hurt animations.
+
+I originally wrote this avatar for the old version of Figura, and I am
+currently in the process of rewriting it for the current Figura version.

TODO.md

@@ -3,28 +3,60 @@
 ## General
 - [ ] use matrix thing for UVManager (linear algebra is hard)
 - [ ] Add action wheel icons
+- [.] add separate function for updating relevant state variables instead of
+	  sending full state to save bandwidth
+- [ ] add function that gets total health with absoprtion
+- [ ] retractable wipers when it rains
+- [ ] avatar themes?? (AvatarAPI.getColor)
 
 ## Rewrite
-- [ ] fix data api
-- [ ] reimplement avatar settings
-- [ ] fix sound
+- [.] fix data api
+	- [.] ConfigAPI
+- [.] reimplement avatar settings
+- [.] fix sound
 - [ ] fix Blockbench animations
-- [ ] fix or disable custom commands (can probably use `/figura run`)
+- [.] fix or disable custom commands (can probably use `/figura run`)
 - [ ] fix armor, won't re-enable until cleanup
 
 ## Cleanup
-- [ ] potentailly rework shared state variables
+- [ ] Rewrite state management and synchronization code to be less horrifying
+	- [ ] one library for syncing state
+		- [ ] sender side: allow syncing entire state (EXPENSIVE) or just
+			  single values
+			- [ ] internally map variable names to a number deterministically
+				  to reduce unnecessary data transfer
+				  i.e. t["this_is_a_very_long_but_readable_variable_name"]=42 ->
+				  t[6]=42
+			- [.] use a lookup table/array based on order added
+			- [.] user should never see this, variable name to number
+				  translation should be completely transparent
+		- [.] alternatively no manual syncing; state should be implicitly
+			  "shared" and can only be written to/read from via functions to
+			  prevent bad programming from desyncing state
+		- [.] receiver side: register handler function that has access to both
+			  old and new state
+			- [.] receive value -> run handler function -> replace old value
+				  with current
+		- [ ] i think figura has a shared storage thing but it's not real time,
+			  mirror values to this so newly initialized players load with
+			  correct state
+	- [.] one library for storing configs and their default values
+		- [.] this will insert values into the shared state using the other
+			  library
+- [.] potentailly rework shared state variables
 - [ ] rework appropriate action wheel items as ToggleAction instead of ClickAction
+- [.] split off large snippets of code into separate files
+	- [.] PartsManager
+	- [.] UVManager
+	- [.] utility functions
+- [ ] cleanup tick functions, timers
+- [ ] cleanup armor code to make less redundant
+
+# Low priority
 - [ ] reimplement partial vanilla as texture swap
 	- [x] remove partial_vanilla stuff from PartsManager
 	- [ ] fix UVManager with matrices or something
 	- [ ] add swap to skin texture
-- [ ] split off large snippets of code into separate files
-	- [ ] PartsManager
-	- [ ] UVManager
-	- [ ] utility functions
-- [ ] cleanup tick functions, timers
-- [ ] cleanup armor code to make less redundant
 
 # Done
 - [x] fix pings

avatar.code-workspace

@@ -0,0 +1 @@
+figuradocs/src/avatar.code-workspace

docs/kattarmor.md

@@ -0,0 +1,291 @@
+At it's fundamentals, KattArmor changes the texture of specific user defined cubes to different textures depending on the detected material of the worn armor.
+
+# Initializing the KattArmor library
+
+First step is to `require` KattArmor into your own script. KattArmor itself should never be modified.
+Curious about that extra `()`? KattArmor supports multiple Instances of itself. Those will be described later.
+```lua
+local kattArmor=require("KattArmor")()
+```
+
+# Creating Armor cubes
+
+For vanilla armor, a template avatar is provided that contains the correct setup for vanilla armor.
+
+The exact size, position, rotation or armor cubes does not matter. However, the uvs of the cubes do matter. In the template, a texture the same size as the vanilla armor textures is used to align the uvs correctly, and it makes editing the model in blockbench easier. If anything goes wrong, the texture assigned to the cubes in blockbench will be what appears.
+
+To create vanilla-like armor, duplicate the cube you are wrapping the armor around, then inflate it by 0.25, 0.5, 0.75, or 1. Then switch the texture to one that allows you to align the uvs.
+
+# Registering ModelParts to the KattArmor Library
+
+Inside `kattArmor` is `Armor`, which contains `Helmet`, `Chestplate`, `Leggings`, and `Boots`. Calling `addParts` on any of these will add the given ModelParts to that Armor piece. 
+
+The ModelParts will be visible while armor is equipped in those slots, and the ModelParts will have their texture changed based on the material of the equipped armor.
+```lua
+kattArmor.Armor.Helmet
+    :addParts(
+      models.model.Head.Helmet,
+      models.model.Head.HelmetHat
+    )
+kattArmor.Armor.Chestplate
+    :addParts(
+      models.model.Body.Chestplate,
+      models.model.RightArm.RightArmArmor,
+      models.model.LeftArm.LeftArmArmor
+    )
+kattArmor.Armor.Leggings
+    :addParts(
+      models.model.Body.Belt,
+      models.model.RightLeg.RightLegArmor,
+      models.model.LeftLeg.LeftLegArmor
+    )
+kattArmor.Armor.Boots
+    :addParts(
+      models.model.RightLeg.RightBoot,
+      models.model.LeftLeg.LeftBoot
+    )
+```
+
+# Identifying Materials
+
+Materials are gotten from the itemID of armor. `minecraft:leather_helmet` has the material `"leather"` because it follows the format `namespace:material_armor`
+
+This is known as a MaterialID. The vanilla materialIDs are as follows: `"leather"`, `"chainmail"`, `"iron"`, `"golden"`, `"diamond"`, `"netherite"`, and `"turtle"`.
+
+There is the special Material which is the boolean value `true`, which represents having no equipped armor.
+
+# Changing the texture of Materials
+
+Materials are stored in the `Materials` table in `kattArmor`. It contains all Materials, even ones that do not exist.
+
+It contains `Material` objects, which we can call `setTexture` and `setTextureLayer2` on. In vanilla, armor is divided into 2 layers: Layer 1 which contains textures for the helmet, chestplate, and boots, and Layer 2 which contains textures for the leggings.
+
+By default, all materials will attempt to find a texture for itself in the resource location `minecraft:textures/models/armor`. If it cannot find a texture there, the error texture will be shown which is the texture defined in blockbench for the ModelParts.
+
+You can manually set the texture by calling `setTexture` and `setTextureLayer2` on a Material, passing in either a resource location, or a Texture object.
+```lua
+kattArmor.Materials.leather
+    :setTexture(textures["customLeather"])
+    :setTextureLayer2(textures["customLeatherLayer2"])
+```
+
+To access the `true` material, you need to use `[]` indexing instead of `.` indexing, as the value used is a boolean value, not a string.
+`true` was used to prevent any clashing with potential custom materials.
+```lua
+kattArmor.Materials[true]
+    :setVisible(true)
+    :setTexture(textures["armorDefault"])
+    :setTextureLayer2(textures["armorDefaultLayer2"])
+```
+
+# Custom Armor
+
+If your character does not conform to vanilla armor, you do not have to worry about conforming to vanilla's standards at all. 
+
+Your UVs can be whereever you feel is best, your armor cubes can be in whatever shape you feel like, and you can ignore legging's layer2 shenanigans. If you do not use layer2 and do not set any textures to use layer2, be sure to set the layer that the Leggings use to layer2.
+```lua
+kattArmor.Armor.Leggings:setLayer(2)
+```
+
+# Modded armors
+
+Some modded armors will be recognized by the script and have the textures accounted for. However, most mods do not use the vanilla rendering system for armor, meaning KattArmor will not be able to find the textures.
+
+The fix is simple. Figure out the Material of the modded armor, and set the texture to the correct resource location.
+
+For example, the fiery armor from the twilight forrest mod. It's helmet has the itemID `twilightforest:fiery_helmet`, and following the pattern `namespace:material_armor`, `"fiery"` is determined to be the material for this item.
+```lua
+kattArmor.Materials.fiery
+    :setTexture("twilightforest:textures/armor/fiery_1.png")
+    :setTextureLayer2("twilightforest:textures/armor/fiery_2.png")
+```
+
+# Adding Material Specific ModelParts to Materials
+
+If a ModelPart is supposed to render on a specific Material and no-where else, you can call the `addParts` function on a Material object, passing in the Armor part object you want to add the ModelPart to.
+
+As an example, this is how the leather layer is done on the template avatar. It uses this Material Parts system.
+
+Material Parts do not change textures and do not change color. They appear when the Material is worn, and disappear when the Material is not worn. However, they do have enchantment glint if the armor item itself is enchanted.
+```lua
+kattArmor.Materials.leather
+    :addParts(kattArmor.Armor.Helmet,
+      models.model.Head.HelmetLeather,
+      models.model.Head.HelmetHatLeather
+    )
+    :addParts(kattArmor.Armor.Chestplate,
+      models.model.Body.ChestplateLeather,
+      models.model.RightArm.RightArmArmorLeather,
+      models.model.LeftArm.LeftArmArmorLeather
+    )
+    :addParts(kattArmor.Armor.Leggings,
+      models.model.Body.BeltLeather,
+      models.model.RightLeg.RightLegLeather,
+      models.model.LeftLeg.LeftLegLeather
+    )
+    :addParts(kattArmor.Armor.Boots,
+      models.model.RightLeg.RightBootLeather,
+      models.model.LeftLeg.LeftBootLeather
+    )
+```
+
+# Custom Materials
+
+You can define custom materials with KattArmor, allowing for unique textures for unique situations.
+
+For an example, we will be defining a custom `"philza"` material.
+
+First step is to define the custom material. This is done by indexing `Materials` like you would for materials that you know exist.
+
+Indexing `Materials` will create a new Material object if the Material didnt exist previously. Plot twist: Zero materials exist when KattArmor is initialized. They are generated when you wear armor for the first time, because KattArmor itself indexes Materials.
+
+We then call `setTexture` and `setTextureLayer2` on the Material to define the textures to use when we use the material.
+
+```lua
+kattArmor.Materials.philza
+    :setTexture(textures["model.philzaLayer1"])
+    :setTextureLayer2(textures["model.philzaLayer2"])
+```
+
+We then need to define when the script will use the custom material. This is done via the `registerOnChange` function.
+
+It takes in a function that should return a string or nil. When the function returns a string, KattArmor will use that as the Material. When it is nil, KattArmor will parse the MaterialID from the itemID as normal.
+
+```lua
+kattArmor.registerOnChange(function (partID, item)
+  -- When the name of the item is "Philza Helmet" on the helmet slot, return "philza".
+  -- The compared name is "Philza Chestplate", "Philza Leggings", and "Philza Boots" for the other armor parts
+  -- Functions return nil when no return is defined.
+  if item:getName() == ("Philza " .. partID) then
+    return "philza"
+  end
+end)
+```
+
+And thats it. KattArmor will now use the `"philza"` material when the armor item's name is correct.
+
+# Armor Trims
+
+KattArmor supports armor trims.
+
+Setting them up requires a bit of work. First of all, duplicate all of your armor cubes and give the duplicate a unique name. Do not touch the scale, leave it the same as the original cube.
+
+You probably want to take the time to make a dummy trim texture in blockbench so that your bbmodel stays readable. A dummy texture for the vanilla armor is available in the template. This is not required by KattArmor and you can leave the trim cube's texture as whatever it was set to before. 
+
+Then in KattArmor, register the new cubes as Trim Parts via the `addTrimParts` function.
+```lua
+kattArmor.Armor.Chestplate:addTrimParts(
+      models.model.Body.ChestplateTrim,
+      models.model.RightArm.RightArmArmorTrim,
+      models.model.LeftArm.LeftArmArmorTrim
+    )
+```
+
+Now the new cubes will use the vanilla trim textures.
+
+# Custom Armor Trims
+
+Fuck custom armor trims.
+
+KattArmor does not support custom Armor Trims in the same format as vanilla, where a source trim texture is provided and using some palate textures, extra textures are dynamically generated.
+
+No. In KattArmor, you have 4 choices for Custom Armor Trims:
+* Dont at all
+* Dont, instead using the Custom Material system
+  * for when you have one specific material-pattern combo that you care about and will ignore the rest
+* Set a single texture per trim pattern and allow KattArmor to setColor the cube based on the trim material
+  * for when you have a large project and want everything perfect, within reason
+* Set a texture for each material-pattern combo, preferably using a texture generation system
+  * For when you want to absolutely demolish your instruction count or file size. Texture manipulation is *very* expensive, which is why KattArmor does not care to do it.
+
+Info for 2:
+    Trim data is stored in nbt, and can be accessed via `item.tag.Trim.pattern` and `item.tag.Trim.material`. Dont forget to do a nil check for `item.tag.Trim`. 
+
+Info for 3:
+    use the `setTexture` and `setTextureLayer2` function on a TrimPattern object.
+```lua
+    kattArmor.TrimPatterns.wild
+            :setTexture(textures["model.sentry"])
+            :setTextureLayer2(textures["model.sentry_leggings"])
+```
+    The textures should be a gray-scale image so that ModelPart:setColor can do it's work.
+
+    If you do not like the colors that I defined for each material, you can set them yourself via the `setColor` function on a TrimMaterial object.
+```lua
+    -- setColor expects a Vector3. I myself was lazy and used hex code number literals converted to Vec3 rbg via the `intToRGB` function.
+    kattArmor.TrimMaterials.amethyst:setColor(vectors.intToRGB(0x9a5cc6))
+```
+
+Info for 4:
+    you can use the `setTexture` and `setTextureLayer2` functions on a TrimMaterial object to completely override the texture used by a material-pattern combo.
+```lua
+    kattArmor.TrimMaterials.lapis:setTexture("ward", textures["model.sentry"])
+```
+    This texture is expected to be full color. KattArmor will apply no colors or other modifiers to the texture.
+
+    As stated before, this is expected to be used by your own instruction burning texture generating script, or by burning file size by manually creating textures in Blockbench for each material-pattern combo
+
+    I might make a texture generating script at some point, just so I can say that KattArmor *can* do it. Or I might not. Probably wont. Regardless, advanced texture manipulation will never be a base KattArmor feature due to it's expensive nature.
+
+# KattArmor Instances
+
+You heard at the top. KattArmor has instances. What does that mean?
+
+`require` returns a function that when called, creates a new KattArmor instance. Every instance has it's own armor cubes, materials, textures, trim data. Basically, its a duplicated KattArmor script file. 
+
+This allows asset creators to create assets that depend on KattArmor, without denying the user the ability to use KattArmor.
+
+Before, each material had a single texture per layer. This meant that if you wanted to merge 2 projects that used KattArmor, you would either need to have a duplicate KattArmor script file, or merge the 2 projects so that the custom textures and uvs worked properly with each other.
+
+You can see how this can be a pain for users that don't even know what they are doing.
+
+There are some things that are shared globally with all instances.
+* The `forceUpdate` function found in all instances will cause *all* instances to update when called.
+* All onChange functions get added to a global list, meaning all instances will obey the material changing brought by onChange.
+  * when multiple onChange functions are registered, the first truthy value will be used and all functions afterwords will not be called.
+* `ArmorPart_SlotID_Map` and `SlotID_ArmorPart_Map`, which are static utility tables for mapping ArmorPartIDs with Slot numbers.
+
+One thing that asset creators *do* have to worry about is giving users access to your KattArmor instance so they can add textures for their custom materials or modded armors. That is, unless you want the users to edit your script, making it difficult for users to update to newer versions of the asset.
+
+# Custom Custom Custom Custom Custom
+
+Not enough for you? There is `onRender` event which gets called after KattArmor has finished all of it's processing. In it's arguments is every single variable that KattArmor uses for determining how to render armor/trims.
+```lua
+kattArmor.registerOnRender(function (materialID, partID, item, visible, renderType, color, texture, textureType, texture_e, textureType_e, damageOverlay, trim, trimPattern, trimMaterial, trimTexture, trimTextureType, trimColor, trimUV)
+  print("oh god thats alot")
+end)
+```
+yea its a bit of a joke. The most useful things are the first 3 arguments anyways, but who knows. Someone might find it useful. For the record, you do not need to define every argument. You can ignore the ones you do not use, using `_` to pad out the positions.
+```lua
+kattArmor.registerOnRender(function (materialID, partID, item)
+  print("ok this is more managable")
+end)
+kattArmor.registerOnRender(function (materialID, partID, item, _, _, _, _, _, _, _, _, trim, trimPattern, trimMaterial)
+  print("I just want trim data for `x` reason")
+end)
+```
+
+# Armor doesn't update when I do stuff?
+
+KattArmor only updates Armor Parts when the equipped item changes. 
+
+If you have additional code executing that onChange needs to watch for, you have to call `forceUpdate` when the variables change so that KattArmor knows to update the visuals.
+
+Additionally, KattArmor functions do not automatically update the armor visuals, meaning you have to call `forceUpdate` when you modify Material textures or add more parts during tick, neither of which you should be doing anyways. Material textures should instead be handled via custom materials, and adding parts during tick should never be done in the first place.
+
+```lua
+local animatedArmor=0
+function events.tick()
+    if world.getTime()%4==0 then
+        animatedArmor=(animatedArmor+1)%4
+        kattArmor.forceUpdate()
+    end
+end
+
+kattArmor.registerOnChange(function(partID, item)
+    if item.id == "minecraft:netherite_"..partID:lower() then
+        -- returns either "netherite-0", "netherite-1", "netherite-2", "netherite-3", which are custom materials.
+        return "netherite-"..animatedArmor
+    end
+end)
+```

figuradocs

@@ -0,0 +1 @@
+Subproject commit 725e04de1f0568cbeddf766b42edb6cf2b899316

kattarmor

@@ -0,0 +1 @@
+Subproject commit a243caa9d8f4a5369e45f16c566bfcc145782b0f

nulllib

@@ -0,0 +1 @@
+Subproject commit 618c082c0f5809bafc9a43a1e6ce81d2897a5333

update-docs.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env nix-shell
+#!nix-shell -i bash -p jq hjson stow
+
+set -Eeuxo pipefail
+
+cd "$(dirname "$0")"
+
+(
+	cd figuradocs
+	git checkout latest
+	git fetch --all
+	git pull
+	stow src --ignore='^\.luarc\.json$'
+)
+
+
+
+< figuradocs/src/.luarc.json hjson -c | jq -s '.[0] * .[1]' - ./.luarc-local.json > .luarc.json
+
+git add .luarc.json
+git status