Top

Secret Chronicles of the Scripting API documentation

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.