Scripting Capabilities¶

Porymap is extensible via scripting capabilities. This allows the user to write custom JavaScript (technically, ECMAScript) files to support enhanced workflows, without having to fork Porymap itself. While the possibilities are endless, some useful examples of scripting might be:

Toggle Day/Night Palettes
Custom Map Painting Brushes
Detect Tile Errors
Show Diagonistic Information
Procedurally Generated Maps
Randomize Grass Patterns

Writing a Custom Script¶

Let’s write a custom script that will randomize grass patterns when the user is editing the map. This is useful, since it’s cumbersome to manually add randomness to grass patches. With the custom script, it will happen automatically. Whenever the user paints a grass tile onto the map, the script will overwrite the tile with a random grass tile instead.

First, create a new script file called my_script.js–place it in the project directory (e.g. pokefirered/).

Next, open the Porymap project config file, porymap.project.cfg, in the project directory. Add the script file to the custom_scripts configuration value. Multiple script files can be loaded by separating the filepaths with a comma.

custom_scripts=my_script.js

Now that Porymap is configured to load the script file, let’s write the actual code that will power the grass-randomizer. Scripts have access to several “callbacks” for events that occur while Porymap is running. This means our script can define functions for each of these callbacks. We’re interested in the onBlockChanged() callback, since we want our script to take action whenever a user paints a block on the map.

// Porymap callback when a block is painted.
export function onBlockChanged(x, y, prevBlock, newBlock) {
    // Grass-randomizing logic goes here.
}

It’s very important to remember to export the callback functions in the script. Otherwise, Porymap will not be able to execute them.

In addition to the callbacks, Porymap also supports a scripting API so that the script can interact with Porymap in interesting ways. For example, a script can change a block or add overlay text on the map. Since we want to paint random grass tiles, we’ll be using the map.setMetatileId() function. Let’s fill in the rest of the grass-randomizing code.

function randInt(min, max) {
    min = Math.ceil(min);
    max = Math.floor(max);
    return Math.floor(Math.random() * (max - min)) + min;
}

// These are the grass metatiles in pokefirered.
const grassTiles = [0x8, 0x9, 0x10, 0x11];

// Porymap callback when a block is painted.
export function onBlockChanged(x, y, prevBlock, newBlock) {
    // Check if the user is painting a grass tile.
    if (grassTiles.indexOf(newBlock.metatileId) != -1) {
        // Choose a random grass tile and paint it on the map.
        const i = randInt(0, grassTiles.length);
        map.setMetatileId(x, y, grassTiles[i]);
    }
}

Let’s test the script out by re-launching Porymap. If we try to paint grass on the map, we should see our script inserting a nice randomized grass pattern.

Grass-Randomizing Script¶

Registering Script Actions¶

The grass-randomizer script above happens implicitly when the user paints on the map. However, other times we probably want to call the custom script on demand. One of the API functions Porymap provides is the ability to trigger scripting functions from the Tools menu, or a keyboard shortcut. To do this, we will usually want to register the action when the project loads. Here is an example script where some custom actions are registered.

export function applyNightTint() {
    // Apply night palette tinting...
}

// Porymap callback when project is opened.
export function onProjectOpened(projectPath) {
map.registerAction("applyNightTint", "View Night Tint", "T")
}

Then, to trigger the applyNightTint() function, we could either click Tools -> View Night Tint or use the T keyboard shortcut.

Now that we have an overview of how to utilize Porymap’s scripting capabilities, the entire scripting API is documented below.

Scripting API¶

Callbacks¶

onProjectOpened(projectPath)¶

Called when Porymap successfully opens a project.

Arguments

projectPath (string) – the directory path of the opened project

onProjectClosed(projectPath)¶

Called when Porymap closes a project. For example, this is called when opening a different project.

Arguments

projectPath (string) – the directory path of the closed project

onMapOpened(mapName)¶

Called when a map is opened.

Arguments

mapName (string) – the name of the opened map

onBlockChanged(x, y, prevBlock, newBlock)¶

Called when a block is changed on the map. For example, this is called when a user paints a new tile or changes the collision property of a block.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block
prevBlock (object) – the block’s state before it was modified. The object’s shape is {metatileId, collision, elevation, rawValue}
newBlock (object) – the block’s new state after it was modified. The object’s shape is {metatileId, collision, elevation, rawValue}

onBorderMetatileChanged(x, y, prevMetatileId, newMetatileId)¶

Called when a border metatile is changed.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block
prevMetatileId (number) – the metatile id of the border block before it was modified
newMetatileId (number) – the metatile id of the border block after it was modified

onBlockHoverChanged(x, y)¶

Called when the mouse enters a new map block.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block

onBlockHoverCleared()¶: Called when the mouse exits the map.

onMapResized(oldWidth, oldHeight, newWidth, newHeight)¶

Called when the dimensions of the map are changed.

Arguments

oldWidth (number) – the width of the map before the change
oldHeight (number) – the height of the map before the change
newWidth (number) – the width of the map after the change
newHeight (number) – the height of the map after the change

onBorderResized(oldWidth, oldHeight, newWidth, newHeight)¶

Called when the dimensions of the border are changed.

Arguments

oldWidth (number) – the width of the border before the change
oldHeight (number) – the height of the border before the change
newWidth (number) – the width of the border after the change
newHeight (number) – the height of the border after the change

onMapShifted(xDelta, yDelta)¶

Called when the map is updated by use of the Map Shift tool.

Arguments

xDelta (number) – the horizontal change from the shift
yDelta (number) – the vertical change from the shift

onTilesetUpdated(tilesetName)¶

Called when the currently loaded tileset is changed by switching to a new one or by saving changes to it in the Tileset Editor.

Arguments

tilesetName (string) – the name of the updated tileset

onMainTabChanged(oldTab, newTab)¶

