Field Checks
A field check examines a field's value and returns the messages displayed beside the field's name (see Field Messages). A field's checks are listed in its schema, under checks (see Line Schemas).
Most messages need no code: a few general checks, configured in the schema, cover them.
Kinds of Messages
| Severity | Use |
error | The value is incorrect. Write a brief text that only states what is incorrect: "Not a whole number." |
warning | The value is correct, but probably not what was meant. |
notice | A reminder of what a correct value does, where it could be read two ways. |
"checks": [ { "check": "required" } ]
number
An error when the value isn't a number.
"checks": [ { "check": "number", "whole": true, "min": 1 } ]
| Setting | Description |
| whole | true: the number must be whole. |
| min | The lowest number accepted. |
| values | Other values accepted, such as ["Reset"]. |
| allow_empty | false: an empty value is an error too. |
| text | The error's text. |
"checks": [ { "check": "one_of", "values": ["Last", "Tags", "All"], "text": "Not a mode." } ]
in_list
A warning when the value isn't in the field's own dropdown list. No message is displayed while the list is empty, since the list isn't known.
"checks": [ { "check": "in_list", "text": "No item ‹name› in the game." } ]
when
A message of your own, displayed while a rule holds. The rule is written like a visible_when rule. A rule with no field tests the field's own value.
"checks": [
{ "check": "when", "severity": "warning", "rule": { "equals": "0" },
"text": "Gives nothing." },
{ "check": "when", "severity": "notice",
"rule": { "all": [ { "greater_than": 99 }, { "field": "Item", "equals": "Key" } ] },
"text": "That's a lot of keys." }
]
Where Checks Go
| Key | Examines |
| checks, on a field | The field's value. Displayed beside the field's name. |
| checks, on a list or map | The list as a whole. Displayed beside its title. |
| entry_checks, on a list or map | The name of each entry. Displayed beside that name. |
‹value› is replaced by the value checked, and ‹entry› by the name of the entry the field is in.
What Is Skipped
Before a field's checks run:
- A value that starts with the project's expression symbol is skipped: it's only known when the game runs the Line. Add
"expressions": true to a check to run it anyway. null in a field whose default is "null" is skipped.- A field hidden by its visible_when rule isn't checked.
A Check Script
For a check that the general ones can't perform, write a script. Place it in a mod's Field_Checks folder. Its file name is the check's name.
Mods/My_Game/Field_Checks/item_name.gd:
extends RefCounted
func check(config: Dictionary, context: CandyCheckContext) -> Array:
var item := context.value.strip_edges()
if item == "" or item.left(1) == item.left(1).to_upper():
return []
return [CandyChecks.message(CandyChecks.WARNING, "Item names start with a capital.")]
In a schema:
"checks": [ { "check": "item_name" } ]
config is the check's dictionary in the schema, so a schema can pass it settings.context.value is the value being checked.- The function returns a list of messages, each created with
CandyChecks.message(). An empty list displays nothing.
A script with the file name of a built-in one replaces it.
Write a check that compares a value with your project's data so that it returns nothing while that data isn't known, rather than reporting every value as missing.
