diff --git a/doc/en/scripting.md b/doc/en/scripting.md index cf4d0bed..7f5f3dda 100644 --- a/doc/en/scripting.md +++ b/doc/en/scripting.md @@ -21,6 +21,7 @@ Subsections: - [pack](scripting/builtins/libpack.md) - [player](scripting/builtins/libplayer.md) - [quat](scripting/builtins/libquat.md) + - [rules](scripting/builtins/librules.md) - [time](scripting/builtins/libtime.md) - [utf8](scripting/builtins/libutf8.md) - [vec2, vec3, vec4](scripting/builtins/libvecn.md) diff --git a/doc/en/scripting/builtins/librules.md b/doc/en/scripting/builtins/librules.md new file mode 100644 index 00000000..c4b1c377 --- /dev/null +++ b/doc/en/scripting/builtins/librules.md @@ -0,0 +1,71 @@ +# *rules* library + +```lua +rules.create( + -- rule name + name: str, + -- default value + default: bool, + -- value change handler function + [optional] handler: function +) -> int +``` + +Creates a rule. If a handler is specified, returns the id for deletion. + +> [!NOTE] +> A rule is created by calling rules.create with a default value. +> Rules that have not been created can be used, but resetting via rules.reset will result in setting the value to nil. + +```lua + rules.listen( + -- rule name + name: str, + -- value change handler function + handler: function +) -> int +``` + +Adds a rule value change handler. + +Returns the id for deletion. +Also allows subscribing to a rule before it is created. + +```lua +rules.unlisten(name: str, id: int) +``` + +Removes a rule handler by id, if it exists. + +```lua +rules.get(name: str) -> bool | nil +``` + +Returns the rule value, or nil if it has not been created yet. + +```lua +rules.set(name: str, value: bool) +``` + +Sets the rule value by calling handlers. Can be used before +creating a rule. + +```lua +rules.reset(name: str) +``` + +Resets the rule value to the default value. + +## Standard Rules + +| Name | Description | Default | +| ---------------------- | ----------------------------------------------------------- | ------- | +| cheat-commands | Allow commands whose names are in the console.cheats array. | true | +| allow-content-access | Allow the content access panel. | true | +| allow-flight | Allow flight. | true | +| allow-noclip | Allow noclip. | true | +| allow-attack | Allow attacking entities. | true | +| allow-destroy | Allow block destruction. | true | +| allow-cheat-movement | Allow special quick movement keys. | true | +| allow-debug-cheats | Allow cheat controls in the debug panel. | true | +| allow-fast-interaction | Allow fast interaction. | true |