Sea-of-Stars-studio/Construct
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: construct CLI & API documentation

Browse Source
This commit is contained in:
ForestOfLight
2026-06-05 17:52:06 +02:00
Unverified
parent 059d7b5c03
commit 5256cda6b6
5 changed files with 297 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+16
View File
@@ -0,0 +1,16 @@
# API Reference
This section documents the public API of Construct, including all endpoints that can be accessed by other addons or scripts. This is intended for advanced users who want to extend or integrate with Construct beyond the provided CLI commands and GUI features.
# API Overview
Construct's API can be accessed via the [AddonAPIKit](https://github.com/ForestOflight/addonapikit) package. Instructions for importing the API into your project can be found in the AddonAPIKit documentation.
You'll need to include Construct's Data Model definitions in your project to work with the API effectively. These data models define the structure of the data passed to and from the API endpoints. They can be found at [`packs/BP/scripts/API/ConstructAPIModel.js`](https://github.com/ForestOfLight/Construct/blob/main/packs/BP/scripts/API/ConstructAPIModel.js). Copy the file into your project and import the models as needed.
Feedback on the Construct API is very welcome! If you have suggestions for new endpoints, improvements to existing ones, or any other feedback, please open a GitHub issue.
Detailed information about the available API endpoints can be found in the following pages:
- [Endpoints](./API/Endpoints.md)
- [Data Models](./API/DataModels.md)
docs/API/DataModels.md
+56
View File
@@ -0,0 +1,56 @@
# Data Models
The following data models are used to represent the format of the data passed by the API endpoints. More information about the API endpoints can be found in the [Endpoints](./Endpoints.md) page.
You'll need to include Construct's Data Model definitions in your project to work with the API effectively. These data models define the structure of the data passed to and from the API endpoints. They can be found at [`packs/BP/scripts/API/ConstructAPIModel.js`](https://github.com/ForestOfLight/Construct/blob/main/packs/BP/scripts/API/ConstructAPIModel.js). Copy the file into your project and import the models as needed.
## Instance
An `Instance` represents a single structure instance in the world, along with its properties and state.
```typescript
interface Instance {
name: PROTO.String,
structureId: PROTO.String,
isEnabled: PROTO.Boolean,
dimensionId: PROTO.Optional(PROTO.String),
location: PROTO.Optional({
x: PROTO.Float64,
y: PROTO.Float64,
z: PROTO.Float64
}),
bounds: PROTO.Optional(PROTO.Object({
min: {
x: PROTO.Float64,
y: PROTO.Float64,
z: PROTO.Float64
},
max: {
x: PROTO.Float64,
y: PROTO.Float64,
z: PROTO.Float64
}
})),
currentLayer: PROTO.Int16,
maxLayer: PROTO.Int16,
verifier: PROTO.Object({
isEnabled: PROTO.Boolean,
trackPlayerDistance: PROTO.Int8,
particleLifetime: PROTO.Int32
})
}
```
## Builder
A `Builder` represents a single builder (Construct's name for Players) in the world, along with its settings and properties.
```typescript
interface Builder {
playerId: PROTO.String,
easyPlace: PROTO.Boolean,
fastEasyPlace: PROTO.Boolean,
materialGrabber: PROTO.Boolean,
materialInstanceName: PROTO.String
}
```
docs/API/Endpoints.md
+75
View File
@@ -0,0 +1,75 @@
# Endpoints
This page documents all the available API endpoints that can be accessed by other addons or scripts. The API is designed so that entire objects are passed at once, rather than making multiple calls to edit or query individual properties. This allows for fewer API calls and easier access to data.
## Instances
### `construct:instances`
Get a list of all registered instance names.
- **Parameters**: `void`
- **Returns**: `string[]`
---
### `construct:instance:get`
Get the full data object for a specific instance.
- **Parameters**: `instanceName: string`
- **Returns**: `Instance` (see [Data Model](./DataModels.md#instance))
---
### `construct:instance:add`
Create a new instance with a given name and structure ID.
- **Parameters**: `instanceName: string`, `structureId: string`
- **Returns**: `Instance` (see [Data Model](./DataModels.md#instance))
---
### `construct:instance:edit`
Edit properties of an existing instance (e.g. enabled state, position).
- **Parameters**: `instanceName: string`, `properties: Instance`
- **Returns**: `Instance` (see [Data Model](./DataModels.md#instance))
---
### `construct:instance:delete`
Permanently delete an instance.
- **Parameters**: `instanceName: string`
- **Returns**: `void`
---
### `construct:instance:materials`
Get a list of materials required to build the active section of an instance. Respects the active layer.
- **Parameters**: `instanceName: string`
- **Returns**: `Map<string, number>` (material name to quantity)
## Builders
### `construct:builder:get`
Get the full data object for a specific builder (player).
- **Parameters**: `playerId: string`
- **Returns**: `Builder` (see [Data Model](./DataModels.md#builder))
---
### `construct:builder:edit`
Edit properties of an existing builder.
- **Parameters**: `playerId: string`, `properties: Builder`
- **Returns**: `Builder` (see [Data Model](./DataModels.md#builder))
docs/CLI.md
+149
View File
@@ -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.