Called when the selected tab in the main tab bar is changed. Tabs are indexed from left to right, starting at 0 (0: Map, 1: Events, 2: Header, 3: Connections, 4: Wild Pokemon).

Arguments

oldTab (number) – the index of the previously selected tab
newTab (number) – the index of the newly selected tab

onMapViewTabChanged(oldTab, newTab)¶

Called when the selected tab in the map view tab bar is changed. Tabs are indexed from left to right, starting at 0 (0: Metatiles, 1: Collision).

Arguments

oldTab (number) – the index of the previously selected tab
newTab (number) – the index of the newly selected tab

onBorderVisibilityToggled(visible)¶

Called when the visibility of the border and connecting maps is toggled on or off.

Arguments

visible (boolean) – whether the border is now visible

Functions¶

All scripting functions are callable via the global map object.

Map Editing Functions¶

The following functions are related to editing the map’s blocks or retrieving information about them.

map.getBlock(x, y)¶

Gets a block in the currently-opened map.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block

Returns {metatileId, collision, elevation, rawValue}

the block object

map.setBlock(x, y, metatileId, collision, elevation, forceRedraw = true, commitChanges = true)¶

Sets a block in the currently-opened map.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block
metatileId (number) – the metatile id of the block
collision (number) – the collision of the block (0 = passable, 1-3 = impassable)
elevation (number) – the elevation of the block
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.setBlock(x, y, rawValue, forceRedraw = true, commitChanges = true)¶

Sets a block in the currently-opened map. This is an overloaded function that takes the raw value of a block instead of each of the block’s properties individually.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block
rawValue (number) – the 16 bit value of the block. Bits 0-9 will be the metatile id, bits 10-11 will be the collision, and bits 12-15 will be the elevation.
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.getMetatileId(x, y)¶

Gets the metatile id of a block in the currently-opened map.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block

Returns number

the metatile id of the block

map.setMetatileId(x, y, metatileId, forceRedraw = true, commitChanges = true)¶

Sets the metatile id of a block in the currently-opened map.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block
metatileId (number) – the metatile id of the block
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.getBorderMetatileId(x, y)¶

Gets the metatile id of a block in the border of the currently-opened map.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block

Returns number

the metatile id of the block

map.setBorderMetatileId(x, y, metatileId, forceRedraw = true, commitChanges = true)¶

Sets the metatile id of a block in the border of the currently-opened map.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block
metatileId (number) – the metatile id of the block
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.getCollision(x, y)¶

Gets the collision of a block in the currently-opened map. (0 = passable, 1-3 = impassable)

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block

Returns number

the collision of the block

map.setCollision(x, y, collision, forceRedraw = true, commitChanges = true)¶

Sets the collision of a block in the currently-opened map. (0 = passable, 1-3 = impassable)

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block
collision (number) – the collision of the block
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.getElevation(x, y)¶

Gets the elevation of a block in the currently-opened map.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block

Returns number

the elevation of the block

map.setElevation(x, y, elevation, forceRedraw = true, commitChanges = true)¶

Sets the elevation of a block in the currently-opened map.

Arguments

x (number) – x coordinate of the block
y (number) – y coordinate of the block
elevation (number) – the elevation of the block
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.setBlocksFromSelection(x, y, forceRedraw = true, commitChanges = true)¶

Sets blocks on the map using the user’s current metatile selection.

Arguments

x (number) – initial x coordinate
y (number) – initial y coordinate
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.bucketFill(x, y, metatileId, forceRedraw = true, commitChanges = true)¶

Performs a bucket fill of a metatile id, starting at the given coordinates.

Arguments

x (number) – initial x coordinate
y (number) – initial y coordinate
metatileId (number) – metatile id to fill
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.bucketFillFromSelection(x, y, forceRedraw = true, commitChanges = true)¶

Performs a bucket fill using the user’s current metatile selection, starting at the given coordinates.

Arguments

x (number) – initial x coordinate
y (number) – initial y coordinate
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.magicFill(x, y, metatileId, forceRedraw = true, commitChanges = true)¶

Performs a magic fill of a metatile id, starting at the given coordinates.

Arguments

x (number) – initial x coordinate
y (number) – initial y coordinate
metatileId (number) – metatile id to magic fill
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.magicFillFromSelection(x, y, forceRedraw = true, commitChanges = true)¶

Performs a magic fill using the user’s current metatile selection, starting at the given coordinates.

Arguments

x (number) – initial x coordinate
y (number) – initial y coordinate
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.shift(xDelta, yDelta, forceRedraw = true, commitChanges = true)¶

Performs a shift on the map’s blocks.

Arguments

xDelta (number) – number of blocks to shift horizontally
yDelta (number) – number of blocks to shift vertically
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().
commitChanges (boolean) – Commit the changes to the map’s edit/undo history. Defaults to true. When making many related map edits, it can be useful to set this to false, and then commit all of them together with map.commit().

map.getDimensions()¶

Gets the dimensions of the currently-opened map.

Returns {width, height}: the dimensions of the map

map.getWidth()¶

Gets the width of the currently-opened map.

Returns number: the width of the map

map.getHeight()¶

Gets the height of the currently-opened map.

Returns number: the height of the map

map.getBorderDimensions()¶

Gets the dimensions of the border of the currently-opened map.

Returns {width, height}: the dimensions of the border

map.getBorderWidth()¶

Gets the width of the border of the currently-opened map.

Returns number: the width of the border

map.getBorderHeight()¶

Gets the height of the border of the currently-opened map.

Returns number: the height of the border

map.setDimensions(width, height)¶

Sets the dimensions of the currently-opened map.

Arguments

width (number) – width in blocks
height (number) – height in blocks

map.setWidth(width)¶

Sets the width of the currently-opened map.

Arguments

width (number) – width in blocks

map.setHeight()¶

Sets the height of the currently-opened map.

Arguments

height (number) – height in blocks

map.setBorderDimensions(width, height)¶

