StructureAPI

「Structure API」
Multi-block structure made easy

「StructureAPI」 is a library for plugin developers, allow developers create multi-block structures instantly in chain-style and provide events when the structure changes, by default, there are create, destroy and click event, you can also add custom detections.

0x01
Introduction to multi-block structure

You may feel confused about multi-block structure, to clarify, the multi-block structure is completely different from the vanilla structure (Mineshaft etc.).
However, it's not a new concept, you may have already met them before especially plugins that can build machines.

Definitively, a multi-block structure is consists of a few blocks that close to each other.
The following pictures show some multi-block structures:

An impossible lightning conductor

A simple redstone turret

Those pictures just show you what is multi-block structure, this plugin doesn't provide you with those functions, remember it's just an API.

0x02
Library usage

i. New Concepts and features*
1) Structure
A structure contains a list which stores block material and its relative coord in current structure and event listeners.

2) Origin coord
An origin coord is the first block that should be placed in a structure, the relative block coordinate of an origin coord is always (0, 0, 0).

3) Coord
Actually, they are relative block coordinate in their structure block lists, thanks to the relative, we can detect a structure form its any member block.
A coord represent as (x, y, z).

All coords in a structure should be relative with the origin coord.
For example, a block directly above the origin coord should be represented as (0, 1, 0).

4) Trigger
Every coord has its trigger, a trigger is bound to a block (1 -> 1).
A trigger records what action can trigger this structure from the current block, such as left-click-only or right-click-only.

5) Link
You may feel confused about how this library detects a structure since a player can place the blocks orderlessly.
Link feature is what you wanted, you can simply add a .link() to the tail of a structure build to enable this useful feature, then, your structure will be mirroring from every coord by offsetting the relative coord.
Actually, every coord in the structure will become an origin coord in the mirrored structures. The mirrored structures are called linked structure.
Fyi, if you don't use this feature, your structure could be only built by specified order(based on your block-add order).

6) LinkStage
This feature is a bit complex to understand, it was designed to improve performance at first, because for some big structures, always search theirs linked structures is expensive.
You can specify your structure to some specific LinkStage, then only in the specified situation, the library will search the linked structures of your structure.

7) StructureTree
A structure-tree contains all necessary information of a multi-block structure(all things listed above), if you wanna register a structure, you post a StructureTree instance but not a Structure instance.

ii. Demo
The code here -> Gitlab
The demo considered the order, so it will still work if you remove the .link() in the tail of structure-tree build.
This demo is attached with the plugin, you can use it to test whether the library works correctly by invoking StructureDemo.registerDemo();

iii. Developing document
A simple introduction to every class and interface, enum.

class StructureAPI
Allows you to register and unregister a structure.
Furthermore, you can match structure in any block location if you want. it will return null if cannot find any.

enum StructureAPI.LinkStage
The default is ANY.

class StructureAPI.Coord
You can set the relative x, y, z and material, trigger of a block.
contact() is a convenient method help you transfer a group coord to an array.
offset() will create new coord, not just modify x, y, z.

class StructureAPI.Trigger
This class allows you to change the clickable for a single block.

class StructureAPI.StructureTree
This class provides method allows you to make whole structure clickable and specific LinkStage.

interface StructureAPI.Structure
This interface provides two event-style methods, you should implement this interface for your structure main class.

interface StructureAPI.Clickable extends Structure
You should implement this for your structure main class if you want to do something when player interact.
There is must at least one block that its Trigger allows interact.

interface StructureAPI.LeftOnly extends Clickable
Signature interface. For convenience, you can implement this interface to ignore right-click.

interface StructureAPI.RightOnly extends Clickable
Signature interface. For convenience, you can implement this interface to ignore left-click.

event CoordInteractEvent
Fire when a structure was triggered by interact, you can get the StructureTree, Coord and the source event(PlayerInteractEvent).

Powered by Akarin-project

Chat in Discord