Class Emitter

java.lang.Object

de.gurkenlabs.litiengine.entities.Entity

de.gurkenlabs.litiengine.graphics.emitters.Emitter

All Implemented Interfaces:

EntityRenderedListener, EntityRenderListener, IEntity, IRenderable, ITimeToLive, IUpdateable, Tweenable, EventListener

Direct Known Subclasses:

EntityEmitter

public class Emitter
extends Entity
implements IUpdateable, ITimeToLive, IRenderable

Represents an emitter that provides particle effects in the game.

The Emitter class extends Entity and implements the IUpdateable, ITimeToLive, and IRenderable interfaces. It manages the lifecycle, rendering, and behavior of particles, allowing for dynamic visual effects.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Emitter.EmitterFinishedListener	Listener interface for handling emitter completion events.

Field Summary

Fields inherited from class Entity

ANY_MESSAGE

Fields inherited from interface IUpdateable

DEFAULT_UPDATE_PRIORITY

Constructor Summary

Constructors

Constructor	Description
Emitter()	Constructs a new Emitter instance.
Emitter(double originX, double originY)	Constructs a new Emitter instance with the specified origin coordinates.
Emitter(double x, double y, EmitterAttributes emitterData)	Constructs a new Emitter instance with the specified coordinates and emitter data.
Emitter(double x, double y, String emitterXml)	Constructs a new Emitter instance with the specified coordinates and emitter XML configuration.
Emitter(EmitterAttributes emitterData)	Constructs a new Emitter instance with the specified emitter data.
Emitter(Point2D origin)	Constructs a new Emitter instance with the specified origin.
Emitter(Point2D origin, EmitterAttributes emitterData)	Constructs a new Emitter instance with the specified origin and emitter data.
Emitter(Point2D origin, String emitterXml)	Constructs a new Emitter instance with the specified origin and emitter XML configuration.

Method Summary

Modifier and Type	Method	Description
void	activate()	Activates the emitter.
void	addParticle(Particle particle)	Adds a particle to this emitter's list of particles.
protected boolean	canTakeNewParticles()	Checks if the emitter can accept new particles.
protected Particle	createNewParticle()	Creates a new particle based on the emitter's configuration.
EmitterAttributes	data()	Retrieves the emitter data associated with this emitter.
void	deactivate()	Deactivates the emitter.
void	delete()	Deletes this emitter from the game world.
long	getAliveTime()	Retrieves the total alive time of the emitter.
Point2D	getOrigin()	Retrieves the origin point of the emitter.
List<Particle>	getParticles()	Retrieves the list of particles managed by this emitter.
IRenderable	getRenderable(RenderType type)	Retrieves the renderable object associated with the specified render type.
int	getTimeToLive()	Gets the total time to live of this instance.
boolean	isActivated()	Checks if the emitter is currently activated.
boolean	isActivateOnInit()	Checks if the emitter is set to activate on initialization.
boolean	isFinished()	Determines if the emitter has finished its duration.
boolean	isPaused()	Checks whether the emitter is currently paused.
boolean	isStopped()	Checks if the emitter is currently stopped.
void	onFinished(Emitter.EmitterFinishedListener listener)	Registers a listener to be notified when the emitter finishes.
protected boolean	particleCanBeRemoved(Particle particle)	Determines if a particle can be removed from the emitter.
void	removeFinishedListener(Emitter.EmitterFinishedListener listener)	Removes a previously registered finished listener.
void	render(Graphics2D g)	Renders the visual contents of this instance onto the provided graphics context.
void	setEmitterData(EmitterAttributes emitterData)	Sets the emitter data for this emitter.
void	setEmitterData(String emitterXmlPath)	Sets the emitter data for this emitter using an XML configuration file.
void	setPaused(boolean paused)	Sets the paused state of the emitter.
void	setStopped(boolean stopped)	Sets the stopped state of the emitter.
protected void	spawnParticle()	Spawns new particles for the emitter.
boolean	timeToLiveReached()	Time to live reached.
void	togglePaused()	Toggles the paused state of the emitter.
void	toggleStopped()	Toggles the stopped state of the emitter.
void	update()	This method is called by the game loop on all objects that are attached to the loop.
protected void	updateOrigin()	Updates the origin point of the emitter.

