Class Radiance

java.lang.Object
com.github.yellowstonegames.grid.Radiance
public class Radiance extends Object
Grouping of qualities related to glow and light emission. When a Radiance variable in some object is null, it means that object doesn't emit light; if a Radiance variable is non-null, it will probably emit light unless the color of light it produces is fully transparent. Light may take up one cell or extend into nearby cells, and the radius may change over time in up to two patterns (flicker, which randomly increases and decreases lighting radius, and/or strobe, which increases and decreases lighting radius in an orderly retract-expand-retract-expand pattern). You can set the flare variable to some value between 0.0f and 1.0f to temporarily expand the minimum radius for strobe and/or flare, useful for gameplay-dependent brightening of a Radiance.
A Radiance does not describe an individual source of light in the world, but rather the qualities that a source of light can have. A Radiance doesn't know its own position, or whether it is currently being drawn; it can be thought of like a color or texture. Some examples would be that data might describe one sword that glows blue (in the presence of game developers, perhaps), and another group of swords that all glow red and strobe rapidly.
This object has 6 fields, each a float:
  • range, how far the light extends; 0f is "just this cell"
  • color, the color of the light as a float; typically opaque and lighter than the glowing object's color
  • flicker, the rate of random continuous change to radiance range
  • strobe, the rate of non-random continuous change to radiance range
  • flare, used to suddenly increase the minimum radius of lighting; expected to be changed after creation
  • delay, which delays the pattern of effects like strobe so a sequence can be formed with multiple Radiance
