1.14.01 - Hero

The hero is the character controlled by the player. There is always exactly one hero on the current map. The hero is automatically created by the engine: you cannot create or remove him.

Overview

The name of the hero (as returned by entity:get_name()) is always "hero". Therefore, from a script, you can access the hero with map:get_entity("hero") or, if you are in a map script, directly with the hero variable (see map:get_entity() for more details). There are also quick accessors map:get_hero() and game:get_hero() to retrieve the hero more easily.

His size is always 16x16 pixels.

The hero entity persists accross map changes. In other words, the effect of functions like hero:set_walking_speed() persists when the player goes to another map. Similarly, events that you define on the hero (like hero:on_taking_damage()) continue to get called on any map while the game is active.

We describe here the Lua API that you can use to change the hero's state.

Hero sprites

Multiple sprites for the hero are automatically created by the engine. You can access them like for any other entity, specifying their name in entity:get_sprite([name]).

Here is the list of hero sprites created by the engine and their names:

Keep in mind that depending on the hero's equipment, his state and the ground below him, all of these built-in sprites don't always exist, and some of them may exist at some point but without being currently displayed.

Methods inherited from map entity

The hero is a particular map entity. Therefore, he inherits all methods from the type map entity.

See Methods of all entity types to know these methods.

Methods of the type hero

The following methods are specific to the hero.

hero:teleport(map_id, [destination_name, [transition_style]])

Teletransports the hero to a different place.

Remarks
The transportation will occur at the next cycle of the engine's main loop. Therefore, your map is not unloaded immediately and your map script continues to work.

hero:get_direction()

Returns the direction of the hero's sprites.

Remarks
The direction of the hero's sprites may be different from both the direction pressed by the player's commands" and from the actual direction of the hero's \ref lua_api_movement "movement".

hero:set_direction(direction4)

Sets the direction of the hero's sprites.

Remarks
The direction of the hero's sprites may be different from both the direction pressed by the player's commands" and from the actual direction of the hero's \ref lua_api_movement "movement".

hero:get_walking_speed()

Returns the speed of the normal walking movement of hero.

This speed is automatically reduced when the hero walks on special ground like grass, ladders or holes.

hero:set_walking_speed(walking_speed)

Sets the speed of the normal walking movement of hero.

The default walking speed is 88 pixels per second. This speed is automatically reduced when the hero walks on special ground like grass, ladders or holes.

hero:save_solid_ground([x, y, layer]), hero:save_solid_ground(callback)

Sets a position to go back to if the hero falls into a hole or other bad ground.

This replaces the usual behavior which is going back to the last solid position before the fall.

The position can be specified either as coordinates and a layer, or as a function that returns coordinates and a layer. Using a function allows to decide the position at the last moment.

To memorize a position directly:

To set a function that indicates the position to go back to:

hero:reset_solid_ground()

Forgets a position that was previously memorized by hero:save_solid_ground() (if any).

The initial behavior is restored: the hero will now get back to where he was just before falling, instead going to of a memorized position.

This is equivalent to hero:save_solid_ground(nil).

hero:get_solid_ground_position()

Returns the position where the hero gets back if he falls into a hole or other bad ground now.

This is the position that was previously memorized by the last call to hero:save_solid_ground(), if any. If the position was passed to hero:save_solid_ground() as a function, then this function is called to get a position.

Otherwise, this is the position of the hero the last time he was on solid ground.

hero:get_animation()

Returns the current animation of the hero's sprites.

