Datapack Format
===============
The various tasks available to a drafter (internally called laws) and the
form-fillable text boxes to configure them (choices) are both completely
data-driven.

Feel free to look at the provided datapack jsons as examples.



data/NAMESPACE/chitinous_ties/law
---------------------------------
These are the actual tasks that players can pick out and add to contracts.

* icon: required. An item (or block) to show to the drafter in the editing
  window as a representative icon.

* bindings: required. A list of identifiers for available Bindings. Each Binding
  namespace:path shown here defines a variable NAMESPACE:PATH for use in the
  count and template fields.

* count: optional. A number denoting how many times this law's criterion must
  be completed. Must be over 0. May use variable substitutions in the same
  format as the template field, in which case you must provide a binding format
  with the chitinous_ties:number serializer.

* template: required. An advancement criterion defining this law. Each object
  and subobject of this field are checked for a "format" field, with three
  possible options:
  * json: The object containing this field will be replaced by a string
    containing the json representation of this object.
  * nbt: The object containing this field will be replaced by a string
    containing the nbt representation of this object. If you need to use
    nbt objects not properly representable in datapack json, that is to say,
    numbers of specific sizes, use a string consisting of the number followed by
    the proper nbt suffix. For example, for the byte 3, use "3b".
  * lhs: All siblings of this field will have their names scanned for bindings.
    Any matches corresponding to string (post-sanitization) will be replaced
    with the contents of the string. Useful for when key needs to be set by a
    player instead of a value.
  * any binding: The name of any available binding can be used as a format,
    replacing the object containing this field with the result of the binding
    passed through its sanitizer. If empty (usually as a result of all
    user-suppliable choices for the binding being empty), this object (and all
    thereafter empty parents) will be removed.



data/NAMESPACE/chitinous_ties/binding
-------------------------------------
These are variable bindings within laws, as a middle-step that can process
multiple choices together.

* sanitizer: required. The user-entered values of the choices listed below will
  be passed to the sanitizer in order to construct the variable substitution
  this binding defines. Sanitizers may induce additional options within this
  binding structure. See below for a list of options.

* namer: required. The user-entered values of the choices listed below will be
  passed to the namer in order to construct a localized text to be passed to the
  contract text of laws that use this binding. Namers may induce additional
  options within this binding structure. See below for a list of options.

* choices: optional. A list of identifiers to drafter-editable choices for this
  binding, serving as arguments to the sanitizer and namer. If choices are
  reused across bindings in the same law, they will all refer to the same
  drafter-provided value. Empty if not provided.

* require: optional. A list of identifiers to choices. If this binding's choices
  aren't blank, it will check to make sure these choices aren't blank as well.



data/NAMESPACE/chitinous_ties/choice
------------------------------------
These are the player-fillable text boxes.

* type: optional. Type of suggestion, as one of the following:
  - registry: The suggest field is taken as the name of a registry. Default.

  - synced: As registry, but will manually sync the registry's contents. Use for
    dynamic non-synced registries like dimensions or structures.

  - statistic: The suggest field is taken as the identifier of a choice, which
    will be read for a statistic type. This will then provide the corresponding
    registry.

* suggest: optional. If provided, provides suggestions to the user according to
  the provided registry id.

* value: optional. If provided, used as the default value for this Choice. If
  this Choice is not user-visible, then it is used as a constant value.



data/NAMESPACE/chitinous_ties/localizer
---------------------------------------
These are used solely due to the messy, non-standard system of minecraft
translation keys. Each entry NAMESPACE:PATH effects one registry of the same
identifier. The localizer then overrides the default localization key Chitinous
Ties generates for the registry's entries.

* entry: required. The localization key format to use, as a string. "%namespace"
  will be replaced by the registry entry namespace, and "%path" with its path.

* fallback: optional. A fallback to use in case entry fails, in the same format
  as entry.

* tag: optional. The localization key format to use for tags, in the same format
  as entry. If not provided, it will default to a generated EMI-style tag
  localization.

* slashed: optional. Boolean defaulting to false. If false, all slashes in paths
  will be replaced with periods.



Sanitizers
----------
* chitinous_ties:string: Makes user input into a string.

* chitinous_ties:boolean: Makes user input into a boolean. Accepts both
  true/false and yes/no.

* chitinous_ties:identifier: Makes sure user input is a valid identifier and
  returns a string.

* chitinous_ties:text: Returns a string containing a text component. Useful for
  entity CustomNames and other spots where text components are used.

* chitinous_ties:player: Interprets user input as a player name, and finds the
  corresponding player UUID. Primarily useful for entity predicate conditions.
  Returns a list containing the nbt/int-array representation of a UUID.

* chitinous_ties:contract: Replaces user input with the Contract's UUID.
  Primarily useful for checking an item's draft component. Returns the
  NBT/int-array representation of a UUID..

* chitinous_ties:number: Makes user input into a number. Induces the following
  fields in the binding structure this is used within:
  - size: optional. What java/NBT type to use for this number; primarily useful
    when this binding is going to be used in NBT. Defaults to long.
  - offset: optional. A number to add to the user-entered value. This is done
    before all other checks.
  - min: optional. Minimum allowed value, inclusive.
  - max: optional. Maximum allowed value, inclusive.

* chitinous_ties:coordinate: Requires three or six choices. For three, provides
  a coordinate in { "x": x, "y": y, "z": z} format. When given six choices,
  will output a similar object, but each coordinate being specified as
  {"min": x, "max": dx}, in order to support areas in location_check predicates.
  Choices, in this case, are ordered x, dx, y, dy, z, dz, each pair signifying
  starting and ending coordinates, respectively. Induces the following fields in
  the binding structure this is used within:
  - offset: optional. A number to offset the maximum values for each coordinate
    range by. Defaults to 1 in order to provide the intuition of block
    coordinates. Note that predicates tend to pass block positions as their
    center, so a block at (0,0,0) is actually (0.5,0.5,0.5), which this default
    is meant to support as well.