Methods inherited from class Entity

actions, addController, addEntityRenderListener, addListener, addTag, addTransformListener, animations, attachControllers, behavior, canRender, detachControllers, getAngle, getBoundingBox, getCenter, getController, getControllers, getEnvironment, getHeight, getLocation, getMapId, getName, getProperties, getRenderType, getTags, getTweenValues, getWidth, getX, getY, hasTag, isLoaded, isVisible, loaded, onActionPerformed, onMessage, onMessage, onRendered, perform, register, removeActionPerformedListener, removed, removeListener, removeListener, removeListener, removeListener, removeListener, removeTag, rendered, rendering, renderWithLayer, sendMessage, setAngle, setController, setHeight, setLocation, setLocation, setMapId, setName, setRenderType, setRenderWithLayer, setSize, setTweenValues, setVisible, setWidth, setX, setY, toString

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface IEntity

scripts

Methods inherited from interface IUpdateable

getUpdatePriority

Constructor Details

Emitter

public Emitter()

Constructs a new Emitter instance.

Initializes the emitter with default settings, including particle collections, renderable mappings, and emitter data. If the EmitterInfo annotation is present on the class, its values are used to configure the emitter's properties.

Emitter

public Emitter(EmitterAttributes emitterData)

Constructs a new Emitter instance with the specified emitter data.

Initializes the emitter using the provided EmitterAttributes, which contains configuration details such as particle type, spawn rate, and emitter duration.

Parameters:

emitterData - the data used to configure this emitter

Emitter

public Emitter(Point2D origin,
 EmitterAttributes emitterData)

Constructs a new Emitter instance with the specified origin and emitter data.

Initializes the emitter at the given origin point and configures it using the provided EmitterAttributes, which contains details such as particle type, spawn rate, and emitter duration.

Parameters:

origin - the origin point where the emitter is located

emitterData - the data used to configure this emitter

Emitter

public Emitter(double x,
 double y,
 EmitterAttributes emitterData)

Constructs a new Emitter instance with the specified coordinates and emitter data.

Initializes the emitter at the given x and y coordinates and configures it using the provided EmitterAttributes, which contains details such as particle type, spawn rate, and emitter duration.

Parameters:

x - the x-coordinate of the emitter's origin

y - the y-coordinate of the emitter's origin

emitterData - the data used to configure this emitter

Emitter

public Emitter(double x,
 double y,
 String emitterXml)

Constructs a new Emitter instance with the specified coordinates and emitter XML configuration.

Initializes the emitter at the given x and y coordinates and configures it using the provided XML file, which contains emitter settings such as particle type, spawn rate, and emitter duration.

Parameters:

x - the x-coordinate of the emitter's origin

y - the y-coordinate of the emitter's origin

emitterXml - the path to the XML file used to configure this emitter

Emitter

public Emitter(Point2D origin,
 String emitterXml)

Constructs a new Emitter instance with the specified origin and emitter XML configuration.

Initializes the emitter at the given origin point and configures it using the provided XML file, which contains emitter settings such as particle type, spawn rate, and emitter duration.

Parameters:

origin - the origin point where the emitter is located

emitterXml - the path to the XML file used to configure this emitter

Emitter

public Emitter(double originX,
 double originY)

Constructs a new Emitter instance with the specified origin coordinates.

Initializes the emitter at the given x and y coordinates, represented as a Point2D.Double.

Parameters:

originX - the x-coordinate of the emitter's origin

originY - the y-coordinate of the emitter's origin

Emitter

public Emitter(Point2D origin)

Constructs a new Emitter instance with the specified origin.

Initializes the emitter at the given origin point, setting its location and preparing it for further configuration or activation.

Parameters:

origin - the origin point where the emitter is located

Method Details

activate

public void activate()

Activates the emitter.

