If you put a portable entity in the map, you can carry it to other map and come back with it. But a new one will be created in the initial map. Sometimes it is desirable to avoid duplicating entities like this. For instance, if the entitiy is something unique: a key item like the "metal ball", a key that can be carried (I will use these in my game if I finish it someday), etc.
If you want to create an entity that is unique, it must be created dynamically from the map script. (You can use the generic_portable.lua script or a more specialized one.) Second, just after creating it you must add an identifier (usually a string) stored in the variable "entity.unique_id = ...". An example of this, in the map script, write:
function map:on_started()
local game = map:get_game()
-- Create independent entity if it does not exist!!!
local unique_id = "write_this_entity_identifier_here"
if not game.save_between_maps:entity_exists(game, unique_id) then
local entity = map:create_custom_entity({x = 208, y = 197, layer = 0, direction = 0, sprite = "things/key", model = "generic_portable.lua"})
entity.unique_id = unique_id
end
end
The parameter "entity.unique_id" is used by the script save_between_maps.lua to detect if the entity exists in other map (or is carried by the hero), to avoid duplicating it. Of course, you can use it as a savegame variable related to the entity, as a second use.