/spacey

-- Class: Emitter

-- An emitter periodically emits sprites with varying properties --

-- for example, velocity. These are set with the emitter's min and

-- max properties. For example, you could set the x velocity of

-- particles to range between -100 and 100 with these statements:

--

-- > emitter.min.velocity.x = -100

-- > emitter.max.velocity.x = 100

--

-- Properties can descend two levels deep at most.

--

-- You can specify any property in min and max, and it will be set

-- on sprites as they are emitted. Mins and maxes can only be used

-- with numeric properties.

--

-- Particles when emitted will appear at a random spot inside the

-- rectangle defined by the emitter's x, y, width, and height

-- properties.

--

-- Because emitters are <Group> subclasses, all particles appear at

-- the same z index onscreen. This also means that setting active,

-- visible, and solid properties on the emitter will affect all particles.

--

-- Any sprite may be used as a particle. When a sprite is added as

-- a particle, its die() method is called. When emitted, revive() is

-- called on it. If you want a particle to remain invisible after being

-- emitted, for example, then write an onEmit method on your sprite to do so.

--

-- Extends:

--              <Group>

--

-- Event: onEmit

-- Called on both the parent emitter and the emitted sprite

-- when it is emitted. If multiple particles are emitted at once, the

-- emitter will receive multiple onEmit events.

 

Emitter = Group:extend{

        -- Property: x

        -- The x coordinate of the upper-left corner of the rectangle where particles may appear.

        x = 0,

 

        -- Property: y

        -- The y coordinate of the upper-left corner of the rectangle where particles may appear.

        y = 0,

 

        -- Property: width

        -- The width of the rectangle where particles may appear.

        width = 0,

 

        -- Property: height

        -- The height of the retangle where particles may appear.

        height = 0,

 

        -- Property: emitting

        -- Boolean whether this emitter is actually emitting particles.

        emitting = true,

        

        -- Property: period

        -- How long, in seconds, the emitter should wait before emitting.

        period = math.huge,

 

        -- Property: emitCount

        -- How many particles to emit at once.

        emitCount = 1,

 

        -- Property: min

        -- Minimum numeric properties for particles.

        min = {},

 

        -- Property: max

        -- Maximum numeric properties for particles.

        max = {},

 

        -- Property: emitTimer

        -- Used to keep track of when the next emit should take place.

        -- To restart the timer, set it to 0. To immediately force a particle

        -- to be emitted, set it to the emitter's period property. (Although

        -- you should probably call emit() instead.)

        emitTimer = 0,

 

        -- which particle to emit next

        _emitIndex = 1,

 

        -- Method: loadParticles

        -- Creates a number of particles to use based on a class.

        -- This calls new() on the particle class with no arguments.

        --

        -- Arguments:

        --              class - class object to instantiate

        --              count - number of particles to create

        --

        -- Returns:

        --              nothing

 

        loadParticles = function (self, class, count)

                for i = 1, count do

                        self:add(class:new())

                end

        end,

 

        -- Method: emit

        -- Emits one or more particles. This ignores the emitting property.

        -- If no particles are ready to be emitted, this does nothing. 

        --

        -- Arguments:

        --              count - how many particles to emit, default 1

        --

        -- Returns:

        --              emitted particle

 

        emit = function (self, count)

                count = count or 1

 

                if #self.sprites == 0 then return end

 

                for i = 1, count do

                        local emitted = self.sprites[self._emitIndex]

                        self._emitIndex = self._emitIndex + 1

                        

                        if self._emitIndex > #self.sprites then self._emitIndex = 1 end

 

                        -- revive it and set properties

 

                        emitted:revive()

                        emitted.x = math.random(self.x, self.x + self.width)

                        emitted.y = math.random(self.y, self.y + self.height)

 

                        for key, _ in pairs(self.min) do

                                if self.max[key] then

                                        -- simple case, single value

                                        

                                        if type(self.min[key]) == 'number' then

                                                emitted[key] = self.min[key] + math.random() * (self.max[key] - self.min[key])

                                        end

 

                                        -- complicated case, table

 

                                        if type(self.min[key]) == 'table' then

                                                for subkey, _ in pairs(self.min[key]) do

                                                        if type(self.min[key][subkey]) == 'number' then

                                                                emitted[key][subkey] = self.min[key][subkey] + math.random() *

                                                                                                           (self.max[key][subkey] - self.min[key][subkey])

                                                        end

                                                end

                                        end

                                end

                        end

        

                        if emitted.onEmit then emitted:onEmit(self) end

                        if self.onEmit then self:onEmit(emitted) end

                end

        end,

 

        -- Method: explode

        -- This emits many particles simultaneously then immediately stops any further

        -- emissions. If you want to keep the emitter going, call emitter.emit(#emitter.sprites).

        --

        -- Arguments:

        --              count - number of particles to emit, defaults to all of them

        --

        -- Returns:

        --              nothing

 

        explode = function (self, count)

                count = count or #self.sprites

 

                self:emit(count)

                self.emitting = false

        end,

 

        -- Method: extinguish

        -- This immediately calls die() on all particles, then the emitter itself.

        -- This differs from a regular die() call in that if you call revive() on the

        -- emitter later, particles will not appear where they last left off.

        --

        -- Arguments:

        --              none

        --

        -- Returns:

        --              nothing

 

        extinguish = function (self)

                for _, spr in pairs(self.sprites) do

                        spr:die()

                end

 

                self:die()

        end,

 

        update = function (self, elapsed)

                if not self.active then return end

 

                if self.emitting then

                        self.emitTimer = self.emitTimer + elapsed

 

                        if self.emitTimer > self.period then

                                self:emit(self.emitCount)

                                self.emitTimer = self.emitTimer - self.period

                        end

                end

 

                Group.update(self, elapsed)

        end,

 

        add = function (self, sprite)

                sprite:die()

                Group.add(self, sprite)

        end,

 

        __tostring = function (self)

                local result = 'Emitter (x: ' .. self.x .. ', y: ' .. self.y ..

                                           ', w: ' .. self.width .. ', h: ' .. self.height .. ', '

 

                if self.emitting then

                        result = result .. 'emitting with period ' .. self.period .. ', '

                else

                        result = result .. 'not emitting, '

                end

 

                return result

        end

}