animator.lua

--- Convenience module for chaining animations or setting a specific frame to show
-- once specific animations are finished
-- @usage
-- local animator = require("animator")
-- 
-- function init(self)
-- 	self.animator = animator.create("#sprite")
-- 	self.animator.set_done_animation("attack", "idle")
-- 	self.animator.set_done_animation("idle", "look")
-- 	self.animator.set_done_animation("look", "idle")
-- end
-- 
-- function on_input(self, action_id, action)
-- 	if action_id == hash("attack") and action.released then
-- 		self.animator.play("attack")
-- 	end
-- end
-- 
-- function on_message(self, message_id, message, sender)
-- 	self.animator.on_message(message_id, message)
-- end


local M = {}

local HASH_ANIMATION_DONE = hash("animation_done")
local HASH_PLAY_ANIMATION = hash("play_animation")


--- Create a new animator instance
-- @param url URL this animator belongs to. This URL will be used when posting
-- play_animation messages
-- @return The animator instance
function M.create(url)
	assert(url, "You must provide a URL to a a sprite instance or a game object with a sprite")
	local animator = {}
	
	local animations = {}
	
	--- Ensure that a provided value is a hash
	-- @param v The value to convert to a hash. If it's a non userdata
	-- value it will be converted using the hash() function. If it's
	-- already a userdata value it is assumed to be a hash value
	-- @return The value converted to a hash 
	local function to_hash(v)
		return type(v) ~= "userdata" and hash(tostring(v)) or v
	end

	--- Set the animation to play once an animation is done
	-- @param animation_id Id of the animation that will trigger another animation once it's done (string|hash)
	-- @param done_animation_id Id of the animation to play (string|hash)
	function animator.set_done_animation(animation_id, done_animation_id)
		animations[hash_to_hex(to_hash(animation_id))] = to_hash(done_animation_id)
	end
	
	--- Pass along any on_message calls received by the game object to this function
	-- to automatically deal with playing animations once other animations are finished
	-- @param message_id
	-- @param message
	function animator.on_message(message_id, message)
		if message_id == HASH_ANIMATION_DONE then
			local done_animation_id = animations[hash_to_hex(message.id)] 
			if done_animation_id then
				msg.post(url, HASH_PLAY_ANIMATION, { id = done_animation_id })
			end
		end
	end
	
	--- Play an animation
	-- @param animation_id Id of the animation to play
	function animator.play(animation_id)
		msg.post(url, HASH_PLAY_ANIMATION, { id = to_hash(animation_id) })
	end
	
	return animator
end


return M