Solarus quests  1.1
Quest maker's reference
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 map script, you can access the hero with map:get_entity("hero") or directly with the hero variable (see map:get_entity() for more details).

His size is always 16x16 pixels and his sprites (tunic, sword, shield, shadow, etc.) are managed by the engine.

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_state_changed()) 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.

Methods inherited from map entity

The hero is a particular map entity. Therefore, it 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.

  • map_id (string): Id of the map to go to (may be the same map or another one).
  • destination_name (string, optional): Name of the destination entity to go to on that map, or the special keyword "_same" to go to the same coordinates. No value means the default destination entity of the map.
  • transition_style (string, optional): "immediate" (no transition effect) or "fade" (fade-out and fade-in effect). The default value is "fade".
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.

  • Return value (number): The direction of the hero's sprites, between 0 (East) and 3 (South).
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.

  • direction4 (number): The direction of the hero's sprites, between 0 (East) and 3 (South).
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.

  • Return value (number): The speed of normal walk in pixels par second.

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.

  • walking speed (number): The speed of normal walk in pixels par second.

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

Memorizes 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.

  • x (number, optional): X coordinate to memorize (default: current position).
  • y (number, optional): Y coordinate to memorize (default: current position).
  • layer (number, optional): Layer to memorize (default: current position).

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.

hero:get_state()

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

  • Return value (string): The current state. Can be one of: "back to solid ground", "boomerang", "bow", "carrying", "conveyor belt", "falling", "forced walking", "free", "freezed", "grabbing", "hookshot", "hurt", "jumping", "lifting", "plunging", "pulling", "pushing", "running", "stairs", "swimming", "sword loading", "sword spin attack", "sword swinging", "sword tapping", "treasure", "using item" or "victory".

hero:freeze()

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

hero:unfreeze()

Restores the control to the player, typically after a call to hero:freeze().

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.

  • path (string): The path as a string sequence of integers. Each value is a number between 0 and 7 that represents a step (move of 8 pixels) in the path. 0 is East, 1 is North-East, etc.
  • loop (boolean, optional): true to repeat the path once it is done (default false).
  • ignore_obstacles (boolean, optional): true to allow the hero to traverse obstacles during this movement (default false). Make sure the movement does not end inside an obstacle.

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

Makes the hero jump towards the specified direction.

  • direction8 (number): Direction of the jump, between 0 and 7 (see jump_movement:set_direction8(direction8) jump_movement:set_direction8()).
  • distance (number): Distance of the jump in pixels (see jump_movement:set_distance(distance) jump_movement:set_distance()).
  • ignore_obstacles (boolean, optional): true to allow the hero to traverse obstacles during this movement (default false). Make sure the movement does not end inside an obstacle.

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

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

  • treasure_name (string, optional): Kind of treasure to give (the name of an equipment item). The treasure must be an obtainable item.
  • treasure_variant (number, optional): Variant of the treasure (because some equipment items may have several variants). The default value is 1 (the first variant).
  • treasure_savegame_variable (string, optional): Name of the boolean value that stores in the savegame whether this treasure is found. No value means that the state of the treasure is not saved. It is allowed (though strange) to give the same saved treasure twice.
  • callback (function, optional): A function to call when the treasure's dialog finishes.

hero:start_victory([callback])

Makes the hero brandish his sword for a victory.

  • callback (function, optional): A function to call when the victory sequence finishes. If you don't define it, the default behavior is to restore control to the player. If you define it, you can do other things, like teletransporting the hero somewhere else. To restore the control to the player, call hero:unfreeze().

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.

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.

  • item (item): The equipment item to start using.

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

Makes the hero shoot a boomerang.

  • max_distance (number): Maximum distance of the boomerang's movement in pixels.
  • speed (number): Speed of the boomerang's movement in pixels per second.
  • tunic_preparing_animation (string): Name of the animation that the hero's tunic sprite should take while preparing the boomerang.
  • sprite_name (string): Sprite animation set to use to draw the boomerang then.

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, life_points, magic_points)

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

This method has no effect if the hero is temporarily invincible (because he was already hurt recently) or if the hero is in a state where he cannot be hurt (for example when he is brandishing a treasure).

  • source_x: X coordinate of whatever hurts the hero. Used to push the hero away from that source.
  • source_y: Y coordinate of whatever hurts the hero. Used to push the hero away from that source.
  • life_points: Base number of life points to remove (possibly 0). This number will be divided by the resistance ability level of the player (his tunic).
  • magic_points: Number of magic points to remove (possibly 0).
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().

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, it 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.

  • state (string): Name of the new state. See hero:get_state() for the list of possible states.
Remarks
This event is called even for the initial state of the hero, right after game:on_started(). This initial state is always "free".