OpenSpace logo

OpenSpace Editor » Map editor

The Map Editor allows designers to create the final maps that will be loaded by the OpenSpace componente at runtime.

Map properties

A map is defined by the following properties.

id The map’s unique id, automatically generated by the Editor.
The m prefix stands for map.
width | height The size of the map, expressed in number of tiles along the north-south and east-west directions respectively.
editable If true, map editing is allowed. This is an additional precaution to make sure that malevolent users with modified clients can't submit changes to maps which are not supposed to be edited.
The default value is false.
customLimits Four comma-separated integer values representing, respectively, x origin, y origin, width and height of a rectangle which acts as virtual map boundary to limit the camera movements during panning, zooming or viewport scrolling caused by the avatar movement.
Custom limits can be set (or modified) at runtime by means of the OpenSpace component's IOpenSpace.setCustomMapLimits method (check the OpenSpace client-side API reference documentation for more informations).

NOTE
The rectangle x,y origin is measured with respect to the grid's (0,0) coordinates, which are located in the top, left corner of the grid’s bounding box, as shown in the following image:

backgroundId The id of the background, among those available in the backgrounds library.
bgHOffset | bgVOffset The background’s horizontal and vertical offsets with respect to the (0,0) coordinates of the map's grid (see previous image). These settings can be used to position the background correctly with respect to the grid in case their sizes are different.

NOTE
Using a background smaller than the base grid's bounding box and setting the customLimits property to the same size of the background, it is possible to create maps whose grids fill the entire viewport, without the typical empty corners of the isometric diamond-shaped maps.

foregroundId The id of the foreground, among those available in the backgrounds library.
title The map’s name displayed in the maps library.
keywords The keywords that describe the map, useful to filter the maps library. All the keywords must be separated by a comma.

Adding tiles to a map

A tile instance can be added to the currently edited map by selecting its destination (an empty cell on the grid or a previously added tile) and:

  • double clicking the tile in the library on the right; or
  • selecting the tile in the library and then pressing the Add to map button.

It is also possible to add a tile without previously selecting the destination:

  • drag the tile from the library and drop it on the destination position (drag&drop can be used to move tiles already on the map too); or
  • use the Insert mode: select the tile in the library and then click on the destination while keeping the SHIFT key pressed.

Using the Fill base layer button located below the tiles library it is also possible to fill the map with the selected tile. The Smart fill checkbox allows chosing the fill method:

  • standard (checkbox not selected): the whole grid is filled – please notice that if the button is pressed when tiles have already been added, it causes all the bottom-most tiles to be removed and substituted by the selected one (an alert is displayed to avoid accidental use);
  • smart (checkbox selected): only the empty grid cells are filled.

When clicking on a tile instance in the preview area, a selection highlighter appears. This shows the tile's id and title in its bottom-left corner, and an icon in the bottom-right corner indicating if the tile is walkable ( ) or not ( ). Clicking on the background or pressing the ESC key on the keyboard deselects the tile.

To remove a tile instance:

  • select the tile and click the X icon in the top-right corner of the selection highlighter; or
  • select the tile and press the CANC key on the keyboard; or
  • use the Remove mode: click on the tile while keeping the keyboard's ALT key pressed.

NOTE
When the mouse is moved over the map's preview, the coordinates of the tile behind the pointer are displayed in the bottom-left corner of the preview area's footer. If no z coordinate is shown, then the pointer is above an empty grid cell.

Tile instance properties

When a tile instance is selected in the preview area, it is possible to edit some properties by opening the Instance properties panel (click on the button in the bottom-left corner of the main viewport area).

The following properties are available.

Name A unique name to be assigned to the tile instance on the map. The OpenSpace component passes this value to the name property of the Tile class upon creation at runtime.
The instance name can be useful to access the Tile object from the main application by means of the IOpenSpace.getTileByName method of the OpenSpace client-side API, for example to access the tile's skin and show an animation when a specific event occurs.

NOTE
This property must be unique: two tiles on the same map can't have the same name. If this should happen, only the last created tile will be accessible via its instance name.

Inventory item ref. The id of an existing inventory item of type Tile from the Inventory editor.
If this property is set, when the tile is istantiated at runtime, the OpenSpace component marks it as a tile that can be moved/removed by users during the runtime map editing process. This is useful to create editable maps that already contain items (for example pieces of furniture) that users will be allowed to remove.

NOTE 1
An inventory item id can't be assigned to a tile placed on the bottom-most layer (z=0), because removing that tile during the runtime map editing would leave an "hole" in the map.

NOTE 2
Actually it is not mandatory that the id entered in this field matches an existing id from the Inventory editor. If the id exists, the developers will be able to track the changes at runtime and, for example, update the item quantity in the inventory.

Access point If selected, the tile is registered among the access points for the map.
When the user’s avatar is created at runtime, if map coordinates are not passed in the AvatarCreationParams class, the OpenSpace Engine randomly selects one of the available access points and places the avatar on the corresponding tile.
When a tile is registered as an access point, the preview area shows the following symbol on the tile:

NOTE
Each map must should at least one access point defined. If not, a warning is logged when the map is exported and an error could occurr at runtime if the user's avatar is created without specifying the coordinates where it should appear.

Tile instance triggers

The Instance properties panel also shows a specific section containing the fields to setup one or more tile triggers and a table to review/remove the existing triggers. Triggers are useful to make the OpenSpace component fire specific events at runtime, when the user interacts with the tile by clicking it, rolling the mouse pointer over or out of it, or making the avatar walk on the tile.
More informations on events that can be triggered by a tile are available in the Trigger class description in the OpenSpace client-side API reference documentation.

