examples/animation/animation_states/example/knight.script

-- ============================================================================
-- KNIGHT ANIMATION STATE MACHINE - Beginner Friendly Example
-- ============================================================================
-- This script demonstrates how to create a character animation system using
-- a simple implementation of a Finite State Machine (FSM) in Defold.

-- Input action hashes - these connect keyboard/gamepad buttons to our code
-- In Defold, we use hash() to convert strings to efficient identifiers
local INPUT = {
	JUMP = hash("jump"),
	CROUCH = hash("crouch"),
	ATTACK = hash("attack"),
	LEFT = hash("left"),
	RIGHT = hash("right")
}

-- ============================================================================
-- STATE MACHINE CONFIGURATION
-- ============================================================================
-- This table defines ALL possible states our character can be in.
-- Think of it as a "rule book" that tells the game:
-- - What animation to play in each state
-- - Whether the animation should loop or play once
-- - What should happen when the player presses different buttons
--
-- Each state is like a "mode" the character is in. For example:
-- - "standing_idle" = character is standing still, playing idle animation, looped
--
-- The "on_" properties define what happens when inputs are pressed, e.g.:
-- - on_attack = what state to go to when attack button is pressed
-- - on_move = what state to go to when movement keys are pressed
-- - default_next = what state to go to when animation finishes (for non-looped animations)

local STATE_CONFIG = {
	-- STANDING STATES - Character is upright and can move freely
	-- These are the "normal" states when the character is standing
	standing_idle = {
		animation = "idle",      -- Play the "idle" animation from the sprite atlas
		is_looped = true,        -- Keep playing this animation over and over
		on_crouch = "to_crouch", -- If crouch key pressed, go to "to_crouch" state
		on_attack = "standing_attack", -- If attack key pressed, go to "standing_attack" state
		on_jump = "standing_jump", -- If jump key pressed, go to "standing_jump" state
		on_move = "standing_run", -- If movement keys pressed, go to "standing_run" state
		on_turn = "standing_turn" -- If character turns around, go to "standing_turn" state
	},
	standing_run = {
		animation = "run",       -- Play the running animation
		is_looped = true,        -- Loop the running animation continuously
		on_crouch = "to_crouch", -- Can still crouch while running
		on_attack = "standing_attack", -- Can attack while running
		on_jump = "standing_jump", -- Can jump while running
		on_stop = "standing_idle", -- When movement stops, go back to idle
		on_turn = "standing_turn" -- When turning around, play turn animation
	},
	standing_jump = {
		animation = "jump",      -- Play the jump animation
		is_looped = false,       -- Play jump animation only once
		default_next = "standing_idle" -- When jump animation finishes, go back to idle
	},
	standing_attack = {
		animation = "attack",    -- Play the attack animation
		is_looped = false,       -- Play attack animation only once
		default_next = "standing_idle" -- When attack finishes, go back to idle
	},
	standing_turn = {
		animation = "turn_around", -- Play the turn around animation
		is_looped = false,        -- Play turn animation only once
		default_next = "standing_idle", -- When turn finishes, go to idle
		on_turn = "standing_turn" -- If turning again while already turning, keep turning
	},

	-- CROUCHING STATES - Character is in low position, limited movement
	-- When crouching, the character can't jump but can still move and attack
	crouching_idle = {
		animation = "crouch_idle", -- Play the crouching idle animation
		is_looped = true,         -- Loop the crouch idle animation
		on_stand = "to_standing", -- If crouch key released, start standing up
		on_attack = "crouching_attack", -- Can attack while crouching
		on_move = "crouching_run" -- Can move while crouching (crouch walk)
	},
	crouching_run = {
		animation = "crouch_walk", -- Play the crouch walking animation
		is_looped = true,         -- Loop the crouch walk animation
		on_stand = "to_standing", -- Can stand up while crouch walking
		on_attack = "crouching_attack", -- Can attack while crouch walking
		on_stop = "crouching_idle" -- When movement stops, go to crouch idle
	},
	crouching_attack = {
		animation = "crouch_attack", -- Play the crouch attack animation
		is_looped = false,         -- Play attack animation only once
		default_next = "crouching_idle", -- When attack finishes, go to crouch idle
		on_stand = "to_standing",  -- Can stand up even while attacking
	},

	-- TRANSITION STATES - Intermediate animations between major state changes
	-- These states handle the smooth transition between standing and crouching
	to_crouch = {
		animation = "to_crouch",  -- Play the "going into crouch" animation
		is_looped = false,        -- Play transition animation only once
		default_next = "crouching_idle" -- When transition finishes, go to crouch idle
	},
	to_standing = {
		animation = "from_crouch", -- Play the "standing up from crouch" animation
		is_looped = false,       -- Play transition animation only once
		default_next = "standing_idle" -- When transition finishes, go to standing idle
	}
}