These all have defaults; if no parameters are specified the light will be white, affect only the current cell, and won't flicker or strobe.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    int
    color
    The color of light as an int; will be interpreted as Oklab by LightingManager, but as RGBA by LightingManagerRgb.
    float
    delay
    A time delay that applies to when the strobe and flicker effects change; useful with strobe to make a strobe expand its lit radius at one point, then expand at a slightly later time at another Radiance with a delay.
    float
    flare
    A temporary increase to the minimum radiance range, meant to brighten a glow during an effect.
    float
    flicker
    The rate of random continuous change to radiance range, like the light from a campfire.
    float
    range
    How far the radiated light extends; 0f is "just this cell", anything higher can go into neighboring cells.
    int
    seed
    Assigned during construction by an internal PouchRandom, this is used for flickering effects, but does not affect equals(Object) or hashCode().
    float
    strobe
    The rate of non-random continuous change to radiance range, like a mechanical strobe effect.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Radiance()
    All-default constructor; makes a single-cell unchanging white light.
    Radiance(float range)
    Makes an unchanging white light with the specified range in cells.
    Radiance(float range, int color)
    Makes an unchanging light with the given color (as an Oklab int) and the specified range in cells.
    Radiance(float range, int color, float flicker)
    Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal.
    Radiance(float range, int color, float flicker, float strobe)
    Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal.
    Radiance(float range, int color, float flicker, float strobe, float delay)
    Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal.
    Radiance(float range, int color, float flicker, float strobe, float delay, float flare)
    Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal.
    Radiance(float range, int color, float flicker, float strobe, float delay, float flare, int seed)
    Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal.
    Radiance(float range, String color, float flicker, float strobe)
    Makes a flickering light with the given color (as a String that can be interpreted by DescriptiveColor) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal.
    Radiance(Radiance other)
    Copies another Radiance exactly, except for the pattern its flicker may have, if any.

  • Method Summary

    Modifier and Type
    Method
    Description
    float
    currentRange()
    Provides the calculated current range adjusted for flicker and strobe at the current time in milliseconds, with flicker seeded with the identity hash code of this Radiance.
    boolean
    equals(Object o)
     
    int
    hashCode()
     
    static Radiance[]
    makeChain(int length, float range, int color, float strobe)
    Makes a chain of Radiance objects that will pulse in a sequence, expanding from one to the next.
    static Radiance
    recreateFromString(String data)
     
    Radiance
    stringDeserialize(String data)
     
    String
    stringSerialize()
     
    String
    toString()
     

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • range

      public float range
      How far the radiated light extends; 0f is "just this cell", anything higher can go into neighboring cells. This is permitted to be a non-integer value, which will make this extend into further cells partially.

    • color

      public int color
      The color of light as an int; will be interpreted as Oklab by LightingManager, but as RGBA by LightingManagerRgb. Typically opaque and lighter than the glowing object's symbol.

    • flicker

      public float flicker
      The rate of random continuous change to radiance range, like the light from a campfire. The random component of the change is determined by a unique seed produced by an internal PouchRandom, which will probably make all flicker effects different when flicker is non-0.

    • strobe

      public float strobe
      The rate of non-random continuous change to radiance range, like a mechanical strobe effect. This looks like a strobe light when the value is high enough, but at lower values it will smoothly pulse, which can be less distracting to players.

    • delay

      public float delay
      A time delay that applies to when the strobe and flicker effects change; useful with strobe to make a strobe expand its lit radius at one point, then expand at a slightly later time at another Radiance with a delay. The range for delay should be considered 0f to 1f, with 0f the default (no delay) and values between 0 and 1f that fraction of a full strobe delayed from that default.

    • flare

      public float flare
      A temporary increase to the minimum radiance range, meant to brighten a glow during an effect. This should be a float between 0f and 1f, with 0f meaning no change and 1f meaning always max radius.

    • seed

      public int seed
      Assigned during construction by an internal PouchRandom, this is used for flickering effects, but does not affect equals(Object) or hashCode(). You can synchronize the flickering effect of two different Radiance objects by setting their seed to the same int. Seeds do not have to be globally unique.
      In earlier versions, this was private and transient, but that preventing synchronizing flicker effects. Now, it is public and generally should be serialized.

  • Constructor Details

    • Radiance

      public Radiance()
      All-default constructor; makes a single-cell unchanging white light. This assumes the color is being treated as Oklab; if you treat this as RGBA8888 without first converting with DescriptiveColor.toRGBA8888(int), this will look like light red. Because this defaults to using Oklab, it is meant for use with LightingManager, not LightingManagerRgb.

    • Radiance

      public Radiance(float range)
      Makes an unchanging white light with the specified range in cells. This assumes the color is being treated as Oklab; if you treat this as RGBA8888 without first converting with DescriptiveColor.toRGBA8888(int), this will look like light red. Because this defaults to using Oklab, it is meant for use with LightingManager, not LightingManagerRgb.
      Parameters:
      range - possibly-non-integer radius to light, in cells

    • Radiance

      public Radiance(float range, int color)
      Makes an unchanging light with the given color (as an Oklab int) and the specified range in cells. You can give this an Oklab color (to use with LightingManager) or an RGBA8888 color (to use with LightingManagerRgb).
      Parameters:
      range - possibly-non-integer radius to light, in cells
      color - an Oklab or RGBA8888 int color

    • Radiance

      public Radiance(float range, int color, float flicker)
      Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal. You can give this an Oklab color (to use with LightingManager) or an RGBA8888 color (to use with LightingManagerRgb).
      Parameters:
      range - possibly-non-integer radius to light, in cells
      color - an Oklab or RGBA8888 int color
      flicker - the rate at which to flicker, as a non-negative float

    • Radiance

      public Radiance(float range, int color, float flicker, float strobe)
      Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal. Usually one of flicker or strobe is 0; if both are non-0, the radius will be smaller than normal. You can give this an Oklab color (to use with LightingManager) or an RGBA8888 color (to use with LightingManagerRgb).
      Parameters:
      range - possibly-non-integer radius to light, in cells
      color - an Oklab or RGBA8888 int color
      flicker - the rate at which to flicker, as a non-negative float
      strobe - the rate at which to strobe or pulse, as a non-negative float

    • Radiance

      public Radiance(float range, String color, float flicker, float strobe)
      Makes a flickering light with the given color (as a String that can be interpreted by DescriptiveColor) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal. Usually one of flicker or strobe is 0; if both are non-0, the radius will be smaller than normal. You can only give this a description that will be translated to Oklab, so this is meant to be used only with LightingManager, not LightingManagerRgb.
      Parameters:
      range - possibly-non-integer radius to light, in cells
      color - a String that describes a color as per DescriptiveColor.describeOklab(String)
      flicker - the rate at which to flicker, as a non-negative float
      strobe - the rate at which to strobe or pulse, as a non-negative float

    • Radiance

      public Radiance(float range, int color, float flicker, float strobe, float delay)
      Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal. Usually one of flicker or strobe is 0; if both are non-0, the radius will be smaller than normal. The delay parameter is usually from 0f to 1f, and is almost always 0f unless this is part of a group of related Radiance objects; it affects when strobe and flicker hit "high points" and "low points", and should usually be used with strobe. You can give this an Oklab color (to use with LightingManager) or an RGBA8888 color (to use with LightingManagerRgb).
      Parameters:
      range - possibly-non-integer radius to light, in cells
      color - an Oklab or RGBA8888 int color
      flicker - the rate at which to flicker, as a non-negative float
      strobe - the rate at which to strobe or pulse, as a non-negative float
      delay - a delay applied to the "high points" and "low points" of strobe and flicker, from 0f to 1f

    • Radiance

      public Radiance(float range, int color, float flicker, float strobe, float delay, float flare)
      Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal. Usually one of flicker or strobe is 0; if both are non-0, the radius will be smaller than normal. The delay parameter is usually from 0f to 1f, and is almost always 0f unless this is part of a group of related Radiance objects; it affects when strobe and flicker hit "high points" and "low points", and should usually be used with strobe. This allows setting flare, where flare is used to create a sudden increase in the minimum radius for the Radiance, but flare makes the most sense to set when an event should brighten a Radiance, not in the constructor. Valid values for flare are usually between 0f and 1f. You can give this an Oklab color (to use with LightingManager) or an RGBA8888 color (to use with LightingManagerRgb).
      Parameters:
      range - possibly-non-integer radius to light, in cells
      color - an Oklab or RGBA8888 int color
      flicker - the rate at which to flicker, as a non-negative float
      strobe - the rate at which to strobe or pulse, as a non-negative float
      delay - a delay applied to the "high points" and "low points" of strobe and flicker, from 0f to 1f
      flare - affects the minimum radius for the Radiance, from 0f to 1f with a default of 0f

    • Radiance

      public Radiance(float range, int color, float flicker, float strobe, float delay, float flare, int seed)
      Makes a flickering light with the given color (as an Oklab int) and the specified range in cells; the flicker parameter affects the rate at which this will randomly reduce its range and return to normal, and the strobe parameter affects the rate at which this will steadily reduce its range and return to normal. Usually one of flicker or strobe is 0; if both are non-0, the radius will be smaller than normal. The delay parameter is usually from 0f to 1f, and is almost always 0f unless this is part of a group of related Radiance objects; it affects when strobe and flicker hit "high points" and "low points", and should usually be used with strobe. This allows setting flare, where flare is used to create a sudden increase in the minimum radius for the Radiance, but flare makes the most sense to set when an event should brighten a Radiance, not in the constructor. Valid values for flare are usually between 0f and 1f. You can give this an Oklab color (to use with LightingManager) or an RGBA8888 color (to use with LightingManagerRgb).
      Parameters:
      range - possibly-non-integer radius to light, in cells
      color - an Oklab or RGBA8888 int color
      flicker - the rate at which to flicker, as a non-negative float
      strobe - the rate at which to strobe or pulse, as a non-negative float
      delay - a delay applied to the "high points" and "low points" of strobe and flicker, from 0f to 1f
      flare - affects the minimum radius for the Radiance, from 0f to 1f with a default of 0f
      seed - a forced seed that can be used to synchronize flicker effects between Radiance objects

    • Radiance

      public Radiance(Radiance other)
      Copies another Radiance exactly, except for the pattern its flicker may have, if any.
      Parameters:
      other - another Radiance to copy

  • Method Details

    • currentRange

      public float currentRange()
      Provides the calculated current range adjusted for flicker and strobe at the current time in milliseconds, with flicker seeded with the identity hash code of this Radiance. Higher values of flicker and strobe will increase the frequency at which the range changes but will not allow it to exceed its starting range, only to diminish temporarily. If both flicker and strobe are non-0, the range will usually be smaller than if only one was non-0, and if both are 0, this simply returns range.
      Returns:
      the current range, adjusting for flicker and strobe using the current time

    • makeChain

      public static Radiance[] makeChain(int length, float range, int color, float strobe)
      Makes a chain of Radiance objects that will pulse in a sequence, expanding from one to the next. This chain is an array of Radiance where the order matters.
      Parameters:
      length - how many Radiance objects should be in the returned array
      range - in cells, how far each Radiance should expand from its start at its greatest radius
      color - as an Oklab or RGBA8888 int color
      strobe - the rate at which the chain will pulse; should be greater than 0
      Returns:
      an array of Radiance objects that will pulse in sequence.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • stringSerialize

      public String stringSerialize()

    • stringDeserialize

      public Radiance stringDeserialize(String data)

    • recreateFromString

      public static Radiance recreateFromString(String data)