Class ParticleEmitter
Parent: Animation
The ParticleEmitter is one of the most complex classes in the API. If you’re not familiar with using regular particle emitters from the normal TSC editor, you probably want to go there first and experiment with them, because everything you need to adjust there needs to be adjusted for dynamically created particle emitters as well--with the difference that in the editor you have a nice UI assisting you, whereelse for the dynamically created particle emitters you have to know what to set and what not to set. Particle emitters can be quite hairy beasts, so I recommend you to often load your level and test what your particle emitter will look like, e.g. by registering for Alex’s Jump event.
Particle emitters can be used in two ways: The usual way, which means periodically issueing a defined number of particles at a time. Such a particle emitter can be created by setting the emitter’s time to live on that particle emitter. If you want more finergrained control about what is going on, you can ignore that setting and call the #emit method directly. Each call to that method will cause the particle emitter to exactly once emit particles according to its configuration.
A good number of setter methods accept a Range instead of a singular fixed parameter, which allows you to specify a range of valid values for a given option. For instance, the #time_to_live= methods allows you to define the ilfespan of particles emitted at a time. Instead of setting this to a single, definite value (which you can do if you want to), you can configure it to a Range like 1..2, which means that the TTL will regularyly be 1.5, but at minimum 1.0 and at maximum 2.0, so that the particles emitted all are a little different.
Note that, in contrast to all other objects in TSC, it is possible to set a particle emitter’s Z coordinate, making it possible to appear in front of Alex or other sprites.
Also note that ParticleEmitter is not a subclass of Sprite (the particle emitter doesn’t show up on the screen itself, just its emitted particles) and the methods defined there don’t apply here therefore.
Example
The following example shows how to create a particle emitter from the scripting API. The object with UID 14 is assumed to be a box you can jump against.
UIDS[14].on_activate do part = ParticleEmitter.new(100, -100, 100, 100) part.quota = 4 part.image_filename = "animation/particles/snowflake_1.png" part.emitter_time_to_live = -1 part.show end
When the player jumps against the box, the game will create a particle emitter at position (100|-100) with a size of 100x100 (all pixel values). The emitter will emit snowflakes as per the image file in animation/particles/snowflake_1.png below the pixmaps/ directory, four flakes at a time. It will do so infinitely (-1).
Class Methods
new
new( x, y [, width [, height ] ] ) → a_particle_emitter
Creates a new particle emitter. It won’t emit particles by default, you first have to adjust the emitter with the various setter methods, and when you’ve done this you can either call #emit which will gives you absolute control over each emitted particle, or use #emitter_time_to_live= to make the emitter emit particles automatically.
Instance Methods
const_rotation_x
const_rotation_x() → a_range
TODO: Docs.
const_rotation_x=
const_rotation_x=( range )
TODO: Docs.
const_rotation_y
const_rotation_y() → a_range
TODO: Docs.
const_rotation_y=
const_rotation_y=( range )
TODO: Docs.
const_rotation_z
const_rotation_z() → a_range
TODO: Docs.
const_rotation_z=
const_rotation_z=( range )
TODO: Docs.
emit
emit()
Emit a single particle (or multiple ones if the #quota is set accordingly). Usually you want to use #emitter_time_to_live= to make the emitter act automatically, but this method allows to retain full control about the particle emitter.
emitter_time_to_live
emitter_time_to_live() → a_float
The number of seconds the emitter will emit particles. This is independant from the TTL of the respective particles.
emitter_time_to_live=
emitter_time_to_live=( value )
Sets the emitter’s time to live (TTL). After the specified number of seconds has passed, the emitter will stop emitting particles. This value is independant from the TTL of the respective particles, which can be set with the Animation#time_to_live= method.
gravity_x
gravity_x() → a_range
TODO: Docs.
gravity_x=
gravity_x=( range )
TODO: Docs.
gravity_y
gravity_y() → a_range
TODO: Docs.
gravity_y=
gravity_y=( range )
TODO: Docs.
image_filename
image_filename() → a_string
The filename of the image of the particles emitted by this emitter, relative to the pixmaps/ directory.
image_filename=
image_filename=( path )
Sets the filename of the image to use for particles generated by the particle emitter, relative to the pixmaps/ directory.
inspect
inspect() → a_string
Human-readable description.
quota
quota() → an_integer
TODO: Docs.
quota=
quota=( value )
Sets the number of particles emitted at one time.
scale
scale() → a_range
TODO: Docs.
scale=
scale=( range )
TODO: Docs.
speed
speed() → a_range
TODO: Docs.
speed=
speed=( range )
TODO: Docs.
z=
z=( val )
TODO: Docs.