-- ============================================================================
-- MOVEMENT AND DIRECTION LOGIC
-- ============================================================================

--- Updates movement state and sprite direction based on input
--- This function figures out:
--- 1. Is the character moving? (left or right key pressed)
--- 2. Which direction is the character facing? (left or right)
--- 3. Did the character just turn around? (for turn animation)
--- @param self table Script instance with input flags
local function update_movement_state(self)
	-- Start by assuming the character is not moving
	self.is_moving = false

	-- Remember the previous facing direction to detect turns
	local previous_is_flipped = self.is_flipped

	-- Check movement input and update facing direction
	if self[INPUT.LEFT] and not self[INPUT.RIGHT] then
		-- Left key is pressed and right key is not pressed
		self.is_moving = true
		self.is_flipped = true -- Character faces left (sprite is flipped)
	elseif self[INPUT.RIGHT] and not self[INPUT.LEFT] then
		-- Right key is pressed and left key is not pressed
		self.is_moving = true
		self.is_flipped = false -- Character faces right (sprite is not flipped)
	end
	-- If both keys are pressed or neither is pressed, character doesn't move

	-- Detect if the character just turned around - used to trigger the "turn around" animation
	self.is_turning = self.is_flipped ~= previous_is_flipped
end


-- ============================================================================
-- STATE TRANSITION LOGIC
-- ============================================================================

--- Determines the next state based on current input and state configuration
--- This is the "brain" of our state machine - it decides what state to go to next
---
--- INPUT PRIORITY SYSTEM (in order of importance):
--- 1. Attack - Highest priority, can interrupt most other actions
--- 2. Jump - High priority, can interrupt movement
--- 3. Movement - Medium priority, handles start/stop moving
--- 4. Crouch/Stand - Medium priority, changes posture
--- 5. Turn - Lowest priority, only when changing direction
---
--- @param self table Script instance with input flags and current state
--- @return string|nil Next state name or nil if no transition needed
local function get_next_state(self)
	-- Get current input state and configuration
	local is_crouching = self[INPUT.CROUCH] -- Is crouch key currently pressed?
	local config = STATE_CONFIG[self.state] -- Get rules for current state
	local next_state = nil               -- Will hold the next state to go to

	-- PRIORITY 1: ATTACK INPUT (Highest Priority)
	-- Attack can interrupt almost any other action
	if self[INPUT.ATTACK] then
		next_state = config.on_attack -- Go to attack state if current state allows it
	end

	-- PRIORITY 2: JUMP INPUT (High Priority)
	-- Jump can interrupt movement but not attack
	if self[INPUT.JUMP] then
		next_state = config.on_jump -- Go to jump state if current state allows it
	end

	-- PRIORITY 3: MOVEMENT STATE CHANGES (Medium Priority)
	-- Handle starting to move or stopping movement
	if self.is_moving and config.on_move then
		next_state = config.on_move -- Character is moving and current state has a "move" transition
	elseif not self.is_moving and config.on_stop then
		next_state = config.on_stop -- Character stopped moving and current state has a "stop" transition
	end

	-- PRIORITY 4: CROUCH/STAND STATE CHANGES (Medium Priority)
	-- Handle posture changes (standing vs crouching)
	if is_crouching and config.on_crouch then
		next_state = config.on_crouch -- Crouch key is pressed and current state allows crouching
	elseif not is_crouching and config.on_stand then
		next_state = config.on_stand -- Crouch key is released and current state allows standing
	end

	-- PRIORITY 5: DIRECTION CHANGE (Lowest Priority)
	-- Handle turning around (only when changing direction)
	if self.is_turning and config.on_turn then
		next_state = config.on_turn -- Character just turned around and current state has turn animation
	end

	-- Return the next state (or nil if no transition is needed)
	return next_state