Sets the dimensions of the border of the currently-opened map. If the config setting use_custom_border_size is set to 0 then this does nothing.

Arguments

width (number) – width in blocks
height (number) – height in blocks

map.setBorderWidth(width)¶

Sets the width of the border of the currently-opened map. If the config setting use_custom_border_size is set to 0 then this does nothing.

Arguments

width (number) – width in blocks

map.setBorderHeight(height)¶

Sets the height of the border of the currently-opened map. If the config setting use_custom_border_size is set to 0 then this does nothing.

Arguments

height (number) – height in blocks

map.redraw()¶: Redraws the entire map area. Useful when delaying map redraws using forceRedraw = false in certain map editing functions.

map.commit()¶: Commits any uncommitted changes to the map’s edit/undo history. Useful when delaying commits using commitChanges = false in certain map editing functions.

Map Header Editing Functions¶

The following functions are related to reading/writing the map’s header properties.

map.getSong()¶

Gets the name of the background song for the currently-opened map.

Returns string: the name of the song

map.setSong(song)¶

Sets the name of the background song for the currently-opened map. The song name must be one of the names in the “Song” dropdown menu on the Header tab.

Arguments

song (string) – the name of the song

map.getLocation()¶

Gets the name of the region map location for the currently-opened map.

Returns string: the name of the location

map.setLocation(location)¶

Sets the name of the region map location for the currently-opened map. The location name must be one of the names in the “Location” dropdown menu on the Header tab.

Arguments

location (string) – the name of the location

map.getRequiresFlash()¶

Gets whether flash would be required in-game for the currently-opened map.

Returns boolean: whether flash is required

map.setRequiresFlash(require)¶

Sets whether flash would be required in-game for the currently-opened map.

Arguments

require (boolean) – whether flash should be required

map.getWeather()¶

Gets the name of the weather for the currently-opened map.

Returns string: the name of the weather

map.setWeather(weather)¶

Sets the name of the weather for the currently-opened map. The weather name must be one of the names in the “Weather” dropdown menu on the Header tab.

Arguments

weather (string) – the name of the weather

map.getType()¶

Gets the name of the map type for the currently-opened map.

Returns string: the name of the map type

map.setType(type)¶

Sets the name of the map type for the currently-opened map. The map type name must be one of the names in the “Type” dropdown menu on the Header tab.

Arguments

type (string) – the name of the map type

map.getBattleScene()¶

Gets the name of the battle scene for the currently-opened map.

Returns string: the name of the battle scene

map.setBattleScene(battleScene)¶

Sets the name of the battle scene for the currently-opened map. The battle scene name must be one of the names in the “Battle scene” dropdown menu on the Header tab.

Arguments

battleScene (string) – the name of the battle scene

map.getShowLocationName()¶

Gets whether the location name will appear in-game for the currently-opened map.

Returns boolean: whether the location name will be shown

map.setShowLocationName(show)¶

Sets whether the location name should appear in-game for the currently-opened map.

Arguments

show (boolean) – whether the location name should be shown

map.getAllowRunning()¶

Gets whether running is allowed in-game for the currently-opened map.

Returns boolean: whether running is allowed

map.setAllowRunning(allow)¶

Sets whether running should be allowed in-game for the currently-opened map.

Arguments

allow (boolean) – whether running should be allowed

map.getAllowBiking()¶

Gets whether biking is allowed in-game for the currently-opened map.

Returns boolean: whether biking is allowed

map.setAllowBiking(allow)¶

Sets whether biking should be allowed in-game for the currently-opened map.

Arguments

allow (boolean) – whether biking should be allowed

map.getAllowEscaping()¶

Gets whether escaping (using Escape Rope or Dig) is allowed in-game for the currently-opened map.

Returns boolean: whether escaping is allowed

map.setAllowEscaping(allow)¶

Sets whether escaping (using Escape Rope or Dig) should be allowed in-game for the currently-opened map.

Arguments

allow (boolean) – whether escaping should be allowed

map.getFloorNumber()¶

Gets the floor number for the currently-opened map.

Returns number: the floor number

map.setFloorNumber(floorNumber)¶

Sets the floor number for the currently-opened map. Floor numbers can be any number between -128 and 127 inclusive.

Arguments

floorNumber (number) – the floor number

Map Overlay Functions¶

The following functions are related to an overlay that is drawn on top of the map area. Text, images, and shapes can be drawn using these functions. Items can be drawn and manipulated on separate layers by specifiying a layer id. Items on higher layer ids will be drawn above those on lower layers. If no layer is specified they will be added to the default layer 0. The visibility and position of each layer can be changed; by default all layers are visible, and their position is 0,0.

map.clearOverlay(layer = 0)¶

Clears and erases all overlay items on the specified layer that were previously-added to the map.

Arguments

layer (number) – the layer id. Defaults to 0

map.clearOverlays()¶: Clears and erases all overlay items that were previously-added to the map.

map.hideOverlay(layer = 0)¶

Hides all overlay items on the specified layer.

Arguments

layer (number) – the layer id. Defaults to 0

map.hideOverlays()¶: Hides all overlay items on all active layers.

map.showOverlay(layer = 0)¶

Shows all overlay items on the specified layer.

Arguments

layer (number) – the layer id. Defaults to 0

map.showOverlays()¶: Shows all overlay items on all active layers.

map.getOverlayVisibility(layer = 0)¶

Gets whether the specified overlay layer is currently showing or not.

Arguments

layer (number) – the layer id. Defaults to 0

Returns boolean

whether the layer is showing

map.setOverlayVisibility(visible, layer = 0)¶

Sets the visibility of the specified overlay layer.

Arguments

visible (boolean) – whether the layer should be showing
layer (number) – the layer id. Defaults to 0

map.setOverlaysVisibility(visible)¶

Sets the visibility of all active overlay layers.

Arguments

