ColorParticle

class pygamelib.gfx.particles.ColorParticle(row: int = 0, column: int = 0, velocity: Vector2D = None, lifespan: int = None, sprixel: ParticleSprixel = None, start_color: Color = None, stop_color: Color = None)

Bases: Particle

This class is an extension of Particle. It adds the possibility to gradually go from a starting color to an end color over time. It is linked with the lifespan of the particle.

__init__(row: int = 0, column: int = 0, velocity: Vector2D = None, lifespan: int = None, sprixel: ParticleSprixel = None, start_color: Color = None, stop_color: Color = None) → None

The constructor takes the following parameters.

Parameters:

row (int) – The initial row position of the particle on the screen.
column (int) – The initial column position of the particle on the screen.
velocity (Vector2D) – The initial velocity of the particle.
lifespan (int) – The particle lifespan in number of movements/turns. A particle with a lifespan of 3 will move for 3 turns before being finished.
sprixel (Sprixel) – The sprixel that represent the particle when drawn on screen.
start_color (Color) – The color of the particle at the beginning of its lifespan.
stop_color (Color) – The color of the particle at the end of its lifespan.

Example:

single_particle = ColorParticle(
    row=5,
    column=5,
    velocity=base.Vector2D(-0.5, 0.0),
    lifespan=10,
    start_color=core.Color(255, 0, 0),
    stop_color=core.Color(0, 255, 0),
)

Methods

`__init__`([row, column, velocity, lifespan, ...])	The constructor takes the following parameters.
`apply_force`(force)	Apply a force to the particle's acceleration vector.
`attach`(observer)	Attach an observer to this instance.
`detach`(observer)	Detach an observer from this instance.
`finished`()	Return True if the particle is done living (i.e its lifespan is lesser or equal to 0).
`handle_notification`(subject[, attribute, value])	A virtual method that needs to be implemented by the observer.
`load`(data)	Load a ColorParticle from a dictionary.
`notify`([modifier, attribute, value])	Notify all the observers that a change occurred.
`render`([sprixel])	Render the particle as a `Sprixel`.
`reset`([row, column, velocity, lifespan])	Reset a particle in its initial state.
`reset_lifespan`([lifespan])	Reset the particle lifespan (including the initial lifespan).
`serialize`()	Serialize a ColorParticle into a dictionary.
`store_screen_position`(row, column)	Store the screen position of the object.
`terminate`()	Terminate a particle, i.e sets its lifespan to -1.
`update`()	The update method perform the calculations required to process the new particle position.

Attributes

`column`	Access and set the column property.
`row`	Access and set the row property.
`screen_column`	A property to get/set the screen column.
`screen_row`	A property to get/set the screen row.
`x`	Access and set the x property.
`y`	Access and set the y property.

apply_force(force: Vector2D) → None

Apply a force to the particle’s acceleration vector.

You are more likely to apply forces to all particles of an emitter through the apply_force() method of the emitter class.

Parameters:: force (Vector2D) – The force to apply.

Example:

gravity = Vector2D(-0.2, 0.0)
my_particle.apply_force(gravity)

attach(observer)

Attach an observer to this instance. It means that until it is detached, it will be notified every time that a notification is issued (usually on changes).

An object cannot add itself to the list of observers (to avoid infinite recursions).

Parameters:: observer (PglBaseObject) – An observer to attach to this object.
Returns:: True or False depending on the success of the operation.
Return type:: bool

Example:

myboard = Board()
screen = Game.instance().screen
# screen will be notified of all changes in myboard
myboard.attach(screen)

property column: Access and set the column property. Equivalent to the x property.

detach(observer)

Detach an observer from this instance. If observer is not in the list this returns False.

Parameters:: observer (PglBaseObject) – An observer to detach from this object.
Returns:: True or False depending on the success of the operation.
Return type:: bool

Example:

# screen will no longer be notified of the changes in myboard.
myboard.detach(screen)

finished() → bool

Return True if the particle is done living (i.e its lifespan is lesser or equal to 0). It returns False otherwise.

Return type:: bool

Example:

if not my_particle.finished():
    my_particle.update()

handle_notification(subject, attribute=None, value=None)

A virtual method that needs to be implemented by the observer. By default it does nothing but each observer needs to implement it if something needs to be done when notified.