* chitinous_ties:registry: Interprets user input as either a registry name or,
  when prefixed with a #, a registry tag. Returns a string. Induces the
  following fields in the binding structure this is used within:
  - registry: required. The registry name (eg minecraft:block, minecraft:item,
    minecraft:entity_type, etc).
  - tags: optional. A list of tags to verify the choice resides within. Works
    even when the user inputs a tag.

* chitinous_ties:statistic: Given a statistic type and a corresponding
  statistic as choices, provides the signing player's current value for that
  statistic. Primarily useful in combination with the chitinous_ties:statistic
  advancement criterion. Returns an (int) number.



Namers
------
* chitinous_ties:none: Just returns an empty string. Use this for bindings whose
  value don't need to be relayed to the signer.

* chitinous_ties:literal: Returns all choices as-is, space-deliminated.

* chitinous_ties:player: Like literal, but for player names. Provides Inline
  mod compat.

* chitinous_ties:numeral: Use in combination with the chitinous_ties:number
  serializer when the user is inputting a numeral, such as enchantment level or
  potion potency. Formats user input according to the following induced fields
  in the binding structure:
  - key: required. Translation key, with a "%s" to get replaced with the number
    inputted (post-offset).
  - fallback: optional. Translation key for fallback text when either no
    localization under key is found, or input isn't a number. The translation is
    passed the entered value. If not provided, just passes user input verbatim.
  - offset: optional. Same as in the chitinous_ties:number sanitizer.
  - overrides: optional. A map from translation keys to translation keys as
    overrides to the default procedure. Useful to specify numerals when vanilla
    just omits them.

* chitinous_ties:coordinate: Use in combination with the
  chitinous_ties:coordinate sanitizer. Formats the coords nicely.

* chitinous_ties:registry: Use in combination with the chitinous_ties:registry
  sanitizer. Tries to output a localized name for the given registry entry.
  Useful, for example, to provide the localized name of an item, block, or
  entity. Induces the following fields in the binding structure this is used
  within:
  - registry: required. As in the chitinous_ties:registry sanitizer.

* chitinous_ties:statistic: Use in combination with the chitinous_ties:statistic
  sanitizer. Tries to output a localized phrase representing the given statistic
  type and statistic.







Localization
============
Translation keys for laws and choices are in the format of law.NAMESPACE.PATH
and choice.NAMESPACE.PATH, respectively.

Law
---
Uses translation keys law.NAMESPACE.PATH, law.NAMESPACE.PATH.tooltip, and
law.NAMESPACE.PATH.contract, used for the law's name in the editor, its tooltip
in the editor, and the text that shows up on the contract, respectively.

The contract text is provided the value of each Binding (passed through their
Namers) in order as arguments, usable either by %s or %INDEX$s tokens in the
translation, or through owo-lib's
[rich translation system](https://docs.wispforest.io/owo/rich-translations/).

Binding
-------
Uses binding.NAMESPACE.PATH.default when no user-suppliable choices have been
provided. Otherwise, wraps the namer's result using binding.NAMESPACE.PATH.

Choice
------
Uses translation keys choice.NAMESPACE.PATH and choice.NAMESPACE.tooltip, both
used solely within the editor. Don't provide these in cases where the choice is
embedded into a binding; those aren't user-visible and don't have a namespace or
PATH anyway.







Advancement Criteria
====================
Chitinous Ties adds various advancement criteria, in order to enable additional
functionality for laws.

chitinous_ties:statistic
------------------------
Checks whether the player has increased a statistic by a given amount. Requires
four values to be provided as conditions:
* type: The statistic type's identifier.
* stat: The statistic's identifier.
* base: The player's value of the statistic on acquiring this condition. This
  should be filled in via the chitinous_ties:statistic sanitizer.
* offset: How much the statistic must be increased by.



Loot Context Conditions
=======================
These are predicates as used in Advancement conditions (and loot tables).

chitinous_ties:coplayer
---------------------
Akin to entity_properties but acting on another player.
* player: UUID of the player to check against, in either string or four-int-list
  format. If not provided, will just use the current player.
* predicate: Same as entity_properties. Optional, in which case player is
  checked only for being online.



Entity Subpredicates
====================
These may be used in the type_specific field in the entity_properties loot
context condition.

chitinous_ties:attribute
------------------------
Checks for an entity's attribute values.
* attributes: An attribute id, a list of multiple, or a #-prefixed tag.
  Optional, in which case this subpredicate just passes.
* range: Either a range of attribute values (as an object with min and max
  elements) or a single value to test against. Optional, in which case just
  checks for the entity possessing the attribute.



Item Subpredicates
==================
Chitinous Ties adds two item subpredicates.

chitinous_ties:component
------------------------
Partial match any component as NBT! Is a list of objects with the following
tags:
* component: The item component to check.
* test: optional. The data to check the component's NBT representation against.
  If not provided, will only check whether the component is present.
* ordered: optional. Whether lists should be checked for order as well. Does NOT
  apply to arrays, such as UUIDs, which are always checked for order. Defaults
  to false.



Statistics
==========
Chitinous Ties, similarily, adds some of its own statistics.
* chitinous_ties:drafted: Contracts drafted.
* chitinous_ties:signed: Contracts signed.
* chitinous_ties:verified: Contracts verified.
* chitinous_ties:completed: Contracts completed.
