Class Structure

java.lang.Object
nl.pim16aap2.animatedarchitecture.core.structures.Structure
All Implemented Interfaces:
IStructureConst, IPropertyHolder, IPropertyHolderConst
@ThreadSafe public final class Structure extends Object implements IStructureConst, IPropertyHolder
Represents the abstract base all structure types should extend.

Please read the documentation of nl.pim16aap2.animatedarchitecture.core.structures for more information about the structure system.

Changes made to this class will not automatically be updated in the database. To update the state in the database, you can use the syncData() method.

  • Method Details

    • getType

      public StructureType getType()
      Description copied from interface: IStructureConst
      Returns the StructureType of this structure.
      Specified by:
      getType in interface IStructureConst
      Returns:
      The StructureType of this structure.

    • getCycledOpenDirection

      public MovementDirection getCycledOpenDirection()
      Description copied from interface: IStructureConst
      Cycle the MovementDirection direction this Structure will open in. By default, it will loop over all valid directions. See StructureType.getValidOpenDirectionsList(). However, subclasses may override this behavior.

      Note that this does not actually change the open direction; it merely tells you which direction comes next!

      Specified by:
      getCycledOpenDirection in interface IStructureConst
      Returns:
      The new MovementDirection direction this Structure will open in.

    • canMovePerpetually

      public boolean canMovePerpetually()
      Description copied from interface: IStructureConst
      Checks if this structure can move perpetually.
      Specified by:
      canMovePerpetually in interface IStructureConst
      Returns:
      True if this structure can move perpetually.

    • constructAnimationComponent

      public IAnimationComponent constructAnimationComponent(AnimationRequestData data)
      Constructs a new animation component for this structure.
      Parameters:
      data - The data to construct the animation component with.
      Returns:
      The constructed animation component.

    • getPotentialNewCoordinates

      public Optional<Cuboid> getPotentialNewCoordinates()
      Finds the new minimum and maximum coordinates (represented by a Cuboid) of this structure that would be the result of toggling it.
      Returns:
      The Cuboid that would represent the structure if it was toggled right now.

    • getAnimationCycleDistance

      public double getAnimationCycleDistance()
      Gets the distance traveled per animation by the animated block that travels the furthest.

      For example, for a circular object, this will be a block on the edge, as these blocks travel further per revolution than the blocks closer to the center of the circle.

      This method looks at the distance per animation cycle. The exact definition of a cycle depends on the implementation of the structure. For a big door, for example, a cycle could be a single toggle, or a quarter circle. To keep things easy, a revolving structure (which may not have a definitive end to its animation) could define a cycle as quarter circle as well.

      The distance value is used to calculate getMinimumAnimationTime() and getBaseAnimationTime().

      Returns:
      The longest distance traveled by an animated block measured in blocks.

    • getAnimationRange

      public Rectangle getAnimationRange()
      Gets the rectangle describing the limits within an animation of this door takes place.

      At no point during an animation will any animated block leave this cuboid, though not guarantees are given regarding how tight the cuboid fits around the animated blocks.

      Specified by:
      getAnimationRange in interface IStructureConst
      Returns:
      The animation range.

    • getMinimumAnimationTime

      public double getMinimumAnimationTime()
      Gets the lower time limit for an animation.

      Because animated blocks have a speed limit, as determined by IConfig.maxBlockSpeed(), there is also a minimum amount of time for its animation.

      The exact time limit depends on the shape, size, and type of structure.

      Specified by:
      getMinimumAnimationTime in interface IStructureConst
      Returns:
      The lower animation time limit for this structure in seconds.

    • getBaseAnimationTime

      public double getBaseAnimationTime()
      Gets the base animation time for this structure.

      This is the animation time without any multipliers applied to it.

      Returns:
      The base animation time for this structure in seconds.

    • canSkipAnimation

      public boolean canSkipAnimation()
      Checks if this structure can be opened instantly (i.e. skip the animation).

      This describes whether skipping the animation actually does anything. When a structure can skip its animation, it means that the actual toggle has an effect on the world and as such toggling it without an animation does something.

      Structures that do not have any effect other than their animation because all their blocks start and stop at exactly the same place (i.e. flags) cannot skip their animation because skipping the animation would mean removing the blocks of the structure from their locations and then placing them back at exactly the same position. This would be a waste of performance for both the server and the client and as such should be prevented.

      Returns:
      True, if this structure can skip its animation.

    • onChunkLoad

      public void onChunkLoad()
      Handles the chunk of the power block (or rotation point) being loaded.

    • verifyRedstoneState

      public void verifyRedstoneState()
      Verifies the redstone state of this structure.

      This method will compare the current redstone state of the power block to the current state of this structure and act accordingly.

      For example, if the structure is powered and this structure is currently closed, it will open the structure.

      Or, if this is a structure that can move perpetually (e.g. a flag), it will stop the animation if the power block is no longer powered.

    • onRedstoneChange

      public void onRedstoneChange(boolean isPowered)
      Handles a change in redstone power.

      This method makes two assumptions:

      1. The chunk containing the power block is loaded.
      2. The provided isPowered value reflects the power state of the power block in the world

      If you cannot guarantee these assumptions, use verifyRedstoneState() instead.

      Parameters:
      isPowered - The power state of the power block in the world.

    • getSnapshot

      public StructureSnapshot getSnapshot()
      Description copied from interface: IStructureConst
      Returns a (read-only) StructureSnapshot of this structure.

      Repeated calls to this method may or may not return the same instance unless the underlying structure has been modified, in which case a new snapshot reflecting the changes will be returned.

      Specified by:
      getSnapshot in interface IStructureConst
      Returns:
      A StructureSnapshot of this structure.

    • syncData

      public CompletableFuture<DatabaseManager.ActionResult> syncData(boolean handleException)
      Synchronizes this structure with the database.
      Parameters:
      handleException - Whether to handle exceptions or not. When set to true, exceptions that occur during the synchronization process will be caught and logged and the result will be DatabaseManager.ActionResult.FAIL.

      When set to false, exceptions will not be handled and will be propagated to the caller.

      Returns:
      The result of the synchronization.

    • syncData

      public CompletableFuture<DatabaseManager.ActionResult> syncData()
      Synchronizes this structure with the database.
      Returns:
      The result of the synchronization.

    • hasWriteLock

      public boolean hasWriteLock()
      Checks if the current thread holds a write lock.

      This method is intended for diagnostic assertions only (e.g., verifying that a caller already holds the write lock before performing a mutation). It should not be used for control-flow decisions outside of assertion contexts.

      Returns:
      true if the current thread holds a write lock.

    • withWriteLock

      public <T> T withWriteLock(Supplier<T> supplier)
      Executes a supplier under a write lock.
      Type Parameters:
      T - The return type of the supplier.
      Parameters:
      supplier - The supplier to execute under the write lock.
      Returns:
      The value returned by the supplier.
      Throws:
      IllegalStateException - When the current thread may is not allowed to obtain a write lock.

    • withWriteLock

      public <T> T withWriteLock(boolean resetAnimationData, Supplier<T> supplier)
      Executes a supplier under a write lock.
      Type Parameters:
      T - The return type of the supplier.
      Parameters:
      resetAnimationData - Whether to reset the cached animation data after the supplier has been executed.

      This is useful when the supplier modifies the structure in a way that affects the animation data.

      supplier - The supplier to execute under the write lock.
      Returns:
      The value returned by the supplier.
      Throws:
      IllegalStateException - When the current thread may is not allowed to obtain a write lock.

    • withWriteLock

      public void withWriteLock(Runnable runnable)
      Executes a Runnable under a write lock.
      Throws:
      IllegalStateException - When the current thread may is not allowed to obtain a write lock.

    • withReadLock

      public <T> T withReadLock(Supplier<T> supplier)
      Executes a supplier under a read lock.
      Type Parameters:
      T - The return type of the supplier.
      Parameters:
      supplier - The supplier to execute under the read lock.
      Returns:
      The value returned by the supplier.

    • withReadLock

      public void withReadLock(Runnable runnable)
      Executes a Runnable under a read lock.

    • getBasicInfo

      public String getBasicInfo()
      Description copied from interface: IStructureConst
      Gets the basic information of this structure.

      This includes the name, UID, type, and prime owner of this structure.

      Specified by:
      getBasicInfo in interface IStructureConst
      Returns:
      The basic information of this structure.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getOwners

      public Collection<StructureOwner> getOwners()
      Description copied from interface: IStructureConst
      Gets all StructureOwners of this structure, including the original creator.
      Specified by:
      getOwners in interface IStructureConst
      Returns:
      All StructureOwners of this structure, including the original creator.

    • getOwner

      public Optional<StructureOwner> getOwner(UUID uuid)
      Description copied from interface: IStructureConst
      Attempts to get the StructureOwner of this structure represented by the UUID of a player.
      Specified by:
      getOwner in interface IStructureConst
      Parameters:
      uuid - The UUID of the player that may or may not be an owner of this structure.
      Returns:
      The StructureOwner of this structure for the given player, if this player is a StructureOwner of this structure.

    • isOwner

      public boolean isOwner(UUID uuid)
      Description copied from interface: IStructureConst
      Checks if a player with a given UUID is a (co-)owner of this structure with any level of ownership.

      If the level of ownership matters, use IStructureConst.getOwner(UUID) instead.

      Specified by:
      isOwner in interface IStructureConst
      Parameters:
      uuid - The UUID of a player.
      Returns:
      True if the player with the given UUID is an owner of this structure with any level of ownership.

    • isOwner

      public boolean isOwner(UUID uuid, PermissionLevel permissionLevel)
      Description copied from interface: IStructureConst
      Checks if a player with a given UUID is a (co-)owner of this structure with a given level of ownership.
      Specified by:
      isOwner in interface IStructureConst
      Parameters:
      uuid - The UUID of a player.
      permissionLevel - The maximum level of ownership the player may have.

      E.g. when permissionLevel is PermissionLevel.ADMIN, this method will return true if the player has admin access or lower (PermissionLevel.ADMIN or PermissionLevel.CREATOR).

      Returns:
      True if the player with the given UUID is an owner of this structure with the given level of ownership (or lower).

    • setCoordinates

      public void setCoordinates(Cuboid newCuboid)
      Changes the position of this Structure. The min/max order of the positions doesn't matter.
      Parameters:
      newCuboid - The Cuboid representing the area the structure will take up from now on.

    • setPowerBlock

      public void setPowerBlock(Vector3Di newPos)
      Updates the position of the powerblock.
      Parameters:
      newPos - The new position.

    • setName

      public void setName(String name)
      Changes the name of the structure.
      Parameters:
      name - The new name of this structure.

    • setOpenDirection

      public void setOpenDirection(MovementDirection openDir)
      Sets the MovementDirection this Structure will open if currently closed.

      Note that if it's currently in the open status, it is supposed go in the opposite direction, as the closing direction is the opposite of the opening direction.

      Parameters:
      openDir - The MovementDirection this Structure will open in.

    • setLocked

      public void setLocked(boolean locked)
      Changes the lock status of this structure. Locked structures cannot be opened.
      Parameters:
      locked - New lock status.

    • setCoordinates

      public void setCoordinates(Vector3Di posA, Vector3Di posB)
      Changes the position of this Structure. The min/max order of the positions does not matter.
      Parameters:
      posA - The first new position.
      posB - The second new position.

    • getPropertyContainerSnapshot

      public PropertyContainerSnapshot getPropertyContainerSnapshot()
      Description copied from interface: IStructureConst
      Gets the PropertyContainerSnapshot of this structure.
      Specified by:
      getPropertyContainerSnapshot in interface IStructureConst
      Returns:
      The PropertyContainerSnapshot of this structure.

    • getPropertyValue

      public <T> IPropertyValue<T> getPropertyValue(Property<T> property)
      Description copied from interface: IPropertyHolderConst
      Gets the value of the given property.
      Specified by:
      getPropertyValue in interface IPropertyHolderConst
      Type Parameters:
      T - The type of the property.
      Parameters:
      property - The property to get the value of.
      Returns:
      The value of the property.

    • hasProperty

      public boolean hasProperty(Property<?> property)
      Description copied from interface: IPropertyHolderConst
      Checks if the given property has a value set.
      Specified by:
      hasProperty in interface IPropertyHolderConst
      Parameters:
      property - The property to check.
      Returns:
      true if the property has a value set, false otherwise.

    • hasProperties

      public boolean hasProperties(Collection<Property<?>> properties)
      Description copied from interface: IPropertyHolderConst
      Checks if this property holder has all the given properties.
      Specified by:
      hasProperties in interface IPropertyHolderConst
      Parameters:
      properties - The properties to check.
      Returns:
      true if this property holder has all the given properties, false otherwise.

    • propertyCount

      public int propertyCount()
      Description copied from interface: IPropertyHolderConst
      Gets the number of properties in this property container.

      This is the number of entries in the property map.

      Specified by:
      propertyCount in interface IPropertyHolderConst
      Returns:
      The number of properties in this property container.

    • canRemoveProperty

      public boolean canRemoveProperty(Property<?> property)
      Description copied from interface: IPropertyHolder
      Checks if a property can be removed from this property holder.

      A property can not be removed under the following conditions:

      Specified by:
      canRemoveProperty in interface IPropertyHolder
      Parameters:
      property - The property to check.
      Returns:
      true if the property can be removed from this property holder, false otherwise.

    • removeProperty

      public <T> IPropertyValue<T> removeProperty(Property<T> property) throws IllegalArgumentException
      Description copied from interface: IPropertyHolder
      Removes the given property from this property container.

      Properties cannot be removed under certain conditions. When in doubt, check IPropertyHolder.canRemoveProperty(Property).

      Specified by:
      removeProperty in interface IPropertyHolder
      Type Parameters:
      T - The type of the property.
      Parameters:
      property - The property to remove.
      Returns:
      The previous value of the property, or PropertyContainer.UnsetPropertyValue.INSTANCE if the property was not set.
      Throws:
      IllegalArgumentException - Thrown if;
      • the property cannot be removed (i.e. it is specified by StructureType.getProperties()).
      • the type of the removed property does not match the type of the property specified by the property.

    • setPropertyValue

      public <T> IPropertyValue<T> setPropertyValue(Property<T> property, @Nullable T value)
      Description copied from interface: IPropertyHolder
      Sets the value of the given property.
      Specified by:
      setPropertyValue in interface IPropertyHolder
      Type Parameters:
      T - The type of the property.
      Parameters:
      property - The property to set the value for.
      value - The value to set.

      If this is null, the property will be removed.

      Returns:
      The previous value of the property, or null if the property had no value set.

    • equals

      public boolean equals(@Nullable Object o)
      Specified by:
      equals in interface IStructureConst
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getUid

      public long getUid()
      Description copied from interface: IStructureConst
      Gets the UID of the Structure as used in the database. Guaranteed to be unique and available.
      Specified by:
      getUid in interface IStructureConst
      Returns:
      The UID of the Structure as used in the database.

    • getWorld

      public IWorld getWorld()
      Description copied from interface: IStructureConst
      Gets the IWorld this Structure exists in.
      Specified by:
      getWorld in interface IStructureConst
      Returns:
      The IWorld this Structure exists in

    • getPowerBlock

      public Vector3Di getPowerBlock()
      Description copied from interface: IStructureConst
      Gets the position of power block of this structure.
      Specified by:
      getPowerBlock in interface IStructureConst
      Returns:
      The position of the power block of this structure.

    • getName

      public String getName()
      Description copied from interface: IStructureConst
      Gets the name of this structure.
      Specified by:
      getName in interface IStructureConst
      Returns:
      The name of this structure.

    • getCuboid

      public Cuboid getCuboid()
      Description copied from interface: IStructureConst
      Gets the Cuboid representing the area taken up by this structure.
      Specified by:
      getCuboid in interface IStructureConst
      Returns:
      The Cuboid representing the area taken up by this structure.

    • getOpenDirection

      public MovementDirection getOpenDirection()
      Description copied from interface: IStructureConst
      Gets the MovementDirection this Structure will open if currently closed.

      Note that if it's currently in the open status, it is supposed go in the opposite direction, as the closing direction is the opposite of the opening direction. This isn't taken into account by this method.

      Specified by:
      getOpenDirection in interface IStructureConst
      Returns:
      The MovementDirection this Structure will open in.

    • isLocked

      public boolean isLocked()
      Represents the locked status of this structure. True = locked, False = unlocked.
      Specified by:
      isLocked in interface IStructureConst
      Returns:
      True if the Structure is locked

    • getPrimeOwner

      public StructureOwner getPrimeOwner()
      Description copied from interface: IStructureConst
      Gets the prime owner (permission = 0) of this structure. In most cases, this will be the original creator of the structure.
      Specified by:
      getPrimeOwner in interface IStructureConst
      Returns:
      The prime owner of this structure.