visible (boolean) – whether the layers should be showing

map.getOverlayOpacity(layer = 0)¶

Gets the opacity of the specified overlay layer. Opacity ranges from 0 (invisible) to 100 (completely opaque).

Arguments

layer (number) – the layer id. Defaults to 0

Returns number

the opacity

map.setOverlayOpacity(opacity, layer = 0)¶

Sets the opacity of the specified overlay layer. Opacity ranges from 0 (invisible) to 100 (completely opaque).

Arguments

opacity (number) – the opacity
layer (number) – the layer id. Defaults to 0

map.setOverlaysOpacity(opacity)¶

Sets the opacity of all active overlay layers. Opacity ranges from 0 (invisible) to 100 (completely opaque).

Arguments

opacity (number) – the opacity

map.getOverlayX(layer = 0)¶

Gets the x position of the specified overlay layer.

Arguments

layer (number) – the layer id. Defaults to 0

Returns number

the pixel x coordinate

map.getOverlayY(layer = 0)¶

Gets the y position of the specified overlay layer.

Arguments

layer (number) – the layer id. Defaults to 0

Returns number

the pixel y coordinate

map.setOverlayX(x, layer = 0)¶

Sets the x position of the specified overlay layer.

Arguments

x (number) – the pixel x coordinate
layer (number) – the layer id. Defaults to 0

map.setOverlayY(y, layer = 0)¶

Sets the y position of the specified overlay layer.

Arguments

y (number) – the pixel y coordinate
layer (number) – the layer id. Defaults to 0

map.setOverlaysX(x)¶

Sets the x position of all active overlay layers.

Arguments

x (number) – the pixel x coordinate

map.setOverlaysY(y)¶

Sets the y position of all active overlay layers.

Arguments

y (number) – the pixel y coordinate

map.getOverlayPosition(layer = 0)¶

Gets the position of the specified overlay layer.

Arguments

layer (number) – the layer id. Defaults to 0

Returns {x, y}

the layer’s pixel coordinates

map.setOverlayPosition(x, y, layer = 0)¶

Sets the position of the specified overlay layer.

Arguments

x (number) – the pixel x coordinate
y (number) – the pixel y coordinate
layer (number) – the layer id. Defaults to 0

map.setOverlaysPosition(x, y)¶

Sets the position of all active overlay layers.

Arguments

x (number) – the pixel x coordinate
y (number) – the pixel y coordinate

map.moveOverlay(deltaX, deltaY, layer = 0)¶

Moves the specified overlay layer.

Arguments

deltaX (number) – the number of pixels to move horizontally
deltaY (number) – the number of pixels to move vertically
layer (number) – the layer id. Defaults to 0

map.moveOverlays(deltaX, deltaY)¶

Moves all active overlay layers.

Arguments

deltaX (number) – the number of pixels to move horizontally
deltaY (number) – the number of pixels to move vertically

map.addText(text, x, y, color = "#000000", size = 12, layer = 0)¶

Adds a text item to the specified overlay layer.

Arguments

text (string) – the text to display
x (number) – the x pixel coordinate of the text (relative to the layer’s position)
y (number) – the y pixel coordinate of the text (relative to the layer’s position)
color (string) – the color of the text. Can be specified as “#RRGGBB” or “#AARRGGBB”. Defaults to black.
size (number) – the font size of the text. Defaults to 12.
layer (number) – the layer id. Defaults to 0

map.addRect(x, y, width, height, color = "#000000", layer = 0)¶

Adds a rectangle outline item to the specified overlay layer.

Arguments

x (number) – the x pixel coordinate of the rectangle’s top-left corner (relative to the layer’s position)
y (number) – the y pixel coordinate of the rectangle’s top-left corner (relative to the layer’s position)
width (number) – the pixel width of the rectangle
height (number) – the pixel height of the rectangle
color (string) – the color of the rectangle. Can be specified as “#RRGGBB” or “#AARRGGBB”. Defaults to black.
layer (number) – the layer id. Defaults to 0

map.addFilledRect(x, y, width, height, color = "#000000", layer = 0)¶

Adds a filled rectangle item to the specified overlay layer.

Arguments

x (number) – the x pixel coordinate of the rectangle’s top-left corner (relative to the layer’s position)
y (number) – the y pixel coordinate of the rectangle’s top-left corner (relative to the layer’s position)
width (number) – the pixel width of the rectangle
height (number) – the pixel height of the rectangle
color (string) – the color of the rectangle. Can be specified as “#RRGGBB” or “#AARRGGBB”. Defaults to black.
layer (number) – the layer id. Defaults to 0

map.addImage(x, y, filepath, layer = 0, useCache = true)¶

Adds an image item to the specified overlay layer.

Arguments

x (number) – the x pixel coordinate of the image’s top-left corner (relative to the layer’s position)
y (number) – the y pixel coordinate of the image’s top-left corner (relative to the layer’s position)
filepath (string) – the image’s filepath
layer (number) – the layer id. Defaults to 0
useCache (boolean) – whether the image should be saved/loaded using the cache. Defaults to true. Reading images from a file is slow. Setting useCache to true will save the image to memory so that the next time the filepath is encountered the image can be loaded from memory rather than the file.

map.createImage(x, y, filepath, width = -1, height = -1, offset = 0, hScale = 1, vScale = 1, paletteId = -1, setTransparency = false, layer = 0, useCache = true)¶

Creates an image item on the specified overlay layer. This differs from map.addImage by allowing the new image to be a transformation of the image file.

Arguments

