1.14.09 - Chest

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

Overview

A chest may contain a treasure or be empty.

When opening the chest, the following happens by default:

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 Methods of all entity types 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).

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.

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.

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

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

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 Events of all entity types 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)

Called when the 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.