Package nl.pim16aap2.animatedarchitecture.core.structures

@NullMarked package nl.pim16aap2.animatedarchitecture.core.structures
This package contains classes that define, manipulate, and manage structures.

Structure Instantiation and Retrieval

An important concept to understand is that structures follow the multiton pattern. This means that there can be at most one instance of a structure with a given UID. These instances are cached and registered in the StructureRegistry. While it is possible to create your own instances of structures, these unregistered instances will be of limited use and will likely lead to unexpected behaviour.

Instead, you should retrieve instances of structures using a StructureRetriever. The StructureRetrieverFactory class can be used to create retrievers that can be used to retrieve structures from the database using a variety of different criteria.

Thread-Safety

One thing to keep in mind is that structures are fully thread-safe and can be used from any thread through the use of read/write locks. The downside of this is that it is possible for a thread to block while waiting for a lock to become available. This is especially true for the write lock, which is used when creating or deleting structures. This means that care should be taken when using structures from the main thread. If you are using structures from the main thread, you should consider using asynchronous tasks to avoid blocking the main thread.

Care should also be taken to avoid situations where an action is performed that requires a write lock while a read lock is already held. This can lead to deadlocks. The plugin will try to prevent this from happening, but it is still a good idea to keep this in mind, as it can lead to exceptions being thrown when a potential deadlock is detected.

Structure Modification

Another thing to keep in mind is that structures are not automatically saved to the database. This means that if you make changes to a structure, those will not be saved to the database until you call the Structure.syncData() method.

When making changes to a structure on behalf of a player, you should use consider using nl.pim16aap2.animatedarchitecture.core.commands instead. This will ensure that the changes are saved to the database, that the player is notified of any errors that may occur, and that any logging is done correctly.

Structure Object Types

There are several different types of structure objects that are used to refer to structures. These are:

  • IStructureConst: This is the immutable version of a structure. It is used to retrieve information about a structure, but cannot be used to modify the structure. All other types are subtypes of this type.

    Never cast objects of this type to its mutable variant. Doing so can lead to all kinds of issues, including deadlocks.

  • Structure: This is the mutable version of a structure. It is the most commonly used type of structure object. It can be used to modify the structure.

    Whenever the documentation refers to a "structure" it is referring to this type unless otherwise specified.

    This class refers to the IStructureComponent interface for any type-specific behaviors (including, but not limited to, creating new animation components).

  • StructureSnapshot: This is an immutable snapshot of a structure at a given point in time. Its immutability allows it to be used safely from any thread without locking or synchronization.

Toggling a Structure

The preferred method to toggle structures is by using StructureAnimationRequestBuilder.