x (number) – the x pixel coordinate of the image’s top-left corner (relative to the layer’s position)
y (number) – the y pixel coordinate of the image’s top-left corner (relative to the layer’s position)
filepath (string) – the image’s filepath
width (number) – the width in pixels of the area to read in the image. If -1, use the full width of the original image. Defaults to -1
height (number) – the height in pixels of the area to read in the image. If -1, use the full height of the original image. Defaults to -1
offset (number) – the pixel offset into the original image where data should be read from. Defaults to 0
hScale (number) – the horizontal scale for the image. Negative values will be a horizontal flip of the original image. Defaults to 1
vScale (number) – the vertical scale for the image. Negative values will be a vertical flip of the original image. Defaults to 1
paletteId (number) – the id of which currently loaded tileset palette to use for the image. If -1, use the original image’s palette. Defaults to -1
setTransparency (boolean) – whether the color at index 0 should be overwritten with transparent pixels. Defaults to false
layer (number) – the layer id. Defaults to 0
useCache (boolean) – whether the image should be saved/loaded using the cache. Defaults to true. Reading images from a file is slow. Setting useCache to true will save the image to memory so that the next time the filepath is encountered the image can be loaded from memory rather than the file.

map.addTileImage(x, y, tileId, xflip, yflip, palette, setTransparency = false, layer = 0)¶

Creates an image of a tile on the specified overlay layer.

Arguments

x (number) – the x pixel coordinate of the image’s top-left corner (relative to the layer’s position)
y (number) – the y pixel coordinate of the image’s top-left corner (relative to the layer’s position)
tileId (number) – tile value for the image
xflip (boolean) – whether the tile image is flipped horizontally
yflip (boolean) – whether the tile image is flipped vertically
palette (number) – palette number for the tile image
setTransparency (boolean) – whether the color at index 0 should be overwritten with transparent pixels. Defaults to false
layer (number) – the layer id. Defaults to 0

map.addTileImage(x, y, tile, setTransparency = false, layer = 0)¶

Creates an image of a tile on the specified overlay layer. This is an overloaded function that takes a single tile as a JavaScript object instead of each of the tile’s properties individually.

Arguments

x (number) – the x pixel coordinate of the image’s top-left corner (relative to the layer’s position)
y (number) – the y pixel coordinate of the image’s top-left corner (relative to the layer’s position)
tile ({tileId,xflip,yflip,palette}) – the tile to create an image of
setTransparency (boolean) – whether the color at index 0 should be overwritten with transparent pixels. Defaults to false
layer (number) – the layer id. Defaults to 0

map.addMetatileImage(x, y, metatileId, setTransparency = false, layer = 0)¶

Creates an image of a metatile on the specified overlay layer.

Arguments

x (number) – the x pixel coordinate of the image’s top-left corner (relative to the layer’s position)
y (number) – the y pixel coordinate of the image’s top-left corner (relative to the layer’s position)
metatileId (number) – id of the metatile to create an image of
setTransparency (boolean) – whether the color at index 0 should be overwritten with transparent pixels. Defaults to false
layer (number) – the layer id. Defaults to 0

Tileset Functions¶

The following functions are related to tilesets and how they are rendered. The functions with “preview” in their name operate on a “fake” version of the palette colors. This means that changing these “preview” colors won’t affect the actual tileset colors in the project. A good use of the “preview” palettes would be Day/Night tints, for example.

map.getPrimaryTilesetPalettePreview(paletteIndex)¶

Gets a palette from the primary tileset of the currently-opened map.

Arguments

paletteIndex (number) – the palette index

Returns array

array of colors. Each color is a 3-element RGB array

map.setPrimaryTilesetPalettePreview(paletteIndex, colors)¶

Sets a palette in the primary tileset of the currently-opened map. This will NOT affect the true underlying colors–it only displays these colors in the map-editing area of Porymap.

Arguments

paletteIndex (number) – the palette index
colors (array) – array of colors. Each color is a 3-element RGB array

map.getPrimaryTilesetPalettesPreview()¶

Gets all of the palettes from the primary tileset of the currently-opened map.

Returns array: array of arrays of colors. Each color is a 3-element RGB array

map.setPrimaryTilesetPalettesPreview(palettes)¶

Sets all of the palettes in the primary tileset of the currently-opened map. This will NOT affect the true underlying colors–it only displays these colors in the map-editing area of Porymap.

Arguments

palettes (array) – array of arrays of colors. Each color is a 3-element RGB array

map.getSecondaryTilesetPalettePreview(paletteIndex)¶

Gets a palette from the secondary tileset of the currently-opened map.

Arguments

paletteIndex (number) – the palette index

Returns array

array of colors. Each color is a 3-element RGB array

map.setSecondaryTilesetPalettePreview(paletteIndex, colors)¶

Sets a palette in the secondary tileset of the currently-opened map. This will NOT affect the true underlying colors–it only displays these colors in the map-editing area of Porymap.

Arguments

paletteIndex (number) – the palette index
colors (array) – array of colors. Each color is a 3-element RGB array

map.getSecondaryTilesetPalettesPreview()¶

Gets all of the palettes from the secondary tileset of the currently-opened map.

Returns array: array of arrays of colors. Each color is a 3-element RGB array

map.setSecondaryTilesetPalettesPreview(palettes)¶

Sets all of the palettes in the secondary tileset of the currently-opened map. This will NOT affect the true underlying colors–it only displays these colors in the map-editing area of Porymap.

Arguments

palettes (array) – array of arrays of colors. Each color is a 3-element RGB array

map.getPrimaryTilesetPalette(paletteIndex)¶

Gets a palette from the primary tileset of the currently-opened map.

Arguments

paletteIndex (number) – the palette index

Returns array

array of colors. Each color is a 3-element RGB array

map.setPrimaryTilesetPalette(paletteIndex, colors)¶

Sets a palette in the primary tileset of the currently-opened map. This will permanently affect the palette and save the palette to disk.

Arguments

paletteIndex (number) – the palette index
colors (array) – array of colors. Each color is a 3-element RGB array

map.getPrimaryTilesetPalettes()¶

Gets all of the palettes from the primary tileset of the currently-opened map.

Returns array: array of arrays of colors. Each color is a 3-element RGB array

