/spacey

-- Class: Sprite

-- A sprite receives all update-related events and draws

-- itself onscreen with its draw() method. It is defined

-- by a rectangle; nothing it draws should be outside that

-- rectangle.

--

-- In most cases, you don't want to create a sprite directly.

-- Instead, you'd want to use a subclass tailored to your needs.

-- Create a new subclass if you need to heavily customize how a 

-- sprite is drawn onscreen.

--

-- If you don't need something to display onscreen, just

-- to listen to updates, set the sprite's visible property to false.

--

-- Extends:

--		<Class>

--

-- Event: onUpdate

-- Called once each frame, with the elapsed time since the last frame in seconds.

--

-- Event: onBeginFrame

-- Called once each frame like onUpdate, but guaranteed to fire before any others' onUpdate handlers.

--

-- Event: onEndFrame

-- Called once each frame like onUpdate, but guaranteed to fire after all others' onUpdate handlers.

--

-- Event: onCollide

-- Called when the sprite intersects another during a collide() call. When a collision is detected,

-- this event occurs for both sprites. The sprite is passed three arguments: the other sprite, the

-- horizontal overlap, and the vertical overlap between the other sprite, in pixels.

Sprite = Class:extend

{

	-- Property: active

	-- If false, the sprite will not receive an update-related events.

	active = true,

	-- Property: visible

	-- If false, the sprite will not draw itself onscreen.

	visible = true,

	-- Property: solid

	-- If false, the sprite will never be eligible to collide with another one.

	-- It will also never displace another one.

	solid = true,

	-- Property: x

	-- Horizontal position in pixels. 0 is the left edge of the window.

	x = 0,

	-- Property: y

	-- Vertical position in pixels. 0 is the top edge of the window.

	y = 0,

	-- Property: width

	-- Width in pixels.

	-- Property: height

	-- Height in pixels.

	-- Property: rotation

	-- Rotation of drawn sprite in radians. This does not affect the bounds

	-- used during collision checking.

	rotation = 0,

	-- Property: velocity

	-- Motion either along the x or y axes, or rotation about its center, in

	-- pixels per second.

	velocity = { x = 0, y = 0, rotation = 0 },

	-- Property: minVelocity

	-- No matter what else may affect this sprite's velocity, it

	-- will never go below these numbers.

	minVelocity = { x = - math.huge, y = - math.huge, rotation = - math.huge },

	-- Property: maxVelocity

	-- No matter what else may affect this sprite's velocity, it will

	-- never go above these numbers.

	maxVelocity = { x = math.huge, y = math.huge, rotation = math.huge },

	-- Property: acceleration

	-- Acceleration along the x or y axes, or rotation about its center, in

	-- pixels per second squared.

	acceleration = { x = 0, y = 0, rotation = 0 },

	-- Property: drag

	-- This property is only active when the related acceleration is 0. In those

	-- instances, it applies acceleration towards 0 for the given property. i.e.

	-- when the velocity is positive, it applies a negative acceleration.

	drag = { x = 0, y = 0, rotation = 0 },

	-- Property: scale

	-- This affects how the sprite is drawn onscreen. e.g. a sprite with scale 2 will

	-- display twice as big. Scaling is centered around the sprite's center. This has

	-- no effect on collision detection.

	scale = 1,

	-- Property: distort

	-- This allows you to scale a sprite in a distorted fashion by defining ratios

	-- between x and y scales.

	distort = { x = 1, y = 1 },

	-- Property: flipX

	-- If set to true, then the sprite will draw flipped horizontally.

	flipX = false,

	-- Property: flipY

	-- If set to true, then the sprite will draw flipped vertically.

	flipY = false,

	-- Property: alpha

	-- This affects the transparency at which the sprite is drawn onscreen. 1 is fully

	-- opaque; 0 is completely transparent.

	alpha = 1,

	-- Property: tint

	-- This tints the sprite a color onscreen. This goes in RGB order; each number affects

	-- how that particular channel is drawn. e.g. to draw the sprite in red only, set tint to

	-- { 1, 0, 0 }.

	tint = { 1, 1, 1 },

	-- Method: die

	-- Makes the sprite totally inert. It will not receive

	-- update events, draw anything, or be collided.

	--

	-- Arguments:

	--		none

	--

	-- Returns:

	-- 		nothing

	die = function (self)

		self.active = false

		self.visible = false

		self.solid = false

	end,

	-- Method: revive

	-- Makes this sprite completely active. It will receive

	-- update events, draw itself, and be collided.

	--

	-- Arguments:

	--		none

	--

	-- Returns:

	-- 		nothing

	revive = function (self)

		self.active = true

		self.visible = true

		self.solid = true

	end,

	-- Method: intersects

	-- Returns whether a point or rectangle intersects this sprite.

	--

	-- Arguments:

	--		x - top left horizontal coordinate

	--		y - top left vertical coordinate

	--		width - width of the rectangle, omit for points

	--		height - height of the rectangle, omit for points

	--

	-- Returns:

	--		boolean

	intersects = function (self, x, y, width, height)

		return self.x < x + (width or 0) and self.x + self.width > x and

			   self.y < y + (height or 0) and self.y + self.height > y

	end,

	-- Method: overlap

	-- Returns the horizontal and vertical overlap of this sprite

	-- and a rectangle. This ignores the sprite's <solid> property

	-- and does not trigger any <onCollide> events.

	--

	-- Arguments:

	--		x - top left horizontal coordinate

	--		y - top left vertical coordinate

	--		width - width of the rectangle

	--		height - height of the rectangles

	--

	-- Returns:

	--		Two numbers: horizontal overlap in pixels, and vertical overlap in pixels.

	overlap = function (self, x, y, width, height)

		local selfRight = self.x + self.width

		local selfBottom = self.y + self.height

		local right = x + width

		local bottom = y + height

		-- this is cribbed from

		-- http://frey.co.nz/old/2007/11/area-of-two-rectangles-algorithm/

		if self.x < right and selfRight > x and

		   self.y < bottom and selfBottom > y then

			return math.min(selfRight, right) - math.max(self.x, x),

				   math.min(selfBottom, bottom) - math.max(self.y, y)

		else

			return 0, 0

		end

	end,

	-- Method: collide

	-- Checks whether this sprite collides with other <Sprite>s ad <Group>s. If a collision is detected,

	-- onCollide() is called on both this sprite and the one it collides with, passing

	-- the amount of horizontal and vertical overlap between the sprites in pixels.

	--

	-- Arguments:

	-- 		... - any number of <Sprite>s or <Group>s to collide with.

	--

	-- Returns:

	--		nothing

	collide = function (self, ...)

		Collision:check(self, ...)

	end,

	-- Method: displace

	-- Displaces another sprite or group so that it no longer overlaps this one.

	-- This by default seeks to move the other sprite the least amount possible.

	-- You can give this function a hint about which way it ought to move the other

	-- sprite (e.g. by consulting its current motion) through the two optional

	-- arguments. A single displace() call will *either* move the other sprite

	-- horizontally or vertically, not along both axes.

	--

	-- This does *not* cause onCollide events to occur on the sprites.

	--

	-- Arguments:

	--		other - sprite or group to displace

	-- 		xHint - force horizontal displacement in one direction, uses direction constants, optional

	--		yHint - force vertical displacement in one direction, uses direction constants, optional

	--

	-- Returns:

	--		nothing

	displace = function (self, other, xHint, yHint)	

		if not self.solid or self == other or not other.solid then return end

		if STRICT then assert(other:instanceOf(Sprite), 'asked to displace a non-sprite') end

		local xChange = 0

		local yChange = 0

		if other.sprites then

			-- handle groups

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

				self:displace(spr, xHint, yHint)

			end

		else

			-- handle sprites

			local xOverlap, yOverlap = self:overlap(other.x, other.y, other.width, other.height)

			-- resolve horizontal overlap

			if xOverlap ~= 0 then

				local leftMove = (other.x - self.x) + other.width

				local rightMove = (self.x + self.width) - other.x

				if xHint == LEFT then

					xChange = - leftMove

				elseif xHint == RIGHT then

					xChange = rightMove

				else

					if leftMove < rightMove then

						xChange = - leftMove

					else

						xChange = rightMove

					end

				end

			end

			-- resolve vertical overlap

			if yOverlap ~= 0 then

				local upMove = (other.y - self.y) + other.height

				local downMove = (self.y + self.height) - other.y

				if yHint == UP then

					yChange = - upMove

				elseif yHint == DOWN then

					yChange = downMove

				else

					if upMove < downMove then

						yChange = - upMove

					else

						yChange = downMove

					end

				end

			end

			-- choose the option that moves the other sprite the least

			if math.abs(xChange) > math.abs(yChange) then

				other.y = other.y + yChange

			else

				other.x = other.x + xChange

			end

		end

	end,

	-- Method: push

	-- Moves another sprite as if it had the same motion properties as this one.

	--

	-- Arguments:

	--		other - other sprite to push

	--		elapsed - elapsed time to simulate, in seconds

	--

	-- Returns:

	--		nothing

	push = function (self, other, elapsed)

		other.x = other.x + self.velocity.x * elapsed

		other.y = other.y + self.velocity.y * elapsed

	end,

	-- Method: distanceTo

	-- Returns the distance from this sprite to either another sprite or 

	-- an arbitrary point. This uses the center of sprites to calculate the distance.

	--

	-- Arguments:

	--		Can be either one argument, a sprite (or any other table with x

	--		and y properties), or two arguments, which correspond to a point.

	--

	-- Returns:

	--		distance in pixels

	distanceTo = function (self, ...)

		local arg = {...}

		local midX = self.x + self.width / 2

		local midY = self.y + self.width / 2

		if #arg == 1 then

			local spr = arg[1]

			if STRICT then

				assert(type(spr.x) == 'number' and type(spr.y) == 'number', 'asked to calculate distance to an object without numeric x and y properties')

			end

			local sprX = spr.x + spr.width / 2

			local sprY = spr.y + spr.height / 2

			return math.sqrt((midX - sprX)^2 + (midY - sprY)^2)

		else

			return math.sqrt((midX - arg[1])^2 + (midY - arg[2])^2)

		end

	end,

	startFrame = function (self, elapsed)

		if self.onStartFrame then self:onStartFrame(elapsed) end

	end,

	update = function (self, elapsed)

		local vel = self.velocity

		local acc = self.acceleration

		local drag = self.drag

		local minVel = self.minVelocity

		local maxVel = self.maxVelocity

		-- check existence of properties

		if STRICT then

			assert(vel, 'active sprite has no velocity property')

			assert(acc, 'active sprite has no acceleration property')

			assert(drag, 'active sprite has no drag property')

			assert(minVel, 'active sprite has no minVelocity property')

			assert(maxVel, 'active sprite has no maxVelocity property')

		end

		vel.x = vel.x or 0

		vel.y = vel.y or 0

		vel.rotation = vel.rotation or 0

		-- physics

		if vel.x ~= 0 then self.x = self.x + vel.x * elapsed end

		if vel.y ~= 0 then self.y = self.y + vel.y * elapsed end

		if vel.rotation ~= 0 then self.rotation = self.rotation + vel.rotation * elapsed end

		if acc.x and acc.x ~= 0 then

			vel.x = vel.x + acc.x * elapsed

		else

			if drag.x then

				if vel.x > 0 then

					vel.x = vel.x - drag.x * elapsed

					if vel.x < 0 then vel.x = 0 end

				elseif vel.x < 0 then

					vel.x = vel.x + drag.x * elapsed

					if vel.x > 0 then vel.x = 0 end

				end

			end

		end

		if acc.y and acc.y ~= 0 then

			vel.y = vel.y + acc.y * elapsed

		else

			if drag.y then

				if vel.y > 0 then

					vel.y = vel.y - drag.y * elapsed

					if vel.y < 0 then vel.y = 0 end

				elseif vel.y < 0 then

					vel.y = vel.y + drag.y * elapsed

					if vel.y > 0 then vel.y = 0 end

				end

			end

		end

		if acc.rotation and acc.rotation ~= 0 then

			vel.rotation = vel.rotation + acc.rotation * elapsed

		else

			if drag.rotation then

				if vel.rotation > 0 then

					vel.rotation = vel.rotation - drag.rotation * elapsed

					if vel.rotation < 0 then vel.rotation = 0 end

				elseif vel.rotation < 0 then

					vel.rotation = vel.rotation + drag.rotation * elapsed

					if vel.rotation > 0 then vel.rotation = 0 end

				end

			end

		end

		if minVel.x and vel.x < minVel.x then vel.x = minVel.x end

		if maxVel.x and vel.x > maxVel.x then vel.x = maxVel.x end

		if minVel.y and vel.y < minVel.y then vel.y = minVel.y end

		if maxVel.y and vel.y > maxVel.y then vel.y = maxVel.y end

		if minVel.rotation and vel.rotation < minVel.rotation then vel.rotation = minVel.rotation end

		if maxVel.rotation and vel.rotation > maxVel.rotation then vel.rotation = maxVel.rotation end

		if self.onUpdate then self:onUpdate(elapsed) end

	end,

	endFrame = function (self, elapsed)

		if self.onEndFrame then self:onEndFrame(elapsed) end

	end,

	draw = function (self, x, y)

		-- subclasses do interesting things here

	end,

	collidedWith = function (self, other, xOverlap, yOverlap)

		if self.onCollide then self:onCollide(other, xOverlap, yOverlap) end

	end

}