This method always receive the notifying object as first parameter. The 2 other parameters are optional and can be None.

You can use the attribute and value as you see fit. You are free to consider attribute as an event and value as the event’s value.

Parameters:

subject (PglBaseObject) – The object that has changed.
attribute (str) – The attribute that has changed, it is usually a “FQDN style” string. This can be None.
value (Any) – The new value of the attribute. This can be None.

classmethod load(data)

Load a ColorParticle from a dictionary.

Parameters:: data (dict) – The dictionary to load from
Returns:: The loaded ColorParticle
Return type:: ColorParticle

Example:

particle = ColorParticle.load( json.load( open("particle.json") ) )

notify(modifier=None, attribute: str = None, value: Any = None) → None

Notify all the observers that a change occurred.

Parameters:

modifier (PglBaseObject) – An optional parameter that identify the modifier object to exclude it from the notified objects.
attribute (str) – An optional parameter that identify the attribute that has changed.
value (Any) – An optional parameter that identify the new value of the attribute.

Example:

# This example is silly, you would usually notify other objects from inside
# an object that changes a value that's important for the observers.
color = Color(255,200,125)
color.attach(some_text_object)
color.notify()

render(sprixel: Sprixel = None)

Render the particle as a Sprixel. This method is called by the ParticleEmitter render_to_buffer method.

It takes a Sprixel as a parameter. This Sprixel is given by the ParticleEmitter.render_to_buffer() method and if it is not None, the particle will render itself into that Sprixel and return it.

Important

This method must be called after everything else as rendered or else there will be Sprixel that will be overwritten during their rendering cycle. Other elements could also have their Sprixel corrupted and replaced by the particle’s one.

Parameters:: sprixel (Sprixel) – A sprixel already rendered in the screen buffer.

Example:

p = my_particle
buffer[p.row][p.column] = p.render(buffer[p.row][p.column])

reset(row: int = 0, column: int = 0, velocity: Vector2D = None, lifespan: int = None)

Reset a particle in its initial state. This is particularly useful for the reuse of particles.

This method takes almost the same parameters than the constructor.

Parameters:

row (int) – The initial row position of the particle on the screen.
column (int) – The initial column position of the particle on the screen.
velocity (Vector2D) – The initial velocity of the particle.
lifespan (int) – The particle lifespan in number of movements/turns. A particle with a lifespan of 3 will move for 3 turns before being finished.

Example:

single_particle.reset(
    row=5,
    column=5,
    velocity=base.Vector2D(-0.5, 0.0),
    lifespan=10,
)

reset_lifespan(lifespan: int = 20) → None

Reset the particle lifespan (including the initial lifespan).

Parameters:: lifespan (int) – The particle lifespan in number of movements/turns.

Example:

my_particle.reset_lifespan(10)

property row: Access and set the row property. Equivalent to the y property.

property screen_column: int

A property to get/set the screen column.

Parameters:: value (int) – the screen column
Return type:: int

property screen_row: int

A property to get/set the screen row.

Parameters:: value (int) – the screen row
Return type:: int

serialize()

Serialize a ColorParticle into a dictionary.

Returns:: The class as a dictionary
Return type:: dict

Example:

json.dump( particle.serialize() )

store_screen_position(row: int, column: int) → bool

Store the screen position of the object.

This method is automatically called by Screen.place().

Parameters:

row (int) – The row (or y) coordinate.
column (int) – The column (or x) coordinate.

Example:

an_object.store_screen_coordinate(3,8)

terminate() → None

Terminate a particle, i.e sets its lifespan to -1.

In that case the ParticleEmitter and ParticlePool will recycle it. That is IF you are managing the particle through an emitter and/or a pool of course.

Example:

p = my_particle
if p.row >= screen,height or p.column >= screen.width:
    p.terminate()

update()

The update method perform the calculations required to process the new particle position. It mainly adds the acceleration to the velocity vector and update the position accordingly.

After calling update() the acceleration is “consumed” in the velocity and therefor reset.

The update() method takes no parameters and returns nothing.

Example:

my_particle.update()

property x: Access and set the x property. Equivalent to the column property.

property y: Access and set the y property. Equivalent to the row property.