Marks the emitter as activated, sets the activation tick to the current game time, and attaches the emitter to the game loop for updates. If the emitter is already activated, this method does nothing.

addParticle

public void addParticle(Particle particle)

Adds a particle to this emitter's list of particles.

If the emitter is stopped, this method does nothing. Otherwise, the specified particle is added to the internal particle collection for rendering and updates.

Parameters:

particle - the particle to be added to the emitter

deactivate

public void deactivate()

Deactivates the emitter.

This method stops the emitter's activity and resets its state. It clears all particles, resets the alive time, activation tick, and last spawn time, and detaches the emitter from the game loop. If the emitter is not currently activated, this method does nothing.

delete

public void delete()

Deletes this emitter from the game world.

Deactivates the emitter, clears its particles, and removes it from the current environment if one exists. This method ensures that the emitter is no longer active or present in the game.

getAliveTime

public long getAliveTime()

Retrieves the total alive time of the emitter.

This method returns the amount of time, in milliseconds, that the emitter has been active since its activation.

Specified by:

getAliveTime in interface ITimeToLive

Returns:

the alive time of the emitter in milliseconds

data

public EmitterAttributes data()

Retrieves the emitter data associated with this emitter.

The emitter data contains configuration details such as particle type, spawn rate, and other properties that define the emitter's behavior.

Returns:

the EmitterAttributes object for this emitter

getOrigin

public Point2D getOrigin()

Retrieves the origin point of the emitter.

If the origin has not been calculated yet, this method updates the origin based on the emitter's current position and alignment settings.

Returns:

the origin point of the emitter as a Point2D object

updateOrigin

protected void updateOrigin()

Updates the origin point of the emitter.

This method recalculates the origin based on the emitter's current position, width, height, and alignment settings defined in the emitter data.

getRenderable

public IRenderable getRenderable(RenderType type)

Retrieves the renderable object associated with the specified render type.

If the provided render type is RenderType.NONE, this method returns null. Otherwise, it returns the IRenderable instance mapped to the given render type.

Parameters:

type - the render type for which the renderable object is requested

Returns:

the renderable object associated with the specified render type, or null if the type is RenderType.NONE

getParticles

public List<Particle> getParticles()

Retrieves the list of particles managed by this emitter.

Returns a list containing all particles currently associated with this emitter. These particles are used for rendering and updates during the emitter's lifecycle.

Returns:

a list of particles managed by this emitter

isActivateOnInit

public boolean isActivateOnInit()

Checks if the emitter is set to activate on initialization.

Returns a boolean indicating whether the emitter should automatically activate when it is initialized.

Returns:

true if the emitter activates on initialization, false otherwise

isActivated

public boolean isActivated()

Checks if the emitter is currently activated.

Returns a boolean indicating whether the emitter is in an active state.

Returns:

true if the emitter is activated, false otherwise

isFinished

public boolean isFinished()

Determines if the emitter has finished its duration.

This method checks whether the emitter's time-to-live (TTL) is greater than zero and if the TTL has been reached. If both conditions are true, the emitter is considered finished.

Returns:

true if the emitter's duration is complete, false otherwise

isPaused

public boolean isPaused()

Checks whether the emitter is currently paused.

Returns a boolean indicating if the emitter is in a paused state.

Returns:

true if the emitter is paused, false otherwise

setPaused

public void setPaused(boolean paused)

Sets the paused state of the emitter.

This method updates the emitter's paused status to the specified value. When paused, the emitter stops updating its particles and other behaviors.

Parameters:

paused - true to pause the emitter, false to resume it

isStopped

public boolean isStopped()

Checks if the emitter is currently stopped.

Returns a boolean indicating whether the emitter is in a stopped state.

Returns:

true if the emitter is stopped, false otherwise

setStopped

public void setStopped(boolean stopped)

Sets the stopped state of the emitter.

This method updates the emitter's stopped status to the specified value. When stopped, the emitter ceases all activity and updates.

Parameters:

stopped - true to stop the emitter, false to resume it

onFinished

public void onFinished(Emitter.EmitterFinishedListener listener)