Each trigger is defined by the following properties:

Type The trigger type, used by OpenSpace to determine which event should be fired at runtime. Available values are click, rollOver, rollOut, avatarMove, avatarStop, avatarEnter and avatarLeave.
Target An all-purpose field to store additional trigger data.
This property can be used to store custom informations that will be passed to the event listener when the event is triggered.
For example this property could contain the id of a map to be loaded when the avatar stops on the tile during its movement. This is useful to create an hot spot which causes a map transition or other effects depending on the avatar position.
Params An all-purpose field to store additional trigger data.
This property can be used to store custom informations that will be passed to the event listener once the event is triggered.
For example this property could contain several comma-separated parameters. These parameters can be useful to take specific actions on the trigger's target (in the above map-change example, this Params field could contain the target coordinates where the avatar should appear on the next map).
All avatars When this property is true, avatar-related events are triggered by the movement of all avatars on the current map. If false, only the user's avatar triggers them.

To remove a trigger, click on the X icon in the triggers' table.

NOTE
Tile triggers can be added to walkable tiles only (see the walkable property above), because event firing involves a specific mouse listener that exists if the tile is walkable only.

Adding supertiles to a map

A supertile can be added as a group of tiles (see the box below) to the currently edited map by selecting its destination (an empty cell on the grid or a previously added tile) and:

  • double clicking the supertile in the library on the right; or
  • selecting the supertile in the library and then pressing the Add to map button.

It is also possible to add a supertile without previously selecting the destination:

  • drag the supertile from the library and drop it on the destination position (drag&drop can be used to move tiles already on the map too); or
  • use the Insert mode: select the supertile in the library and then click on the destination while keeping the SHIFT key pressed.

The editor prevents the supertile to be added if it exceeds the map boundaries or if at least one of the destination cells has a different elevation with respect to the others (for example due to an existing tile which has its topElevation greater than 0). In case drag&drop is used, a red highlighting gives a visual feedback when the drop is not possible due to an elevation issue.

IMPORTANT
When a supertile is added to a map, it is converted into a group of tiles, losing any reference to the original supertile. This means that if the supertile is later updated (changing size, adding/removing tiles, etc.) in the Supertile editor, the changes won’t be reflected on the maps to which that supertile was added previously.

When clicking on a group in the preview area, a selection highlighter appears. This shows the group's id (generated when the group is added to the map – g stands for group) and title (equal to the supertile's title) in its bottom-left corner, and an icon in the bottom-right corner indicating that a group was selected ( ). Clicking on the background or pressing the ESC key on the keyboard deselects the group.

To remove a group:

  • select the group and click the X icon in the top-right corner of the selection highlighter; or
  • select the tile and press the CANC key on the keyboard.

Group properties

When a group is selected in the preview area, it is possible to edit some properties by opening the Instance properties panel (click on the button in the bottom-left corner of the main viewport area).

The following properties are available.

Inventory item ref. The id of an existing inventory item of type Supertile from the Inventory editor.
If this property is set, when the group is created at runtime, the OpenSpace component marks it as a group that can be moved/removed by users during the runtime map editing process. This is useful to create editable maps that already contain items (for example pieces of furniture) that users will be allowed to remove.

NOTE 1
An inventory item id can't be assigned to a group with at least one tile placed on the bottom-most layer (z=0), because removing that group during the runtime map editing would leave an "hole" in the map.

NOTE 2
Actually it is not mandatory that the id entered in this field matches an existing id from the Inventory editor. If the id exists, the developers will be able to track the changes at runtime and, for example, update the item quantity in the inventory.

In order to change the instance properties of tiles belonging to a group (as described in the Tile instances properties paragraph above), keep the CONTROL key (Windows) or the COMMAND key (Mac OS X) pressed while clicking on the tile. In this way a single tile can be selected instead of the entire group.
If a tile belonging to a group is dragged in a different position on the map, it still belongs to the group which is re-shaped accordingly. If a tile belonging to a group is removed from the map, that tile is removed from the group too.

Insertions optimization

The OpenSpace Editor automatically optimizes tiles and groups insertions. Under certain circumstances, when a tile (single or belonging to a group) is added to the map and the destination coordinates already contain a tile, the existing tile may be substituted, instead of the new tile being stacked upon it. This allows the reduction of the number of tiles on the map by removing the unnecessary ones, thus improving performance.
Optimization occurs if the Optimize checkbox near the Add to map button is selected and in the following cases:

  • a plain (topElevation equal to 0) tile is inserted above an identical tile (actually in this case the existing tile isn’t substituted and the insertion is simply cancelled);
  • a tile with bottomElevation equal to 0 is inserted above a plain, not skinned tile;
  • the tile in the destination coordinates doesn’t belong to a group.

Preview settings

The Show base grid checkbox shows and hides the map's reference grid.

Using the Show tiles wireframe and Solid wireframe checkboxes it is possible to show/hide the tiles’ reference frames, to better understand the architecture of the map. When the solid wireframe is displayed, walkable tiles are highlighted in green (top side only).

The Show background and Show foreground checkboxes can turn on and off the background and foreground respectively.

The Show custom map limits checkbox shows/hides a thin, green rectangle in the preview area showing the custom map limits defined by means of the customLimits property described above.

Exporting the preview

By means of the Export button located in the bottom left corner of the Map editor it is possible to save a JPG screenshot of the map preview of the desired width (height is calculated proportionally).

Next: Inventory editor