end

-- ============================================================================
-- VISUAL LAYER - Handles all visual effects and animations
-- ============================================================================

--- Updates all visual elements based on current character state
--- This function is responsible for making the character look correct on screen:
--- - Playing the right animation for the current state
--- - Flipping the sprite to face the right direction
--- - Creating special effects (like the jump animation)
--- - Updating the GUI to show current state
--- @param self table Script instance with current state and flip information
local function update_visuals(self)
	-- Get the configuration for the current state
	local config = STATE_CONFIG[self.state]

	-- Play the animation for the current state
	sprite.play_flipbook("#sprite", config.animation)

	-- Visualize the jump effect
	-- (When jumping, we add a visual effect by moving the character up and down)
	if self.state == "standing_jump" then
		local pos = go.get_position()
		-- Animate the Y position to simulate a jump visually
		go.animate(".", "position.y", go.PLAYBACK_ONCE_PINGPONG, pos.y + 50, go.EASING_INOUTCUBIC, 0.6)
	else
		-- If not jumping, make sure any jump animation is cancelled and reset the character to ground level
		go.cancel_animations(".", "position.y")
		local pos = go.get_position()
		go.set_position(vmath.vector3(pos.x, 600, pos.z)) -- 600 is our ground level Y position
	end

	-- Update the GUI - send a message to the GUI component to update the UI
	msg.post("gui", "animation_state_changed", {
		state = self.state
	})
end

-- ============================================================================
-- DEFOLD LIFECYCLE FUNCTIONS
-- ============================================================================

--- Initializes the knight character when the game starts
--- It sets up the initial state and prepares the character for input
--- @param self table Script instance - this is automatically provided by Defold
function init(self)
	-- Set up initial state machine state as "standing_idle"
	self.state = "standing_idle"

	-- Set up movement and direction flags
	self.is_flipped = false -- Character starts facing right (not flipped)
	self.is_moving = false -- Character starts not moving
	self.is_turning = false -- Character starts not turning

	-- Initialize all input flags - start with all keys "not pressed" (false)
	self[INPUT.LEFT] = false -- Left arrow key
	self[INPUT.RIGHT] = false -- Right arrow key
	self[INPUT.JUMP] = false -- Space bar
	self[INPUT.ATTACK] = false -- Attack button (X)
	self[INPUT.CROUCH] = false -- Crouch button (C)

	-- Display the initial state visually
	update_visuals(self)

	-- Enable input handling
	msg.post(".", "acquire_input_focus")
end

--- Handles input events from keyboard every time the player presses or releases a key
--- It updates our input tracking and triggers state transitions
--- @param self table Script instance
--- @param action_id hash Which input was pressed (like "jump", "attack", etc.)
--- @param action table Contains information about the input (pressed/released)
function on_input(self, action_id, action)
	-- Update input state - keep track of which keys are currently being pressed:
	if action.pressed then
		self[action_id] = true -- Key was just pressed down
	elseif action.released then
		self[action_id] = false -- Key was just released
	end

	-- Process state machine:
	update_movement_state(self)          -- Update movement and direction state based on input
	local next_state = get_next_state(self) -- Decide what state to go to next

	-- If we determined a new state is needed, switch to it and update visuals:
	if next_state then
		self.state = next_state -- Change to the new state
		update_visuals(self) -- Update the visual appearance
	end
end

--- Handles messages from other game objects
--- We use it to handle messages that comes to the script when animations finish playing
--- @param self table Script instance
--- @param message_id hash What type of message this is
function on_message(self, message_id, message)
	-- This message is sent when a non-looped animation finishes playing (like attack, jump, or turn animations)
	if message_id == hash("animation_done") then

		-- Flip the sprite horizontally when the character just finished turning
		if message.id == hash("turn_around") then
			sprite.set_hflip("#sprite", self.is_flipped)
		end

		-- Process state machine:
		update_movement_state(self)       -- Update movement and direction state based on input
		local next_state = get_next_state(self) -- Decide what state to go to next

		-- Switch to the next state (or default next) and update visuals
		self.state = next_state or STATE_CONFIG[self.state].default_next
		update_visuals(self)
	end
end