Package org.boxutil.define.struct.statictrail

Class StaticTrailData

java.lang.Object
org.boxutil.define.struct.statictrail.StaticTrailData
public class StaticTrailData extends Object
Recommended to use const field for all.

For each trail object, a fixed amount of vRAM is pre‑allocated for storing its rendering data, this amount depends on the trail duration(fadeIn + full + fadeOut) and the trail quality configuration.

Therefore, the duration should not be set too long, as doing so may consume excessive vRAM.

For (M)VP matrix, always is BoxEnum.ENTITY_VANILLA_PRIME_MATRIX.

To reduce overhead and permit special values for custom effects, the trail system does not heavily validate parameters, so you must ensure the correctness of the values they supply.

TECHNICAL DETAILS

When a trail is created, the trail system assumes that after it starts generating, it will continue generating for at least the given duration before stopping (or still running); accordingly, a sufficiently large fixed‑size vRAM block is allocated.

Each recorded node in the trail occupies 24 bytes of vRAM. In addition to the minimum number of nodes required to form a trail, an extra fixed 3 fill-nodes are allocated for proper rendering.

Based on the configured maximum number of nodes recordable per second(nodePerSeconds), and provided that all components of the duration are non‑negative, the allocated vRAM for one trail is: 

 24 * (ceil(duration * nodePerSeconds) + 3)  bytes

  • Field Details

    • MINIMUM_TOTAL_DURATION

      public static final float MINIMUM_TOTAL_DURATION
      See Also:

    • randomUVStartOffset

      public boolean randomUVStartOffset

    • additiveBlend

      public boolean additiveBlend

    • velocityForForward

      public boolean velocityForForward

    • renderBelowExplosions

      public boolean renderBelowExplosions

    • initCapacity

      public final short initCapacity
      How many trails have in a typical scene.

    • durFadeIn

      public float durFadeIn

    • durFull

      public float durFull

    • durFadeOut

      public float durFadeOut

    • sizeIn

      public float sizeIn

    • sizeOut

      public float sizeOut

    • smoothEnds

      public float smoothEnds

    • texturePixels

      public float texturePixels

    • textureSpeed

      public float textureSpeed

    • id

      @NotNull public final String id
      The unique ID in game.

    • material

      @NotNull public MaterialData material

    • angularInRange

      @Nullable public org.lwjgl.util.vector.Vector2f angularInRange

    • angularOutRange

      @Nullable public org.lwjgl.util.vector.Vector2f angularOutRange

    • colorIn

      @Nullable public org.lwjgl.util.vector.Vector4f colorIn

    • colorOut

      @Nullable public org.lwjgl.util.vector.Vector4f colorOut

    • velocityInRange

      @Nullable public org.lwjgl.util.vector.Vector4f velocityInRange

    • velocityOutRange

      @Nullable public org.lwjgl.util.vector.Vector4f velocityOutRange

    • fixedSpawnOffsetRange

      @Nullable public org.lwjgl.util.vector.Vector4f fixedSpawnOffsetRange

    • customTrackerID

      @Nullable public String customTrackerID

  • Constructor Details

    • StaticTrailData

      public StaticTrailData(@NotNull String id, short initCapacity)
      Parameters:
      id - IMPORTANT, the unique ID in game, to define the unique trail style type and memory pool, for example ABCD_efgh_trail.

      MUST be the const field.

      CANNOT be empty or contains only white space codepoints.

      initCapacity - how many trails have in a typical scene, for example: 2048 for the weapon [vulkan]

    • StaticTrailData

      public StaticTrailData(@NotNull StaticTrailData src, @NotNull String id, short initCapacity)
      Deep copy constructor.
      Parameters:
      id - IMPORTANT, the unique ID in game, to define the unique trail style type and memory pool, for example ABCD_abcd_trail.

      MUST be the const field.

      CANNOT be empty or contains only white space codepoints.

      initCapacity - how many trails have in a typical scene, for example: 2048 for the weapon [vulkan]

  • Method Details

    • setRandomUVStartOffset

      public StaticTrailData setRandomUVStartOffset(boolean randomUVStartOffset)
      Whether to apply a random offset to the UV coordinates for texture sampling, may make the trail more naturally.

    • setAdditiveBlend

      public StaticTrailData setAdditiveBlend(boolean additiveBlend)
      Use additive blend when true, false for normal blend.

    • setVelocityForForward

      public StaticTrailData setVelocityForForward(boolean velocityForForward)
      Only for system-gen trail, invalid for custom trail, not required.

      Use the facing of entity for forward direction when false, use the velocity of entity when true.

      For any stationary projectiles (velocity is a zero vector), also use facing for forward.

      Recommended to set to true if the spawnType of projectile is BALLISTIC_AS_BEAM.

    • setRenderBelowExplosions

      public StaticTrailData setRenderBelowExplosions(boolean renderBelowExplosions)
      Only for system-gen trail, invalid for custom trail, not required.

      Rendering at CombatEngineLayers.BELOW_INDICATORS_LAYER when false, at CombatEngineLayers.ABOVE_SHIPS_LAYER when true

    • setDurFadeIn

      public StaticTrailData setDurFadeIn(float durFadeIn)
      MUST be the const field, and greater than or equal to zero.

    • setDurFull

      public StaticTrailData setDurFull(float durFull)
      MUST be the const field, and greater than or equal to zero.

    • setDurFadeOut

      public StaticTrailData setDurFadeOut(float durFadeOut)
      MUST be the const field, and greater than or equal to zero.

    • setSizeIn

      public StaticTrailData setSizeIn(float sizeIn)
      The head width of trail in pixels.

    • setSizeOut

      public StaticTrailData setSizeOut(float sizeOut)
      The tail width of trail in pixels.

    • setSmoothEnds

      public StaticTrailData setSmoothEnds(float duration)
      Controls the transparency fade at both ends of a trail to smooth truncation. The fade only affects the first two and last two nodes; larger values stretch the faded area. The effective range also depends on the variable node‑per‑second recording rate.

    • setTexturePixels

      public StaticTrailData setTexturePixels(float texturePixels)
      MUST be the const field, and should be a positive number.

    • setTextureSpeed

      public StaticTrailData setTextureSpeed(float textureSpeed)
      The texture scrolling length in one seconds.

      Use negative value will look like away from the spawn location.

    • setMaterial

      public StaticTrailData setMaterial(@NotNull MaterialData material)
      For cull face state, always used BoxEnum.MATERIAL_CULL_DISABLED.

    • setAngularInRange

      public StaticTrailData setAngularInRange(@Nullable org.lwjgl.util.vector.Vector2f angularInRange)
      Based on forward direction.

      {minAngular, maxAngular}, null for without angular applied

    • setAngularOutRange

      public StaticTrailData setAngularOutRange(@Nullable org.lwjgl.util.vector.Vector2f angularOutRange)
      Based on forward direction.

      {minAngular, maxAngular}, null for without angular applied

    • setColorIn

      public StaticTrailData setColorIn(@Nullable org.lwjgl.util.vector.Vector4f colorIn)
      null for white color with full opacity.

    • setColorOut

      public StaticTrailData setColorOut(@Nullable org.lwjgl.util.vector.Vector4f colorOut)
      null for white color with full opacity.

    • setVelocityInRange

      public StaticTrailData setVelocityInRange(@Nullable org.lwjgl.util.vector.Vector4f velocityInRange)
      Based on forward direction.

      {minVelocity.xy, maxVelocity.xy}, null for without velocity applied

    • setVelocityOutRange

      public StaticTrailData setVelocityOutRange(@Nullable org.lwjgl.util.vector.Vector4f velocityOutRange)
      Based on forward direction.

      {minVelocity.xy, maxVelocity.xy}, null for without velocity applied

    • setFixedSpawnOffsetRange

      public StaticTrailData setFixedSpawnOffsetRange(@Nullable org.lwjgl.util.vector.Vector4f fixedSpawnOffsetRange)
      Only for system-gen trail, invalid for custom trail, not required.

      Based on forward direction.

      {minOffset.xy, maxOffset.xy}, null for without offset

    • setCustomTrackerID

      public StaticTrailData setCustomTrackerID(@Nullable String trackerID)
      Only for system-gen trail, invalid for custom trail, not required.

      The trail will try to use specific tracker by ID, call StaticTrailManager.registerCustomTracker(String, BiFunction) for register one.

      null or white space, or not find the tracker constructor with the ID, then the trail will use default built-in tracker.

    • hashCode

      public final int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public final boolean equals(Object obj)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object