map.setPrimaryTilesetPalettes(palettes)¶

Sets all of the palettes in the primary tileset of the currently-opened map. This will permanently affect the palettes and save the palettes to disk.

Arguments

palettes (array) – array of arrays of colors. Each color is a 3-element RGB array

map.getSecondaryTilesetPalette(paletteIndex)¶

Gets a palette from the secondary tileset of the currently-opened map.

Arguments

paletteIndex (number) – the palette index

Returns array

array of colors. Each color is a 3-element RGB array

map.setSecondaryTilesetPalette(paletteIndex, colors)¶

Sets a palette in the secondary tileset of the currently-opened map. This will permanently affect the palette and save the palette to disk.

Arguments

paletteIndex (number) – the palette index
colors (array) – array of colors. Each color is a 3-element RGB array

map.getSecondaryTilesetPalettes()¶

Gets all of the palettes from the secondary tileset of the currently-opened map.

Returns array: array of arrays of colors. Each color is a 3-element RGB array

map.setSecondaryTilesetPalettes(palettes)¶

Sets all of the palettes in the secondary tileset of the currently-opened map. This will permanently affect the palettes and save the palettes to disk.

Arguments

palettes (array) – array of arrays of colors. Each color is a 3-element RGB array

map.isPrimaryTileset(tilesetName)¶

Gets whether the specified tileset is a primary tileset.

Arguments

tilesetName (string) – the tileset name

Returns boolean

is a primary tileset

map.isSecondaryTileset(tilesetName)¶

Gets whether the specified tileset is a secondary tileset.

Arguments

tilesetName (string) – the tileset name

Returns boolean

is a secondary tileset

map.getPrimaryTileset()¶

Gets the name of the primary tileset for the currently-opened map.

Returns string: primary tileset name

map.setPrimaryTileset(tileset)¶

Sets the primary tileset for the currently-opened map.

Arguments

tileset (string) – the tileset name

map.getSecondaryTileset()¶

Gets the name of the secondary tileset for the currently-opened map.

Returns string: secondary tileset name

map.setSecondaryTileset(tileset)¶

Sets the secondary tileset for the currently-opened map.

Arguments

tileset (string) – the tileset name

map.getNumPrimaryTilesetMetatiles()¶

Gets the number of metatiles in the primary tileset for the currently-opened map.

Returns number: number of metatiles

map.getMaxPrimaryTilesetMetatiles()¶

Gets the maximum number of metatiles allowed in a primary tileset.

Returns number: maximum number of metatiles

map.getNumSecondaryTilesetMetatiles()¶

Gets the number of metatiles in the secondary tileset for the currently-opened map.

Returns number: number of metatiles

map.getMaxSecondaryTilesetMetatiles()¶

Gets the maximum number of metatiles allowed in a secondary tileset.

Returns number: maximum number of metatiles

map.getNumPrimaryTilesetTiles()¶

Gets the number of tiles in the primary tileset for the currently-opened map.

Returns number: number of tiles

map.getMaxPrimaryTilesetTiles()¶

Gets the maximum number of tiles allowed in a primary tileset.

Returns number: maximum number of tiles

map.getNumSecondaryTilesetTiles()¶

Gets the number of tiles in the secondary tileset for the currently-opened map.

Returns number: number of tiles

map.getMaxSecondaryTilesetTiles()¶

Gets the maximum number of tiles allowed in a secondary tileset.

Returns number: maximum number of tiles

map.getNumTilesInMetatile()¶

Gets the number of tiles in a metatile. Will be either 8 or 12 depending on enable_triple_layer_metatiles.

Returns number: number of tiles in a metatile

map.getNumMetatileLayers()¶

Gets the number of layers in a metatiles. Will be either 2 or 3 depending on enable_triple_layer_metatiles.

Returns number: number of layers in a metatile

map.getMetatileLayerOrder()¶

Gets the order that metatile layers are rendered.

Returns array: array of layers. The bottom layer is represented as 0.

map.setMetatileLayerOrder(order)¶

Sets the order that metatile layers are rendered.

Arguments

order (array) – array of layers. The bottom layer is represented as 0.

map.getMetatileLayerOpacity()¶

Gets the opacities that metatile layers are rendered with.

Returns array: array of opacities for each layer. The bottom layer is the first element.

map.setMetatileLayerOpacity(opacities)¶

Sets the opacities that metatile layers are rendered with.

Arguments

opacities (array) – array of opacities for each layer. The bottom layer is the first element.

map.getMetatileLabel(metatileId)¶

Gets the label for the specified metatile.

Arguments

metatileId (number) – id of target metatile

Returns string

the label

map.setMetatileLabel(metatileId, label)¶

Sets the label for the specified metatile. A label can only consist of letters, numbers, and underscores.

Warning: This function writes directly to the project. There is no undo for this.

Arguments

metatileId (number) – id of target metatile
label (string) – the label

map.getMetatileLayerType(metatileId)¶

Gets the layer type for the specified metatile. 0: Middle/Top, 1: Bottom/Middle, 2: Bottom/Top.

Arguments

metatileId (number) – id of target metatile

Returns number

the layer type

map.setMetatileLayerType(metatileId, layerType)¶

Sets the layer type for the specified metatile. 0: Middle/Top, 1: Bottom/Middle, 2: Bottom/Top.

Warning: This function writes directly to the tileset. There is no undo for this.

Arguments

metatileId (number) – id of target metatile
layerType (number) – the layer type

map.getMetatileEncounterType(metatileId)¶

Gets the encounter type for the specified metatile. 0: None, 1: Land, 2: Water

Arguments

metatileId (number) – id of target metatile

Returns number

the encounter type

map.setMetatileEncounterType(metatileId, encounterType)¶

Sets the encounter type for the specified metatile. 0: None, 1: Land, 2: Water

Warning: This function writes directly to the tileset. There is no undo for this.

Arguments