Registers a listener to be notified when the emitter finishes.

The specified Emitter.EmitterFinishedListener is added to the list of listeners that will be invoked when the emitter completes its lifecycle.

Parameters:

listener - the listener to be notified when the emitter finishes

removeFinishedListener

public void removeFinishedListener(Emitter.EmitterFinishedListener listener)

Removes a previously registered finished listener.

The specified Emitter.EmitterFinishedListener is removed from the list of listeners that are notified when the emitter finishes.

Parameters:

listener - the listener to be removed

render

public void render(Graphics2D g)

Description copied from interface: IRenderable

Renders the visual contents of this instance onto the provided graphics context.

If an Entity implements this interface, this method will be called right after the entity was rendered from the environment. Allowing for a custom rendering mechanism.

This interface can be implemented in general by anything that should be rendered to the game's screen.

Specified by:

render in interface IRenderable

Parameters:

g - The current graphics object onto which this instance will render its visual contents.

See Also:

• RenderEngine.renderEntity(Graphics2D, de.gurkenlabs.litiengine.entities.IEntity)

setEmitterData

public void setEmitterData(EmitterAttributes emitterData)

Sets the emitter data for this emitter.

This method updates the emitter's configuration using the provided EmitterAttributes. If the provided data is null, the method does nothing.

Parameters:

emitterData - the data used to configure this emitter

setEmitterData

public void setEmitterData(String emitterXmlPath)

Sets the emitter data for this emitter using an XML configuration file.

This method loads the emitter data from the specified XML file and updates the emitter's configuration accordingly.

Parameters:

emitterXmlPath - the path to the XML file containing the emitter data

timeToLiveReached

public boolean timeToLiveReached()

Time to live reached.

Specified by:

timeToLiveReached in interface ITimeToLive

Returns:

true, if successful

togglePaused

public void togglePaused()

Toggles the paused state of the emitter.

This method switches the emitter's paused status between true and false. When paused, the emitter stops updating its particles and other behaviors.

toggleStopped

public void toggleStopped()

Toggles the stopped state of the emitter.

This method switches the emitter's stopped status between true and false. When stopped, the emitter ceases all activity and updates.

getTimeToLive

public int getTimeToLive()

Description copied from interface: ITimeToLive

Gets the total time to live of this instance.

Specified by:

getTimeToLive in interface ITimeToLive

Returns:

The total time to live.

update

public void update()

Description copied from interface: IUpdateable

This method is called by the game loop on all objects that are attached to the loop. It's called on every tick of the loop and the frequency can be configured using the ClientConfiguration.

Specified by:

update in interface IUpdateable

See Also:

• ClientConfiguration.setMaxFps(int)

canTakeNewParticles

protected boolean canTakeNewParticles()

Checks if the emitter can accept new particles.

This method determines whether the current number of particles is less than the maximum allowed particles as defined in the emitter data configuration.

Returns:

true if the emitter can accept new particles, false otherwise

createNewParticle

protected Particle createNewParticle()

Creates a new particle based on the emitter's configuration.

This method generates a particle of the type specified in the emitter's data. The particle's dimensions are determined by the configured width and height. If the particle type is SPRITE, the method ensures the spritesheet is valid before creating the particle. If no specific type is defined, a rectangle particle is created by default.

Returns:

the newly created particle, or null if the particle type is SPRITE and the spritesheet is invalid

particleCanBeRemoved

protected boolean particleCanBeRemoved(Particle particle)

Determines if a particle can be removed from the emitter.

This method checks whether the specified particle has reached its time-to-live (TTL). If the particle's TTL is reached, it is considered eligible for removal.

Parameters:

particle - the particle to check

Returns:

true if the particle's TTL is reached, false otherwise

spawnParticle

protected void spawnParticle()

Spawns new particles for the emitter.

This method generates a number of particles based on the emitter's spawn amount configuration. It ensures that the emitter does not exceed its maximum allowed particles. If a new particle is successfully created, it is added to the emitter's particle list.

classgraphicsapijava