docs: construct CLI & API documentation

2026-06-05 17:52:06 +02:00
parent 059d7b5c03
commit 5256cda6b6
5 changed files with 297 additions and 1 deletions
@@ -0,0 +1,149 @@
+# CLI Reference
+
+All commands are prefixed with `construct:`. Arguments in angle brackets (`<arg>`) are required, while those in square brackets (`[arg]`) are optional. Assume commands can be run from any source (player, entity, block, or server) unless otherwise noted.
+
+## Instance Management
+ 
+### `construct:create <instanceName> <structureId>`
+Create a new instance bound to a structure.
+ 
+| Argument | Description |
+|---|---|
+| `<instanceName>` | Unique name for this instance. |
+| `<structureId>` | ID of a structure saved in the world (without the `mystructure:` prefix). |
+ 
+> Corresponds to the "create new instance" flow in the main menu. Errors if `instanceName` is already taken or `structureId` does not exist.
+ 
+### `construct:delete <instanceName>`
+Permanently delete an instance.
+ 
+| Argument | Description |
+|---|---|
+| `<instanceName>` | Name of the instance to delete. |
+ 
+> Calls `structureCollection.delete()`. Also disables the instance and clears its saved dynamic properties before removal.
+ 
+### `construct:rename <instanceName> <newInstanceName>`
+Rename an existing instance.
+ 
+| Argument | Description |
+|---|---|
+| `<instanceName>` | Current instance name. |
+| `<newInstanceName>` | Desired new name. Errors if already in use. |
+ 
+### `construct:list`
+List all registered instances and their status.
+ 
+> Prints each instance name, its bound structure ID, enabled/disabled state, and placed location (if any). Useful for scripting and quick inspection without opening the GUI.
+ 
+## Placement & Movement
+ 
+### `construct:place <instanceName> <x y z>`
+Enable and place an instance at a location.
+ 
+| Argument | Description |
+|---|---|
+| `<instanceName>` | Instance to place. |
+| `<x y z>` | World coordinates. Errors if omitted. Supports tilde (`~`) notation. |
+ 
+> Equivalent to the "Place" button in the instance menu — enables the instance and calls `move()` in one step. If the instance already has a location, this is a move, not a fresh place.
+ 
+### `construct:move <instanceName> [x y z]`
+Reposition a placed instance without toggling its enabled state.
+ 
+| Argument | Description |
+|---|---|
+| `<instanceName>` | Name of a placed instance. |
+| `<x y z>` | Target world coordinates. |
+
+## Enable / Disable
+ 
+### `construct:enable <instanceName>`
+Enable a placed instance.
+ 
+> Requires the instance to have a saved location. Refreshes the outliner, verifier, and materials cache.
+ 
+### `construct:disable <instanceName>`
+Disable an active instance.
+ 
+> Tears down outliner rendering and pauses the verifier. The instance retains its saved location and can be re-enabled.
+ 
+## Layer Control
+ 
+### `construct:layer <instanceName> <layer>`
+Set the active layer of an instance.
+ 
+| Argument | Description |
+|---|---|
+| `<instanceName>` | Name of the instance. |
+| `<layer>` | Integer layer index. `0` = whole structure (no layer selected). Valid range: `0` to `structure.height`. |
+ 
+> Errors if `layer` is out of bounds. Only meaningful for structures with height > 1.
+ 
+### `construct:nextlayer <instanceName>`
+Step the layer up by one (wraps from max back to `0`).
+ 
+> Mirrors the "Next layer" button. Wrapping from max → `0` restores the whole-structure view.
+ 
+### `construct:prevlayer <instanceName>`
+Step the layer down by one (wraps from `0` back to max).
+ 
+> Mirrors the "Previous layer" button.
+
+## Settings
+ 
+### `construct:verifier <instanceName> true|false`
+Toggle the structure verifier for an instance.
+ 
+| Argument | Description |
+|---|---|
+| `<instanceName>` | Name of the instance. |
+| `true\|false` | Whether to run the verifier. Corresponds to the "validation" toggle in Settings. |
+ 
+### `construct:option <optionId> true|false`
+Enable or disable a per-player builder option. Must be run as a player source.
+ 
+| Argument | Description |
+|---|---|
+| `<optionId>` | One of: `easyPlace`, `fastEasyPlace`, `materialGrabber`. |
+| `true\|false` | Desired state. Runs the option's enable/disable callback (gives or removes the action item). |
+ 
+> Replaces the toggles in the Builder Options form. State is saved per-player via dynamic properties.
+
+## Information
+ 
+### `construct:info <instanceName>`
+Print instance details to chat.
+ 
+> Outputs: bound structure ID, enabled state, placed location and dimension, current layer, verifier enabled, structure bounds (min/max). Equivalent to the data shown in the instance menu body.
+ 
+### `construct:stats <instanceName>`
+Run the structure verifier and print statistics.
+ 
+> Triggers a standalone `StructureVerifier` pass (same as the "Statistics" button) and sends the result to chat. Errors if a verifier is already running on this instance.
+ 
+### `construct:materials <instanceName> [missing]`
+Print the material list for an instance.
+ 
+| Argument | Description |
+|---|---|
+| `<instanceName>` | Name of the instance. |
+| `missing` | When present, show only materials the player does not have in their inventory (mirrors the "missing only" toggle). Can only be used by a player source. |
+ 
+> Respects the active layer: if a layer is set, only that layer's material counts are shown.
+
+## Utility
+ 
+### `construct:item`
+Give yourself the Construct menu item.
+ 
+> Already implemented as a native custom command. Needs to be refactored to fit the new command pipeline.
+ 
+### `construct:tag <instanceName>`
+Rename the held Construct item to an instance name for quick-open. Errors if the item is not a construct item or if the instance name is not registered.
+ 
+| Argument | Description |
+|---|---|
+| `<instanceName>` | Instance name to embed in the item's `nameTag`. Using the item in-world will jump straight to that instance's menu. |
+ 
+> The item-use handler in `construct.js` already checks `itemStack.nameTag` against known instance names; this command just makes it easy to tag an item without renaming it in an anvil.