metatileId (number) – id of target metatile
encounterType (number) – the encounter type

map.getMetatileTerrainType(metatileId)¶

Gets the terrain type for the specified metatile. 0: None, 1: Grass, 2: Water, 3: Waterfall

Arguments

metatileId (number) – id of target metatile

Returns number

the terrain type

map.setMetatileTerrainType(metatileId, terrainType)¶

Sets the terrain type for the specified metatile. 0: None, 1: Grass, 2: Water, 3: Waterfall

Warning: This function writes directly to the tileset. There is no undo for this.

Arguments

metatileId (number) – id of target metatile
terrainType (number) – the terrain type

map.getMetatileBehavior(metatileId)¶

Gets the behavior for the specified metatile.

Arguments

metatileId (number) – id of target metatile

Returns number

the behavior

map.setMetatileBehavior(metatileId, behavior)¶

Sets the behavior for the specified metatile.

Warning: This function writes directly to the tileset. There is no undo for this.

Arguments

metatileId (number) – id of target metatile
behavior (number) – the behavior

map.getMetatileAttributes(metatileId)¶

Gets the raw attributes value for the specified metatile.

Arguments

metatileId (number) – id of target metatile

Returns number

the raw attributes value

map.setMetatileAttributes(metatileId, attributes)¶

Sets the raw attributes value for the specified metatile.

Warning: This function writes directly to the tileset. There is no undo for this. Porymap will not limit the value of existing attributes to their usual range.

Arguments

metatileId (number) – id of target metatile
attributes (number) – the raw attributes value

map.getMetatileTile(metatileId, tileIndex)¶

Gets the tile at the specified index of the metatile.

Arguments

metatileId (number) – id of target metatile
tileIndex (number) – index of the tile to get

Returns {tileId, xflip, yflip, palette}

the tile

map.getMetatileTiles(metatileId, tileStart = 0, tileEnd = -1)¶

Gets the tiles in the specified range of the metatile.

Arguments

metatileId (number) – id of target metatile
tileStart (number) – index of the first tile to get. Defaults to 0 (the first tile)
tileEnd (number) – index of the last tile to get. Defaults to -1 (the last tile)

Returns array

array of tiles in the specified range. Each tile is an object of the form {tileId, xflip, yflip, palette}

map.setMetatileTile(metatileId, tileIndex, tileId, xflip, yflip, palette, forceRedraw = true)¶

Sets the tile at the specified index of the metatile.

Warning: This function writes directly to the tileset. There is no undo for this.

Arguments

metatileId (number) – id of target metatile
tileIndex (number) – index of the tile to set
tileId (number) – new tile’s value
xflip (boolean) – whether the new tile is flipped horizontally
yflip (boolean) – whether the new tile is flipped vertically
palette (number) – new tile’s palette number
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().

map.setMetatileTile(metatileId, tileIndex, tile, forceRedraw = true)¶

Sets the tile at the specified index of the metatile. This is an overloaded function that takes a single tile as a JavaScript object instead of each of the tile’s properties individually.

Warning: This function writes directly to the tileset. There is no undo for this.

Arguments

metatileId (number) – id of target metatile
tileIndex (number) – index of the tile to set
tile ({tileId,xflip,yflip,palette}) – the new tile
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().

map.setMetatileTiles(metatileId, tileId, xflip, yflip, palette, tileStart = 0, tileEnd = -1, forceRedraw = true)¶

Sets the tiles in the specified range of the metatile. All tiles in the specified range will be set using the same given values.

Warning: This function writes directly to the tileset. There is no undo for this.

Arguments

metatileId (number) – id of target metatile
tileId (number) – new tiles’ value
xflip (boolean) – whether the new tiles are flipped horizontally
yflip (boolean) – whether the new tiles are flipped vertically
palette (number) – new tiles’ palette number
tileStart (number) – index of the first tile to set. Defaults to 0 (the first tile)
tileEnd (number) – index of the last tile to set. Defaults to -1 (the last tile)
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().

map.setMetatileTiles(metatileId, tiles, tileStart = 0, tileEnd = -1, forceRedraw = true)¶

Sets the tiles in the specified range of the metatile. This is an overloaded function that takes an array of tiles as JavaScript objects instead of each of the tile properties individually.

Warning: This function writes directly to the tileset. There is no undo for this.

Arguments

metatileId (number) – id of target metatile
tiles (array) – array of tiles to set. Each tile is an object of the form {tileId, xflip, yflip, palette}. If the array does not have sufficient objects to set all the tiles in the specified range then the remaining tiles will be set with all default values.
tileStart (number) – index of the first tile to set. Defaults to 0 (the first tile)
tileEnd (number) – index of the last tile to set. Defaults to -1 (the last tile)
forceRedraw (boolean) – Force the map view to refresh. Defaults to true. Redrawing the map view is expensive, so set to false when making many consecutive map edits, and then redraw the map once using map.redraw().

map.getTilePixels(tileId)¶

Gets the pixel data for the specified tile. The pixel data is an array of indexes indicating which palette color each pixel uses. Tiles are 8x8, so the pixel array will be 64 elements long.

Returns array: the pixel data

Settings Functions¶

The following functions are related to settings.

map.getGridVisibility()¶

Gets the visibility of the map grid overlay.

Returns boolean: grid visibility

map.setGridVisibility(visible)¶

Sets the visibility of the map grid overlay.

Arguments

visible (boolean) – grid visibility

map.getBorderVisibility()¶

Gets the visibility of the map’s border.

Returns boolean: border visibility

map.setBorderVisibility(visible)¶

Sets the visibility of the map’s border.

Arguments

visible (boolean) – border visibility

map.getSmartPathsEnabled()¶

Gets the toggle state of smart paths.

Returns boolean: smart paths enabled

map.setSmartPathsEnabled(enabled)¶

Sets the toggle state of smart paths.

Arguments