The hero may have several sprites (see hero:set_animation(). This function always returns the animation of the tunic sprite.

hero:set_animation(animation, [callback])

Changes the animation of the hero's sprites.

The hero has several sprites, that are normally displayed or not depending on his state and his abilities:

The animation of all these sprites is usually managed by the engine to represent the current state of the hero. You can use this function to customize the animation. This allows you to implement custom actions that are not provided by the built-in states. Make sure that you don't call this function when the hero is not already doing a particular action (like pushing something or attacking), unless you know what you are doing.

All sprites of the hero that have an animation with the specified name take the animation. The ones that don't have such an animation are not displayed.

hero:get_tunic_sprite_id()

Returns the name of the sprite representing the hero's body.

hero:set_tunic_sprite_id(sprite_id)

Changes the sprite representing the hero's body.

By default, the sprite used for the body is "hero/tunicX", where X is the tunic level.

You can use this function if you want to use another sprite.

hero:get_sword_sprite_id()

Returns the name of the sprite representing the hero's sword.

hero:set_sword_sprite_id(sprite_id)

Changes the sprite representing the hero's sword.

By default, the sprite used for the sword is "hero/swordX", where X is the sword level, or no sprite if the sword level is 0.

You can use this function if you want to use another sprite.

hero:get_sword_sound_id()

Returns the name of the sound played when the hero uses the sword.

hero:set_sword_sound_id(sound_id)

Changes the sound to play when the hero uses the sword.

By default, the sound used for the sword is "swordX", where X is the sword level, or no sound if the sword level is 0.

You can use this function if you want another sound to be played.

hero:get_shield_sprite_id()

Returns the name of the sprite representing the hero's shield.

hero:set_shield_sprite_id(sprite_id)

Changes the sprite representing the hero's shield.

By default, the sprite used for the shield is "hero/shieldX", where X is the shield level, or no sprite if the shield level is 0.

You can use this function if you want to use another sprite.

hero:is_invincible()

Returns whether the hero is currently invincible.

The hero is temporarily invincible after being hurt or after you called hero:set_invincible(). In this situation, enemies cannot attack the hero, but you can still hurt him manually with hero:start_hurt().

hero:set_invincible([invincible, [duration]])

Sets or unsets the hero temporarily invincible.

When the hero is invincible, enemies cannot attack him, but you can still hurt him manually with hero:start_hurt().

hero:is_blinking()

Returns whether the hero's sprites are currently blinking.

The sprites are temporarily blinking after the hero was hurt or after you called hero:set_blinking().

Remarks
The visibility property of the hero is independent from this. Even when the sprites are blinking, the result of hero:is_visible() is unchanged.

hero:set_blinking([blinking, [duration]])

Makes the hero's sprites temporarily blink or stop blinking.

This only affects displaying: see hero:set_invincible() if you also want to make the hero invincible.

hero:get_state()

Returns the name of the current built-in state of the hero.

hero:freeze()

Prevents the player from moving the hero until you call hero:unfreeze().

hero:unfreeze()

Restores the control to the player. The control may have been lost for example by a call to hero:freeze() or to some_movement:start(hero).

hero:walk(path, [loop, [ignore_obstacles]])

Makes the hero move with the specified path and a walking animation. The player cannot control him during the movement.

hero:start_jumping(direction8, distance, [ignore_obstacles])

Makes the hero jump towards the specified direction.

hero:start_attack()

Makes the hero perform his main attack (swinging his sword).

This function does the same as what happens when the player presses the "attack" game command. You can use it to trigger the attack from your script instead of from a game command.

If the player is not allowed to perform the attack now (because he does not have the sword ability or because the hero is currently busy in another state), then nothing happens.

hero:start_item(item)

Makes the hero use an equipment item.

The item:on_using() event will be called and the player won't be able to control the hero until you call item:set_finished(). See the documentation of equipment items for more information.

This function does the same as what happens when the player presses a game command corresponding to this equipment item. You can use it to trigger the item from your script instead of from a game command.

If the player is not allowed to use the item now (because he does not have it, because the item cannot be used explicitly, or because the hero is currently busy in another state), then nothing happens.

hero:start_treasure(treasure_name, [treasure_variant, [treasure_savegame_variable, [callback]]])

Gives a treasure to the player. The hero will brandish the treasure as follows.

The hero sprites take the animation "treasure". The treasure is displayed above the hero, as the sprite "entities/items" with animation treasure_name and direction treasure_variant - 1. If this sprite, this animation or this direction do not exist, then no treasure sprite is displayed above the hero.

If a dialog called "_treasure.treasure_name.treasure_variant" exists, then this dialog is displayed during the brandishing animation. For example, calling hero:start_treasure("heart", 1) will automatically show the dialog _treasure.heart.1.

Remarks
If there is no callback, or if the callback does not change the state of the hero, then he automatically stops the brandishing animation.

hero:start_victory([callback])

Makes the hero brandish his sword for a victory.

hero:start_boomerang(max_distance, speed, tunic_preparing_animation, sprite_name)

Makes the hero shoot a boomerang.

hero:start_bow()

Makes the hero shoot an arrow with a bow.

hero:start_hookshot()

Makes the hero throw a hookshot.

hero:start_running()

Makes the hero run.

hero:start_hurt(source_x, source_y, damage)

Hurts the hero, exactly like when he is touched by an enemy. The hurting animations and sounds of the hero are played.

This method hurts the hero even if enemies cannot, including when the hero is temporarily invincible (because he was already hurt recently) or when the hero is in a state where he cannot be hurt (for example when he is brandishing a treasure).

Remarks
If you just want to remove some life to the player, without making the hurting animations and sounds of the hero, see game:remove_life().

hero:start_hurt([source_entity, [source_sprite]], damage)

Same as hero:start_hurt(source_x, source_y, damage), but specifying the source coordinates as an optional entity and possibly its sprite.

Events inherited from map entity

Events are callback methods automatically called by the engine if you define them.

The hero is a particular map entity. Therefore, he inherits all events from the type map entity.

See Events of all entity types to know these events.

Events of the type hero

The following events are specific to the hero.

Recall that the hero persists when the player goes to another map, and so do the events defined on the hero.

hero:on_state_changed(state)

Called when the built-in state of the hero changes.

Remarks
This event is called even for the initial state of the hero, right after game:on_started(). This initial state is always "free".

hero:on_taking_damage(damage)

Called when the hero is hurt and should take damages.

This happens usually after a collision with an enemy or when you call hero:start_hurt().

This event allows you to override what happens when the hero takes damage. By default, if you don't define this event, the hero loses some life as follows. The life lost is the damage inflicted by the attacker divided by the tunic level of the player, with a minimum of 1 (unless the initial damage was already 0).

You can define this event if you need to change how the hero takes damage, for example if you want the shield level to give better resistance to injuries.