Chest

Table of Contents

• Overview
• Methods inherited from map entity
• Methods of the type chest
  • chest:is_open()
  • chest:set_open([open])
  • chest:get_treasure()
  • chest:set_treasure([item_name, [variant, [savegame_variable]]])
• Events inherited from map entity
• Events of the type chest
  • chest:on_opened(treasure_item, treasure_variant, treasure_savegame_variable)

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:

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

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

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.

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

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.

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