Package nl.colorize.multimedialib.scene.effect

Class Effect

java.lang.Object
nl.colorize.multimedialib.scene.effect.Effect
All Implemented Interfaces:
Scene
public final class Effect extends Object implements Scene
Effects are short-lived sub-scenes that can be defined in a declarative style. Effects are not intended to contain general application logic, they are intended for small, self-contained effects that are active for a limited period of time and are independent of other things happening in the scene.

Behavior can be added to effects in the form of handlers. These handlers operate on different points in the effect's lifecycle, for example during frame updates or after the effect is marked as completed.

Effects can be "linked" to graphics. When the effect ends, it will automatically remove all linked graphics from the stage. This allows the effect to control the life cycle for both the effect logic and the associated graphics.

  • Constructor Details

    • Effect

      public Effect()
      Creates a new effect that initially does not define any behavior and is not linked to any graphics. Prefer using the static factory methods to create effects with the desired behavior.

  • Method Details

    • addFrameHandler

      public Effect addFrameHandler(Updatable handler)

    • addFrameHandler

      public Effect addFrameHandler(Runnable handler)

    • addTimerHandler

      public Effect addTimerHandler(Timer timer, Consumer<Float> callback)
      Adds a frame handler that will update the specified timer during every update, then invokes the callback function based on the timer's new value. This effect will be marked as completed once the timer ends.

    • addTimelineHandler

      public Effect addTimelineHandler(nl.colorize.util.animation.Timeline timeline, Consumer<Float> callback)
      Adds a frame handler that will update the specified timeline during every frame update, then invokes the callback function based on the timeline's new value. The effect will be marked as completed once the timeline ends.

    • addClickHandler

      public Effect addClickHandler(Rect bounds, Runnable handler)

    • addClickHandler

      public Effect addClickHandler(Supplier<Rect> bounds, Runnable handler)

    • addClickHandler

      public Effect addClickHandler(StageNode2D graphic, Runnable handler)

    • addCompletionHandler

      public Effect addCompletionHandler(Runnable handler)

    • stopAfter

      public Effect stopAfter(float duration)
      Adds a handler that will mark the effect as completed once the specified period of time has elapsed.

    • stopAfterAnimation

      public Effect stopAfterAnimation(Sprite sprite)
      Adds a handler that will mark the effect as completed once the specified sprite animation has ended.

    • stopIf

      public Effect stopIf(BooleanSupplier condition)
      Adds a handler that will mark the effect as completed once the specified condition is met.

    • stopNow

      public Effect stopNow()
      Adds a handler that will mark the effect as completed during the next frame update.

    • stopNever

      public Effect stopNever()
      Adds a handler that will always return false, and will therefore make the effect continue indefinitely.

    • linkGraphics

      public Effect linkGraphics(StageNode2D... graphics)
      Links existing graphics to this effect. This means the graphics will be removed from stage when the effect has completed.

    • removeAfterwards

      @Deprecated public Effect removeAfterwards(StageNode2D... graphics)
      Deprecated.
      Use linkGraphics(StageNode2D...) instead.
      Links existing graphics to this effect. This means the graphics will be removed from stage when the effect has completed.

    • update

      public void update(SceneContext context, float deltaTime)
      Description copied from interface: Scene
      Called during every frame update for as long as the scene is active. deltaTime indicates the elapsed time since the last frame, in seconds.
      Specified by:
      update in interface Scene

    • end

      public void end(SceneContext context)
      Description copied from interface: Scene
      Clean-up logic that is performed every time the scene ends.

      This method is optional, the default implementation does nothing.

      Specified by:
      end in interface Scene

    • isCompleted

      public boolean isCompleted()
      Description copied from interface: Scene
      Indicates the scene has been completed and no longer wishes to receive frame updates.

      If this scene is the currently active scene, it might not actually end until a new scene is requested.

      If this scene is a completed sub-scene, meaning there is a parent scene which is still active, this sub-scene will end after the current frame.

      Specified by:
      isCompleted in interface Scene

    • withLinkedGraphics

      @Deprecated public void withLinkedGraphics(Consumer<StageNode2D> callback)
      Deprecated.

    • withLinkedGraphics

      @Deprecated public <T extends StageNode2D> void withLinkedGraphics(Class<T> type, Consumer<T> callback)
      Deprecated.

    • attach

      public Effect attach(SceneContext context)
      Attaches this effect to the specified scene context. Using this method is identical to sceneContext.attach(effect), but is more readable when creating effects using the fluent API.

    • forFrameHandler

      public static Effect forFrameHandler(Updatable action)
      Creates an effect that will use the specified callback every frame for as long the effect is active.

    • forFrameHandler

      public static Effect forFrameHandler(Runnable action)
      Creates an effect that will use the specified callback every frame for as long the effect is active.

    • delay

      public static Effect delay(float duration, Runnable action)
      Creates an effect that will first wait for the specified period of time, and will then perform an action.

    • forTimeline

      public static Effect forTimeline(nl.colorize.util.animation.Timeline timeline, Consumer<Float> callback)
      Creates an effect that will invoke a callback function based on the timeline's current value. The effect is completed once the timeline has reached the end.

    • forClickHandler

      public static Effect forClickHandler(StageNode2D graphic, Runnable handler)

    • forX

      public static Effect forX(StageNode2D graphic, nl.colorize.util.animation.Timeline timeline)

    • forY

      public static Effect forY(StageNode2D graphic, nl.colorize.util.animation.Timeline timeline)

    • forSpriteRotation

      public static Effect forSpriteRotation(Sprite sprite, float duration)
      Shorthand for creating an effect that rotates a sprite.

    • forSpriteScale

      public static Effect forSpriteScale(Sprite sprite, nl.colorize.util.animation.Timeline timeline)
      Shorthand for creating an effect that scales a sprite based on the specified timeline.

    • forSpriteAlpha

      public static Effect forSpriteAlpha(Sprite sprite, nl.colorize.util.animation.Timeline timeline)
      Shorthand for creating an effect that modifies the sprite's alpha value based on a timeline.

    • scaleToFit

      public static Effect scaleToFit(Sprite sprite, Canvas canvas, boolean uniform)
      Changes a sprite's scale until it fits the canvas. The uniform parameter controls how the sprite should handle situations where the aspect ratio of bound differs from the sprite's own aspect ratio. When true, the sprite's horizontal and vertical scale will always be set to the same values. When false, they can be different, meaning the sprite could appear as stretched or squashed in certain situations.

    • forPrimitiveAlpha

      public static Effect forPrimitiveAlpha(Primitive primitive, nl.colorize.util.animation.Timeline timeline)
      Shorthand for creating an effect that modifies the primitive's alpha value based on a timeline.

    • forTextAlpha

      public static Effect forTextAlpha(Text text, nl.colorize.util.animation.Timeline timeline)
      Shorthand for creating an effect that modifies the text's alpha value based on a timeline.

    • forTextAppear

      public static Effect forTextAppear(Text text, float duration)
      Shorthand for creating an effect that will make the text slowly appear over time, with more and more characters appearing on screen over time until the entire text is shown.