/traderous

-- 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
}