Game World Widget

The Game World widget renders an interactive, navigable 2D tile-based game world directly inside a Business Platform page. It is suited for onboarding experiences, interactive floor plans, warehouse overviews, and similar spatial use cases.

The widget uses Phaser for rendering and physics, loaded dynamically in the browser. Map data is authored in the backoffice and stored as GameMap documents, which the widget loads at runtime.

Prerequisites

A GameMap document must exist before placing the widget. Create one via the backoffice admin area (see Creating a Game Map).
Phaser is loaded lazily; no additional installation steps are required for widget consumers.

Creating a Game Map

Game maps are created and edited in the backoffice admin area.

Opening the Map Manager

Navigate to Admin → Game Maps in the backoffice sidebar.
The page lists all existing maps with their names and dimensions.

Creating a New Map

Click Create Map.
Fill in the dialog fields:

Field Description Default

Name Display name for the map (required)

Width Map width in tiles 30

Height Map height in tiles 20

Tile Size Width and height of each tile in pixels 32
Click Create. The editor opens automatically for the new map.

Field	Description	Default
Name	Display name for the map	(required)
Width	Map width in tiles	`30`
Height	Map height in tiles	`20`
Tile Size	Width and height of each tile in pixels	`32`

Map Editor

The editor provides a full-screen canvas-based interface with the following panels and tools.

Tool	Description
Brush	Paint the selected tile onto the active layer
Fill	Flood-fill a contiguous area with the selected tile
Eraser	Remove tiles from the active layer
Object	Place an interactive object (NPC, item, decoration, sign)
Trigger	Draw a trigger zone (teleport, dialogue, info, action)
Spawn	Set the player spawn point
Select	Select and inspect objects or triggers

Layers Panel

Layers are rendered in depth order. Each layer has:

Visibility toggle — show or hide the layer on the canvas.
Collision toggle — when enabled, the layer acts as a collision surface for the player.
Move up / Move down buttons — reorder layers.
Remove button — delete the layer (at least one layer must remain).

To add a new layer, type a name into the input at the bottom of the panel and press Enter or click +.

Tileset Manager

Tilesets provide the tile graphics painted onto layers. Three built-in tilesets are available:

Tileset	Tile Size	Tiles
`basic-office`	32 × 32	64
`basic-outdoor`	32 × 32	64
`basic-warehouse`	32 × 32	64

Click Add Tileset in the panel to expand the built-in tileset list and add one to the current map. Each tileset can only be added once per map. Remove a tileset by clicking the × next to its name.

Tile Palette

After adding a tileset, the Tile Palette panel shows the tileset image with a grid overlay. Click any tile to select it as the active brush. The selected tile is highlighted in green.

If the map contains multiple tilesets, use the dropdown at the top of the palette to switch between them.

Objects Panel

Objects are interactive entities placed on the map. Supported types:

Type	Icon	Description
`npc`	person	Non-player character
`item`	box	Collectible or usable item
`decoration`	tree	Non-interactive decoration
`sign`	sign	Readable sign

Select the desired type in the Objects panel, then choose the Object tool from the toolbar and click on the canvas to place it. Select an existing object in the list or via the Select tool to view and edit its properties in the Properties panel.

Triggers Panel

Triggers are rectangular zones that fire events when the player enters them. Supported types:

Type	Description
`teleport`	Move the player to another location or map
`dialogue`	Start a dialogue sequence
`info`	Display an informational message
`action`	Fire a custom action

Click Draw Trigger to activate the trigger tool, then drag a rectangle on the canvas to define the zone. Select a trigger from the list to edit its properties.

Property	Type	Required	Default	Description
`mapId`	`string`	✅	—	The `_id` of the `GameMap` document to load
`width`	`number`		`800`	Canvas width in pixels
`height`	`number`		`600`	Canvas height in pixels
`enableSound`	`boolean`		`true`	Enable ambient audio and sound effects
`showMinimap`	`boolean`		`false`	Show a minimap overlay
`playerSprite`	`string`		—	URL of a custom player sprite sheet, overriding the default
`movementType`	`"free"` \| `"grid"`		`"free"`	Player movement style — smooth free movement or tile-snapped grid movement

Minimal Example

{
  "mapId": "6627f4e2a1b2c3d4e5f60001"
}

Full Example

{
  "mapId": "6627f4e2a1b2c3d4e5f60001",
  "width": 1024,
  "height": 768,
  "enableSound": false,
  "showMinimap": true,
  "playerSprite": "https://cdn.example.com/sprites/custom-player.png",
  "movementType": "grid"
}

Runtime Behaviour

The widget loads Phaser lazily; it is not included in the server-side render bundle.
While map data is loading, a spinner is shown in place of the canvas.
The game canvas is focusable. When not focused, an overlay prompts the user to Click to play. Keyboard input is disabled while the widget is out of focus, preventing conflicts with page-level shortcuts.
If Phaser fails to load or the map cannot be found, an error message is shown inside the widget boundary.

Interactive Objects at Runtime

Objects placed on a map respond to player proximity:

When the player moves within 48 pixels of an object, a prompt key indicator appears above it.
Interacting with the object (pressing the interaction key) triggers the configured behaviour (dialogue, item pickup, etc.).
Collection-bound objects can display live data labels sourced from a linked collection document.

API Endpoints

The backoffice editor and the widget communicate with the following endpoints:

Method	Path	Description
`GET`	`/api/game-maps`	List all maps
`POST`	`/api/game-maps`	Create a new map
`GET`	`/api/game-maps/:id`	Load a single map
`PATCH`	`/api/game-maps/:id`	Save map changes
`DELETE`	`/api/game-maps/:id`	Delete a map