Icon Overlay

From Planimate Knowledge Base
Jump to: navigation, search

By including certain commands in icon names, multiple icons can be merged during one, during edit or dynamically using text expressions. Coloured blocks can be dynamically created. Both icons and created blocks can be scaled, offset, positioned, filtered and blended, becoming one in-memory icon.

The basic structure of a name that uses the Icon Overlay system is parameters in square brackets preceeding an icon name, with multiple icons combined using a vertical bar.

The simplest way of combining icons:


Will overlay Icon2 over Icon1, centering it.

If you want Icon2 to be made smaller you add a parameter block


You are not limited to 2 icons and can create icons on the fly:

Icon1|[W:8 H:8 A:BL]#FFFF00|[W:8 H:8 A:BR]#0000FF

Starts with Icon1, overlays a yellow block at the bottom left and a blue block at the bottom right.

Icon Name

Specifying A File

Icon names are normal file names with no extention, the platform automatically looks for known file types.

The DB file system places a limit of 30 characters on the name of an image placed into a Planimate file DB.

The limit on an Icon Overlay name (commands+names) is about 1000 characters.

Icon file names must not start with '#' or '[' and its advisable to avoid the following characters within names: '#', '['. ']', '@'.

Colour Rectangle

If an icon is named with a '#' following 6 or 8 valid hex digits, instead of a file being loaded, an in-memory colour rectangle with the given #RRGGBB or #AARRGGBB colour will be created. A default size of 16x16 is used but this can be changed/scaled using parameters.

Icon Groups

Planimate has long had the ability to load a number of icons and treat them as one multi-frame icon (like an animated GIF).

This works by naming the icon with a common name, eg: MyGroup and appending an @ (at) symbel followed by a 2 digit equence number. In your DB you may have


Which can be imported from a supported icon image format (PNG, BMP, JPG). By then choosing MyGroup@01 for an item icon, Planimate animates between the frames as the item moves.

This has been extended to support dynamically created icon overlays. A name is chosen for the group, eg: MyGroup@ (include the '@'). For a object state or item icon, use the name MyGroup@ (no following number). This needs to fail to load any icon, resulting in a red square. During run (eg: run start), use an icon overlay command with the group name with a 2 digit frame number appended, starting from 1. This enables each individual frame of the group to be set. Planimate will automatically use the number of frames set. In code this might be done like this:

[1] SetPortalIcon(s.OwningPortalLocation,"_ENTIDLE|GROUP@01")
[2] SetPortalIcon(s.OwningPortalLocation,"[R:90]_ENTIDLE|GROUP@02")
[3] SetPortalIcon(s.OwningPortalLocation,"[R:180]_ENTIDLE|GROUP@03")
[4] SetPortalIcon(s.OwningPortalLocation,"[R:270]_ENTIDLE|GROUP@04")

In this case you may want this code in a portal with an object label which is not visible to the user, it acts a placeholder for creating the icons dynamically.


A parameter block can optionally preceed an icon name with a number of processing/scaling options available. These are applied to that icon before it gets overlaid on the base. If its the base icon, the scaling and sizing parameters are useful in determining the size of the initial base icon.

Alignment (A)

This sets how an overlay image is positioned relative to the base image. Two letters specify vertical then horizontal.

Possible Values: TL,TC,TR,CL,CC,CR,BL,BC,BR


BaseIcon|[A:BL S:50]OverlayIcon

This overlays OverlayIcon over BaseIcon, scaling OverlayIcon to 50% its size and positioning it at the bottom left corner of BaseIcon.

XOffset (X)

This shifts the position of an overlay image. It can be used in addition to Alignment. Example:

BaseIcon|[A:CC X:-2]OverlayIcon

Positive values shift to the right, negative to the left.

YOffset (Y)

This shifts the position of an overlay image. It can be used in addition to Alignment. Example:

BaseIcon|[A:CC Y:3]OverlayIcon

Positive values shift down, negative up (top left co-ordinate system).

Scale (S)

This scales the icon from its loaded/created size. The value specifies a percentage and range from 5 to 1000 are reasonable. Large scaling of large images may exhaust memory. See Example in Align.

Width (W)

Overrides any default width for an icon (base or overlay), enabling the width to be set in pixels. This is particularly useful when creating a colour block in-memory.


[W:32 H:32]#00FF00

Create a 32x32 green block.

Height (H)

Overrides any default height for an icon (base or overlay), enabling the height to be set in pixels. This is particularly useful when creating a colour block in-memory.


[W:32 H:32]#800000FF

Create a 32x32 transparent blue block.

Transparency (T)

Enables a given colour to be made totally transparent. This is useful for BMPs which use "Planimate Grey" as the Icon OVerlay system does not process Planimate Grey transparency when in use.



Mix (M)

Mixes an icon with a colour. This can be used to colour filter an icon and is particularly useful with a white image template as it can be recoloured to any colour.



This creates a light grey 32x32 transparent backdrop and overlays "TemplateIcon" after runnint it through a green filter.

The mix filter supports mixing alpha.

Exchange (E)

Substitutes a given colour with another with full alpha support.



Replaces pure blue pixels with a transparent green.

Rotate [R]

Rotates the associated icon/colour block by an angle (in degrees).


[W:24 H:24]#00000000|[R:45]_PORIDLE

A transparent area of 24x24 is created to allow space for the rotated _PORIDLE icon's corners.

Make BMP (B)

Creates an in-memory BMP of the icon which is faster to render but will not have translucent pixels and will not scale or rotate as nicely. This is recommended for node icons on a map where fast redraw is desired as a user pans the map. Regardless of where this command appears in a set of combined overlay commands, the conversion is applied to the final resulting image.



The image will render as fast as if the image was a BMP. Fully transparent pixels will remain transparent. Rotation and scaling is not antialiased.