Chest

Overview

A chest is a box that contains a treasure.

This type of map entity can be declared in the map data file. It can also be created dynamically with map:create_chest().

A chest may contain a treasure or be empty. When opening the chest, the following happens by default:

If the chest contains a treasure, the engine automatically gives it to the player, unless the treasure is not obtainable.
If the chest is empty or contains a non-obtainable treasure, then nothing happens.

This is the default behavior of opening a chest, and it can be redefined by your script in the chest:on_opened() event.

The state of a chest is either open or closed. When a chest is closed, its treasure (if any) is still inside and the hero can get it.

A chest appears initially open on the map if its state is saved and the corresponding boolean value is true If is possible to save the state of a chest (open or closed) even if it contains no treasure.

Methods Inherited from map entity

Chests are particular map entities. Therefore, they inherit all methods from the type map entity.

See entity to know these methods.

Methods of the type chest

The following methods are specific to chests.

`chest:is_open()`

Returns the state of this chest (open or closed).

Return value (boolean): true if this chest is open, false if it is closed.

`chest:set_open([open])`

Sets the state of this chest (open or closed). If you close the chest, its treasure (as returned by chest:get_treasure()) is restored and can be obtained again later.

open (boolean, optional): true to make the chest open, false to make it closed. No value means true.

`chest:get_treasure()`

Returns the treasure the player will obtain when opening this chest.

If the chest is already open, this function still works: it returns the treasure that was inside the chest before it was open.

Return value 1 (string): Name of an equipment item. nil means that the chest is empty.
Return value 2 (number): Variant of this equipment item (1 means the first variant). nil means that the chest is empty.
Return value 3 (string): Name of the boolean value that stores in the savegame whether the chest is open. nil means that the chest is not saved.

Note

If the treasure is a non-obtainable item, the hero will actually get no treasure when opening the chest.

`chest:set_treasure([item_name, [variant, [savegame_variable]]])`

Sets the treasure the player will obtain when opening this chest.

If the chest is already open, this function still works, it sets the treasure that will be put back in case you close the chest later.

item_name (string, optional): Name of an equipment item. nil makes the chest empty.
variant (number, optional): Variant of this equipment item (1 means the first variant). The default value is 1. Must be nil when item_name is nil.
savegame_variable (string, optional): Name of the boolean value that stores in the savegame whether the chest is open. nil means that the chest is not saved.

Note

If the treasure is a non-obtainable item, the hero will actually get no treasure when opening the chest.

`chest:get_opening_method()`

Returns a string describing the way this chest can be opened. Can be either "interaction" (when the hero interacts with it), "interaction_if_item" (when the hero interacts with it while possessing a certain item, returned by chest:get_opening_condition()), "interaction_if_savegame_variable" (when the hero interacts with it while the value of a certain savegame variable, returned by chest:get_opening_condition(), is true),

Return value (string): The opening method.

`chest:get_opening_condition()`

Returns the name of the item or savegame variable required to open this chest (if the opening method is "interaction_if_item" or "interaction_if_savegame_variable", respectively).

Return value (string): item name or savegame variable.

`chest:is_opening_condition_consumed()`

Returns whether the opening condition of this chest is consumed when you open it (only if the opening method is "interaction_if_item" or "interaction_if_savegame_variable") If the condition is an item (i.e. the opening method is "interaction_if_item"), the item is removed, which means setting its possessed variant to 0, unless it has an associated amount : in this case, the amount is decremented.

If the condition is a savegame variable (i.e. the opening method is "interaction_if_savegame_variable"),it is reset to false, 0 or "" (depending on its type).

Return value (boolean): true if the condition is consumed, false if it is not.

`chest:set_opening_method(method)`

Sets the opening method of this chest. See chest:get_opening_method() for a list of possible methods.

method (string): the string associated with the wanted method, as returned by chest:get_opening_method()

`chest:set_opening_condition(condition)`

Sets the name of the item or savegame variable required to open this chest (if the opening method is "interaction_if_item" or "interaction_if_savegame_variable", respectively).

condition (string): item name or savegame variable that will be required to open this chest.

`chest:set_opening_condition_consumed([condition_consumed])`

Returns whether the opening condition of this chest is consumed when you open it (only if the opening method is "interaction_if_item" or "interaction_if_savegame_variable").

See chest:is_opening_condition_consumed() for more information about what happens when the condition is consumed.

condition_consumed (boolean): true if the condition is consumed, false if it is not. No value means true.

`chest:get_cannot_open_sound()`

Returns the sound id defined for this chest when the hero is unable to open it.

Return value (string): The sound id.

`chest:set_cannot_open_sound([sound_id])`

Changes the sound to play when the hero is unable to open the chest.

By default, the sound used is "wrong".

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

sound_id (string, optional): The sound id. An empty string or nil means no sound.

`chest:get_opening_sound()`

Returns the sound id for the chest opening phase.

Return value (string): The sound id.

`chest:set_opening_sound([sound_id])`

Changes the sound to play when the chest is opening. By default, the sound used for chest opening phase is "chest_open".

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

sound_id (string, optional): The sound id. An empty string or nil means no sound.

Events inherited from map entity

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

Chests are particular map entities. Therefore, they inherit all events from the type map entity.

See entity to know these events.

Events of the type chest

The following events are specific to chests.

`chest:on_opened(treasure_item, treasure_variant, treasure_savegame_variable, hero)`

Called when a hero opens this chest.

At this point, if the chest is saved, then the engine has already set the corresponding savegame value to true (treasure_savegame_variable),no matter if this event is defined.

Then, if you don't define this event, by default, the engine gives the treasure to the player (if there is no treasure, then nothing else happens and the hero is automatically unfrozen).

Your script can define this event to customize what happens. By calling hero:start_treasure(), you can either give the chest's treasure or a treasure decided dynamically. Or you can do something else: show a dialog, play a sound, close the chest again, etc.

The hero is automatically frozen during the whole process of opening a chest. If you don't give him a treasure, then you have to unblock him explicitly by calling hero:unfreeze() when you want to restore control to the player.

treasure_item (item): Equipment item in the chest, or nil if the chest is empty or contains a non-obtainable item.
treasure_variant (number): Variant of the treasure or nil if the chest is empty or contains a non-obtainable item.
treasure_savegame_variable (string): Name of the boolean value that stores in the savegame whether this chest is open, or nil if this chest is not saved.
hero (hero): The hero who opened the chest.