enabled (boolean) – smart paths enabled

map.getBaseGameVersion()¶

Gets the project’s base game version.

Returns string: "pokeruby", "pokefirered", or "pokeemerald"

map.getPorymapVersion()¶

Gets the current version of Porymap (MAJOR.MINOR.PATCH).

Returns {major, minor, patch}: the version object

map.getCustomScripts()¶

Gets the list of paths to custom scripts.

Returns array: string array of custom scripts paths

map.getMainTab()¶

Gets the index of the currently selected main tab. Tabs are indexed from left to right, starting at 0 (0: Map, 1: Events, 2: Header, 3: Connections, 4: Wild Pokemon).

Returns number: current main tab index

map.setMainTab(tab)¶

Sets the currently selected main tab. Tabs are indexed from left to right, starting at 0 (0: Map, 1: Events, 2: Header, 3: Connections, 4: Wild Pokemon).

Arguments

tab (number) – index of the tab to select

map.getMapViewTab()¶

Gets the index of the currently selected map view tab. Tabs are indexed from left to right, starting at 0 (0: Metatiles, 1: Collision).

Returns number: current map view tab index

map.setMapViewTab(tab)¶

Sets the currently selected map view tab. Tabs are indexed from left to right, starting at 0 (0: Metatiles, 1: Collision).

Arguments

tab (number) – index of the tab to select

Utility Functions¶

These are some miscellaneous functions that can be very useful when building custom scripts.

map.registerAction(functionName, actionName, shortcut = "")¶

Registers a JavaScript function to an action that can be manually triggered in Porymap’s Tools menu. Optionally, a keyboard shortcut (e.g. "Ctrl+P") can also be specified, assuming it doesn’t collide with any existing shortcuts used by Porymap. The function specified by functionName must have the export keyword.

Arguments

functionName (string) – name of the JavaScript function
actionName (string) – name of the action that will be displayed in the Tools menu
shortcut (string) – optional keyboard shortcut

map.setTimeout(func, delayMs)¶

This behaves essentially the same as JavaScript’s setTimeout() that is used in web browsers or NodeJS. The func argument is a JavaScript function (NOT the name of a function) which will be executed after a delay. This is useful for creating animations or refreshing the overlay at constant intervals.

Arguments

func (function) – a JavaScript function that will be executed later
delayMs (number) – the number of milliseconds to wait before executing func

map.log(message)¶

Logs a message to the Porymap log file with the prefix [INFO]. This is useful for debugging custom scripts.

Arguments

message (string) – the message to log

map.warn(message)¶

Logs a message to the Porymap log file with the prefix [WARN].

Arguments

message (string) – the message to log

map.error(message)¶

Logs a message to the Porymap log file with the prefix [ERROR].

Arguments

message (string) – the message to log

map.showMessage(text, informativeText, detailedText)¶

Displays a message box with an “Information” icon and an OK button. Execution stops while the window is open.

Arguments

text (string) – the main message text
informativeText (string) – smaller text below the main message. Defaults to ""
detailedText (string) – text hidden behind a “Show Details” box. Defaults to ""

map.showWarning(text, informativeText, detailedText)¶

Displays a message box with a “Warning” icon and an OK button. Execution stops while the window is open.

Arguments

text (string) – the main message text
informativeText (string) – smaller text below the main message. Defaults to ""
detailedText (string) – text hidden behind a “Show Details” box. Defaults to ""

map.showError(text, informativeText, detailedText)¶

Displays a message box with a “Critical” icon and an OK button. Execution stops while the window is open.

Arguments

text (string) – the main message text
informativeText (string) – smaller text below the main message. Defaults to ""
detailedText (string) – text hidden behind a “Show Details” box. Defaults to ""

map.showQuestion(text, informativeText, detailedText)¶

Displays a message box with a “Question” icon and a Yes and a No button. Execution stops while the window is open.

Arguments

text (string) – the main message text
informativeText (string) – smaller text below the main message. Defaults to ""
detailedText (string) – text hidden behind a “Show Details” box. Defaults to ""

Returns boolean

true if Yes was selected, false if No was selected or if the window was closed without selection

map.getInputText(title, label, default)¶

Displays a text input dialog with an OK and a Cancel button. Execution stops while the window is open.

Arguments

title (string) – the text in the window title bar
label (string) – the text adjacent to the input entry area
default (string) – the text in the input entry area when the window is opened. Defaults to ""

Returns {input, ok}

input will be the input text and ok will be true if OK was selected. input will be "" and ok will be false if Cancel was selected or if the window was closed without selection.

map.getInputNumber(title, label, default, min, max, decimals, step)¶

Displays a number input dialog with an OK and a Cancel button. Execution stops while the window is open.

Arguments

title (string) – the text in the window title bar
label (string) – the text adjacent to the input entry area
default (number) – the number in the input entry area when the window is opened. Defaults to 0
min (number) – the minimum allowable input value. Defaults to -2147483648
max (number) – the maximum allowable input value. Defaults to 2147483647
decimals (number) – the number of decimals used for the input number. Defaults to 0
step (number) – the increment by which the input number will change when the spinner is used. Defaults to 1

Returns {input, ok}

input will be the input number and ok will be true if OK was selected. input will be default and ok will be false if Cancel was selected or if the window was closed without selection.

map.getInputItem(title, label, items, default, editable)¶

Displays a text input dialog with an items dropdown and an OK and a Cancel button. Execution stops while the window is open.

Arguments

title (string) – the text in the window title bar
label (string) – the text adjacent to the input entry area
items (array) – an array of text items that will populate the dropdown
default (number) – the index of the item to select by default. Defaults to 0
editable (boolean) – whether the user is allowed to enter their own text instead. Defaults to false

Returns {input, ok}

input will be the input text and ok will be true if OK was selected. input will be the text of the item at default and ok will be false if Cancel was selected or if the window was closed without selection.