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. 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. 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. You may, additionally, supply a JSON compound
  specifying a Choice directly, instead of an identifier to one. In that case,
  the choice will not be presented to the user, and instead always take its
  default value, providing a constant argument. 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.

* 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:number: Makes user input into a (long) number.

* chitinous_ties:natural: Same as number, but requires input be one or above,
  and subtracts one from it. Useful for zero-indexed values.

* chitinous_ties:rational: Makes user input into a (double) number.

* 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 item predicate conditions.
  Returns the json/string representation of a UUID.

* 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.

* chitinous_ties:registry: Requires at least two choices. The first choice
  denotes the registry name (eg minecraft:block, minecraft:item,
  minecraft:entity_type, etc) and the second choice the actual entry in the
  registry (or, alternatively, a tag beginning with #). In its most useful case,
  supply the first choice through a hidden choice in order to check that the
  second choice is a valid block, item, entity, etc. All choices after the
  second denote tags to additionally verify that the second choice falls under.
  Returns a string.

* 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 entered, space-deliminated.

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

* chitinous_ties:enchantment: Returns the corresponding enchantment level
  numeral.

* chitinous_ties:potion: Returns the corresponding potion potency numeral.

* chitinous_ties:villager: Returns the corresponding villager profession level
  name.

* 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.

* 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!
* component: The item component to check.
* test: optional. The data to test against, as SNBT. Best generated through law
  templates using the nbt format. Defaults to passing every component.
* 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.
