Porymap

https://huderlem.github.io/porymap/
Admin
Porymap is a feature-rich map editor for creating and editing game maps with support for tiles,...
Tokens:38,072
Snippets:416
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Register Custom Script Actions

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Example of using onProjectOpened to register a custom function as an action in the Tools menu with a keyboard shortcut.

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

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

```

--------------------------------

### Porymap Scripting API: onProjectOpened Callback

Source: https://huderlem.github.io/porymap/manual/settings-and-options.html

Example of the `onProjectOpened` callback function in Porymap's scripting API. This function is executed when a project is opened.

```lua
function onProjectOpened(project)
  print("Project opened: " .. project.name)
end
```

--------------------------------

### map.bucketFill

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Performs a bucket fill operation starting at the given coordinates.

```APIDOC
## map.bucketFill(x, y, metatileId, forceRedraw, commitChanges)

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

### Parameters
#### Arguments
- **x** (number) - Required - initial x coordinate
- **y** (number) - Required - initial y coordinate
- **metatileId** (number) - Required - metatile id to fill
- **forceRedraw** (boolean) - Optional - Force the map view to refresh. Defaults to true.
- **commitChanges** (boolean) - Optional - Commit the changes to the map’s edit/undo history. Defaults to true.
```

--------------------------------

### map.getMetatileBehavior

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Gets the behavior for the specified metatile.

```APIDOC
## map.getMetatileBehavior

### Description
Gets the behavior for the specified metatile.

### Parameters
- **metatileId** (number) - Required - id of target metatile

### Response
- **return** (number) - the behavior
```

--------------------------------

### Tileset Palette Preview Functions

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Functions to get and set palette previews for tilesets. These changes do not affect actual tileset colors.

```APIDOC
## map.getPrimaryTilesetPalettePreview(paletteIndex)
### Description
Gets a palette from the primary tileset of the currently-opened map.
### Parameters
- **paletteIndex** (number) - Required
### Response
- **colors** (array) - Array of 3-element RGB arrays

## map.setPrimaryTilesetPalettePreview(paletteIndex, colors, forceRedraw)
### Description
Sets a palette in the primary tileset of the currently-opened map. Only affects the map-editing area.
### Parameters
- **paletteIndex** (number) - Required
- **colors** (array) - Required - Array of 3-element RGB arrays
- **forceRedraw** (boolean) - Optional - Defaults to true

## map.getPrimaryTilesetPalettesPreview()
### Description
Gets all of the palettes from the primary tileset of the currently-opened map.
### Response
- **palettes** (array) - Array of arrays of 3-element RGB arrays

## map.setPrimaryTilesetPalettesPreview(palettes, forceRedraw)
### Description
Sets all of the palettes in the primary tileset of the currently-opened map.
### Parameters
- **palettes** (array) - Required - Array of arrays of 3-element RGB arrays
- **forceRedraw** (boolean) - Optional - Defaults to true
```

--------------------------------

### Overlay Opacity Get/Set Functions

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Functions to get and set the opacity of overlay layers.

```APIDOC
## overlay.getOpacity(_layer = 0_)

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

### Method
overlay.getOpacity

### Parameters
#### Path Parameters
- **layer** (number) - Optional - the layer id. Defaults to `0`

### Returns
- **number** - the opacity

### Response Example
```json
{
  "opacity": 80
}
```

## overlay.setOpacity(_opacity_ , _layer_)

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

### Method
overlay.setOpacity

### Parameters
#### Path Parameters
- **opacity** (number) - Required - the opacity
- **layer** (number) - Required - the layer id

### Request Example
```json
{
  "opacity": 50,
  "layer": 1
}
```

## overlay.setOpacity(_opacity_)

### Description
Sets the opacity of all active overlay layers. Layers that have not been used yet will not have their opacity changed. Opacity ranges from `0` (invisible) to `100` (completely opaque).

### Method
overlay.setOpacity

### Parameters
#### Path Parameters
- **opacity** (number) - Required - the opacity

### Request Example
```json
{
  "opacity": 75
}
```
```

--------------------------------

### Overlay Visibility Get/Set Functions

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Functions to get and set the visibility of overlay layers.

```APIDOC
## overlay.getVisibility(_layer = 0_)

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

### Method
overlay.getVisibility

### Parameters
#### Path Parameters
- **layer** (number) - Optional - the layer id. Defaults to `0`

### Returns
- **boolean** - whether the layer is showing

### Response Example
```json
{
  "visible": true
}
```

## overlay.setVisibility(_visible_ , _layer_)

### Description
Sets the visibility of the specified overlay layer.

### Method
overlay.setVisibility

### Parameters
#### Path Parameters
- **visible** (boolean) - Required - whether the layer should be showing
- **layer** (number) - Required - the layer id

### Request Example
```json
{
  "visible": true,
  "layer": 1
}
```

## overlay.setVisibility(_visible_)

### Description
Sets the visibility of all active overlay layers.

### Method
overlay.setVisibility

### Parameters
#### Path Parameters
- **visible** (boolean) - Required - whether the layers should be showing

### Request Example
```json
{
  "visible": false
}
```
```

--------------------------------

### Tileset Management Functions

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Functions to get and set primary and secondary tilesets for the currently opened map.

```APIDOC
## map.getPrimaryTileset()
### Description
Gets the name of the primary tileset for the currently-opened map.
### Response
- **primary tileset name** (string)

## map.setPrimaryTileset(tileset)
### Description
Sets the primary tileset for the currently-opened map.
### Parameters
- **tileset** (string) - Required - The tileset name

## map.getSecondaryTileset()
### Description
Gets the name of the secondary tileset for the currently-opened map.
### Response
- **secondary tileset name** (string)

## map.setSecondaryTileset(tileset)
### Description
Sets the secondary tileset for the currently-opened map.
### Parameters
- **tileset** (string) - Required - The tileset name
```

--------------------------------

### Porymap Scripting API: onMapOpened Callback

Source: https://huderlem.github.io/porymap/manual/settings-and-options.html

Example of the `onMapOpened` callback function in Porymap's scripting API. This function is executed when a map is opened.

```lua
function onMapOpened(map)
  print("Map opened: " .. map.name)
end
```

--------------------------------

### utility.showQuestion

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Displays a question dialog with Yes/No buttons.

```APIDOC
## utility.showQuestion

### Description
Displays a message box with a Question icon and Yes/No buttons. Execution pauses while open.

### Parameters
- **text** (string) - Required - Main message text
- **informativeText** (string) - Optional - Smaller text below main message
- **detailedText** (string) - Optional - Text hidden behind Show Details

### Response
- **Returns** (boolean) - true if Yes selected, false otherwise
```

--------------------------------

### map.getMetatileTiles

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Gets the tiles in the specified range of the metatile.

```APIDOC
## map.getMetatileTiles

### Description
Gets the tiles in the specified range of the metatile.

### Parameters
- **metatileId** (number) - Required - id of target metatile
- **tileStart** (number) - Optional - index of the first tile to get. Defaults to 0.
- **tileEnd** (number) - Optional - index of the last tile to get. Defaults to -1.

### Response
- **return** (array) - array of tiles in the specified range.
```

--------------------------------

### Registering Script Actions in Porymap

Source: https://huderlem.github.io/porymap/manual/settings-and-options.html

Demonstrates how to register custom script actions within Porymap. This is useful for extending Porymap's functionality with custom commands.

```lua
script.register("My Custom Action", function(args)
  -- Your script logic here
end)
```

--------------------------------

### map.getMetatileTile

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Gets the tile at the specified index of the metatile.

```APIDOC
## map.getMetatileTile

### Description
Gets the tile at the specified index of the metatile.

### Parameters
- **metatileId** (number) - Required - id of target metatile
- **tileIndex** (number) - Required - index of the tile to get

### Response
- **return** (object) - {tileId, xflip, yflip, palette}
```

--------------------------------

### map.getMetatileBehaviorName

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Gets the behavior name for the specified metatile.

```APIDOC
## map.getMetatileBehaviorName

### Description
Gets the behavior name for the specified metatile. Returns an empty string if the metatile’s behavior value has no name.

### Parameters
- **metatileId** (number) - Required - id of target metatile

### Response
- **return** (string) - the behavior name
```

--------------------------------

### utility.showMessage, utility.showWarning, utility.showError

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Displays modal message boxes to the user.

```APIDOC
## utility.showMessage / utility.showWarning / utility.showError

### Description
Displays a modal message box with an icon and an OK button. Execution pauses while open.

### Parameters
- **text** (string) - Required - Main message text
- **informativeText** (string) - Optional - Smaller text below main message
- **detailedText** (string) - Optional - Text hidden behind Show Details
```

--------------------------------

### map.getMetatileTerrainType

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Gets the terrain type for the specified metatile.

```APIDOC
## map.getMetatileTerrainType

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

### Parameters
- **metatileId** (number) - Required - id of target metatile

### Response
- **return** (number) - the terrain type
```

--------------------------------

### Calling a Porymap Script Action

Source: https://huderlem.github.io/porymap/manual/settings-and-options.html

Shows how to call a registered script action from within Porymap. This allows for the execution of custom logic defined elsewhere.

```lua
script.call("My Custom Action", {arg1 = 1, arg2 = "hello"})
```

--------------------------------

### map.getMetatileEncounterType

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Gets the encounter type for the specified metatile.

```APIDOC
## map.getMetatileEncounterType

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

### Parameters
- **metatileId** (number) - Required - id of target metatile

### Response
- **return** (number) - the encounter type
```

--------------------------------

### map.getMetatileLayerOrder

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Gets the current rendering order of metatile layers.

```APIDOC
## map.getMetatileLayerOrder

### Description
Gets the order that metatile layers are rendered for the current layout (0=bottom, 1=middle, 2=top).

### Response
- **Returns** (array) - Array of layers
```

--------------------------------

### Scripting API Callbacks

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

List of available event-driven callbacks that can be registered in custom scripts to respond to Porymap actions.

```APIDOC
## Scripting API Callbacks

### Description
These callbacks are triggered by specific actions within the Porymap application, allowing custom scripts to execute logic based on user interactions or project state changes.

### Available Callbacks
- **onProjectOpened** - Triggered when a project is opened.
- **onProjectClosed** - Triggered when a project is closed.
- **onMapOpened** - Triggered when a map is opened.
- **onLayoutOpened** - Triggered when a layout is opened.
- **onBlockChanged** - Triggered when a block is modified.
- **onBorderMetatileChanged** - Triggered when a border metatile is modified.
- **onBlockHoverChanged** - Triggered when the mouse hovers over a different block.
- **onBlockHoverCleared** - Triggered when the mouse stops hovering over a block.
- **onMapResized** - Triggered when a map is resized.
- **onBorderResized** - Triggered when the border is resized.
- **onMapShifted** - Triggered when a map is shifted.
- **onTilesetUpdated** - Triggered when a tileset is updated.
- **onMainTabChanged** - Triggered when the main tab is switched.
- **onMapViewTabChanged** - Triggered when the map view tab is switched.
- **onBorderVisibilityToggled** - Triggered when border visibility is toggled.
```

--------------------------------

### map.getMetatileAttributes

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Gets the raw attributes value for the specified metatile.

```APIDOC
## map.getMetatileAttributes

### Description
Gets the raw attributes value for the specified metatile.

### Parameters
- **metatileId** (number) - Required - id of target metatile

### Response
- **return** (number) - the raw attributes value
```

--------------------------------

### map.bucketFillFromSelection

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Performs a bucket fill using the current metatile selection.

```APIDOC
## map.bucketFillFromSelection(x, y, forceRedraw, commitChanges)

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

### Parameters
#### Arguments
- **x** (number) - Required - initial x coordinate
- **y** (number) - Required - initial y coordinate
- **forceRedraw** (boolean) - Optional - Force the map view to refresh. Defaults to true.
- **commitChanges** (boolean) - Optional - Commit the changes to the map’s edit/undo history. Defaults to true.
```

--------------------------------

### Scripting API Callbacks

Source: https://huderlem.github.io/porymap/manual/shortcuts.html

List of available event callbacks that can be registered in custom scripts to respond to Porymap actions.

```APIDOC
## Scripting API Callbacks

### Description
These callbacks allow custom scripts to execute logic when specific events occur within the Porymap application.

### Available Callbacks
- **onProjectOpened** - Triggered when a project is opened.
- **onProjectClosed** - Triggered when a project is closed.
- **onMapOpened** - Triggered when a map is opened.
- **onLayoutOpened** - Triggered when a layout is opened.
- **onBlockChanged** - Triggered when a block is modified.
- **onBorderMetatileChanged** - Triggered when a border metatile is modified.
- **onBlockHoverChanged** - Triggered when the mouse hovers over a different block.
- **onBlockHoverCleared** - Triggered when the mouse stops hovering over a block.
- **onMapResized** - Triggered when a map is resized.
- **onBorderResized** - Triggered when the border is resized.
- **onMapShifted** - Triggered when a map is shifted.
- **onTilesetUpdated** - Triggered when a tileset is updated.
- **onMainTabChanged** - Triggered when the main tab changes.
- **onMapViewTabChanged** - Triggered when the map view tab changes.
- **onBorderVisibilityToggled** - Triggered when border visibility is toggled.
```

--------------------------------

### map.magicFill

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Performs a magic fill operation starting at the given coordinates.

```APIDOC
## map.magicFill(x, y, metatileId, forceRedraw, commitChanges)

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

### Parameters
#### Arguments
- **x** (number) - Required - initial x coordinate
- **y** (number) - Required - initial y coordinate
- **metatileId** (number) - Required - metatile id to magic fill
- **forceRedraw** (boolean) - Optional - Force the map view to refresh. Defaults to true.
- **commitChanges** (boolean) - Optional - Commit the changes to the map’s edit/undo history. Defaults to true.
```

--------------------------------

### Settings Functions API

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

This section covers various utility functions for managing Porymap settings.

```APIDOC
## utility.getGridVisibility()

### Description
Gets the visibility of the map grid overlay.

### Method
GET

### Endpoint
/utility/gridVisibility

### Response
#### Success Response (200)
- **grid visibility** (boolean) - The current visibility state of the map grid overlay.
```

```APIDOC
## utility.setGridVisibility(_visible_)

### Description
Sets the visibility of the map grid overlay.

### Method
POST

### Endpoint
/utility/gridVisibility

### Parameters
#### Request Body
- **visible** (boolean) - Required - The desired visibility state for the map grid overlay.
```

```APIDOC
## utility.getBorderVisibility()

### Description
Gets the visibility of the map’s border.

### Method
GET

### Endpoint
/utility/borderVisibility

### Response
#### Success Response (200)
- **border visibility** (boolean) - The current visibility state of the map's border.
```

```APIDOC
## utility.setBorderVisibility(_visible_)

### Description
Sets the visibility of the map’s border.

### Method
POST

### Endpoint
/utility/borderVisibility

### Parameters
#### Request Body
- **visible** (boolean) - Required - The desired visibility state for the map's border.
```

```APIDOC
## utility.getSmartPathsEnabled()

### Description
Gets the toggle state of smart paths.

### Method
GET

### Endpoint
/utility/smartPathsEnabled

### Response
#### Success Response (200)
- **smart paths enabled** (boolean) - The current toggle state of smart paths.
```

```APIDOC
## utility.setSmartPathsEnabled(_enabled_)

### Description
Sets the toggle state of smart paths.

### Method
POST

### Endpoint
/utility/smartPathsEnabled

### Parameters
#### Request Body
- **enabled** (boolean) - Required - The desired toggle state for smart paths.
```

```APIDOC
## utility.getCustomScripts()

### Description
Gets the list of paths to custom scripts.

### Method
GET

### Endpoint
/utility/customScripts

### Response
#### Success Response (200)
- **string array of custom scripts paths** (array) - An array containing the paths to custom scripts.
```

```APIDOC
## utility.getMainTab()

### Description
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).

### Method
GET

### Endpoint
/utility/mainTab

### Response
#### Success Response (200)
- **current main tab index** (number) - The index of the currently selected main tab.
```

```APIDOC
## utility.setMainTab(_tab_)

### Description
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).

### Method
POST

### Endpoint
/utility/mainTab

### Parameters
#### Request Body
- **tab** (number) - Required - The index of the tab to select.
```

```APIDOC
## utility.getMapViewTab()

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

### Method
GET

### Endpoint
/utility/mapViewTab

### Response
#### Success Response (200)
- **current map view tab index** (number) - The index of the currently selected map view tab.
```

```APIDOC
## utility.setMapViewTab(_tab_)

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

### Method
POST

### Endpoint
/utility/mapViewTab

### Parameters
#### Request Body
- **tab** (number) - Required - The index of the tab to select.
```

```APIDOC
## utility.getMetatileLayerOrder()

### Description
Gets the order that metatile layers are rendered by default, where 0 is the bottom layer, 1 is the middle layer, and 2 is the top layer. The default order is [0, 1, 2].
If you’d like to get the metatile layer order for only the current layout, see `map.getMetatileLayerOrder` instead.

### Method
GET

### Endpoint
/utility/metatileLayerOrder

### Response
#### Success Response (200)
- **array of layers** (array) - An array representing the order of metatile layers.
```

```APIDOC
## utility.setMetatileLayerOrder(_order_)

### Description
Sets the order that metatile layers are rendered by default, where 0 is the bottom layer, 1 is the middle layer, and 2 is the top layer. The default order is [0, 1, 2].
If no elements are provided the layer order will be reset to the default. Any layer not listed in the provided `order` will not be rendered. Any additional elements after the first 3 are ignored.
If you’d like to set the metatile layer order for only the current layout, see `map.setMetatileLayerOrder` instead.

### Method
POST

### Endpoint
/utility/metatileLayerOrder

### Parameters
#### Request Body
- **order** (array) - Required - An array of layers specifying the rendering order.
```

```APIDOC
## utility.getMetatileLayerOpacity()

### Description
Gets the opacities that metatile layers are rendered with by default, where the first element is the bottom layer, the second element is the middle layer, and the third element is the top layer. The default opacities are [1.0, 1.0, 1.0].
If you’d like to get the metatile layer opacities for only the current layout, see `map.getMetatileLayerOpacity` instead.

### Method
GET

### Endpoint
/utility/metatileLayerOpacity

### Response
#### Success Response (200)
- **array of opacities for each layer** (array) - An array of opacities for each metatile layer.
```

```APIDOC
## utility.setMetatileLayerOpacity(_opacities_)

### Description
Sets the opacities that metatile layers are rendered with by default, where the first element is the bottom layer, the second element is the middle layer, and the third element is the top layer. The default opacities are [1.0, 1.0, 1.0].
Any additional elements after the first 3 are ignored. Any elements not provided will be rendered with opacity 1.0.
If you’d like to set the metatile layer opacities for only the current layout, see `map.setMetatileLayerOpacity` instead.

### Method
POST

### Endpoint
/utility/metatileLayerOpacity

### Parameters
#### Request Body
- **opacities** (array) - Required - An array of opacities for each layer.
```

--------------------------------

### Pokemon GFX Directory

Source: https://huderlem.github.io/porymap/manual/project-files.html

Directory `graphics/pokemon/` used to search for Pokémon icon.png files if they are not found via `symbol_pokemon_icon_table`.

```shell
graphics/pokemon/
```

--------------------------------

### Overlay Positioning API

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Methods for getting and setting the X and Y coordinates of overlay layers.

```APIDOC
## overlay.getX(layer)

### Description
Gets the x position of the specified overlay layer.

### Parameters
#### Arguments
- **layer** (number) - Optional - The layer id. Defaults to 0.

### Response
- **return** (number) - The pixel x coordinate.

## overlay.setX(x, layer)

### Description
Sets the x position of the specified overlay layer or all active layers.

### Parameters
#### Arguments
- **x** (number) - Required - The pixel x coordinate.
- **layer** (number) - Optional - The layer id.

## overlay.getY(layer)

### Description
Gets the y position of the specified overlay layer.

### Parameters
#### Arguments
- **layer** (number) - Optional - The layer id. Defaults to 0.

### Response
- **return** (number) - The pixel y coordinate.

## overlay.setY(y, layer)

### Description
Sets the y position of the specified overlay layer or all active layers.

### Parameters
#### Arguments
- **y** (number) - Required - The pixel y coordinate.
- **layer** (number) - Optional - The layer id.
```

--------------------------------

### Scripting API Constants

Source: https://huderlem.github.io/porymap/manual/shortcuts.html

System constants available for use within Porymap custom scripts.

```APIDOC
## Scripting API Constants

### Description
Constants defining limits and version information for the current Porymap project.

### Constants
- **constants.max_primary_tiles** (int)
- **constants.max_secondary_tiles** (int)
- **constants.max_primary_metatiles** (int)
- **constants.max_secondary_metatiles** (int)
- **constants.num_primary_palettes** (int)
- **constants.num_secondary_palettes** (int)
- **constants.layers_per_metatile** (int)
- **constants.tiles_per_metatile** (int)
- **constants.metatile_behaviors** (list)
- **constants.base_game_version** (string)
- **constants.version.major** (int)
- **constants.version.minor** (int)
- **constants.version.patch** (int)
```

--------------------------------

### Implement Grass Randomizer Script

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Full implementation of a grass-randomizing script that uses map.setMetatileId to replace painted grass tiles with random alternatives.

```javascript
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]);
    }
}

```

--------------------------------

### Overlay Scale Get/Set Functions

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Functions to get and set the horizontal and vertical scale of overlay layers.

```APIDOC
## overlay.getHorizontalScale(_layer = 0_)

### Description
Gets the horizontal scale of the specified overlay layer. `1.0` is normal size.

### Method
overlay.getHorizontalScale

### Parameters
#### Path Parameters
- **layer** (number) - Optional - the layer id. Defaults to `0`

### Returns
- **number** - the scale

### Response Example
```json
{
  "scale": 1.2
}
```

## overlay.getVerticalScale(_layer = 0_)

### Description
Gets the vertical scale of the specified overlay layer. `1.0` is normal size.

### Method
overlay.getVerticalScale

### Parameters
#### Path Parameters
- **layer** (number) - Optional - the layer id. Defaults to `0`

### Returns
- **number** - the scale

### Response Example
```json
{
  "scale": 1.2
}
```

## overlay.setHorizontalScale(_scale_ , _layer_)

### Description
Sets the horizontal scale of the specified overlay layer. `1.0` is normal size.

### Method
overlay.setHorizontalScale

### Parameters
#### Path Parameters
- **scale** (number) - Required - the scale to set
- **layer** (number) - Required - the layer id

### Request Example
```json
{
  "scale": 1.5,
  "layer": 1
}
```

## overlay.setHorizontalScale(_scale_)

### Description
Sets the horizontal scale of all active overlay layers. Layers that have not been used yet will not have their scale changed. `1.0` is normal size.

### Method
overlay.setHorizontalScale

### Parameters
#### Path Parameters
- **scale** (number) - Required - the scale to set

### Request Example
```json
{
  "scale": 1.5
}
```

## overlay.setVerticalScale(_scale_ , _layer_)

### Description
Sets the vertical scale of the specified overlay layer. `1.0` is normal size.

### Method
overlay.setVerticalScale

### Parameters
#### Path Parameters
- **scale** (number) - Required - the scale to set
- **layer** (number) - Required - the layer id

### Request Example
```json
{
  "scale": 1.5,
  "layer": 1
}
```

## overlay.setVerticalScale(_scale_)

### Description
Sets the vertical scale of all active overlay layers. Layers that have not been used yet will not have their scale changed. `1.0` is normal size.

### Method
overlay.setVerticalScale

### Parameters
#### Path Parameters
- **scale** (number) - Required - the scale to set

### Request Example
```json
{
  "scale": 1.5
}
```

## overlay.setScale(_hScale_ , _vScale_ , _layer_)

### Description
Sets the horizontal and vertical scale of the specified overlay layer. `1.0` is normal size.

### Method
overlay.setScale

### Parameters
#### Path Parameters
- **hScale** (number) - Required - the horizontal scale to set
- **vScale** (number) - Required - the vertical scale to set
- **layer** (number) - Required - the layer id

### Request Example
```json
{
  "hScale": 1.2,
  "vScale": 1.3,
  "layer": 1
}
```

## overlay.setScale(_hScale_ , _vScale_)

### Description
Sets the horizontal and vertical scale of all active overlay layers. `1.0` is normal size.

### Method
overlay.setScale

### Parameters
#### Path Parameters
- **hScale** (number) - Required - the horizontal scale to set
- **vScale** (number) - Required - the vertical scale to set

### Request Example
```json
{
  "hScale": 1.2,
  "vScale": 1.3
}
```
```

--------------------------------

### utility.log, utility.warn, utility.error

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Logging functions for debugging purposes.

```APIDOC
## utility.log / utility.warn / utility.error

### Description
Logs messages to the Porymap log file with specific prefixes ([INFO], [WARN], [ERROR]).

### Parameters
- **message** (string) - Required - The message to log
```

--------------------------------

### Define Metatile Label Prefix

Source: https://huderlem.github.io/porymap/manual/project-files.html

Used in `include/constants/metatile_labels.h` to read and write metatile labels. Requires 'yes' for both read and write access.

```c
#define define_metatile_label_prefix(name) name
```

--------------------------------

### Regex Behaviors

Source: https://huderlem.github.io/porymap/manual/project-files.html

Used in `include/constants/metatile_behaviors.h` to evaluate behavior constants.

```c
regex_behaviors
```

--------------------------------

### Get Metatile Layer Opacities

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Retrieves the opacities for metatile layers in the current layout. The opacities are ordered from bottom to top layer.

```APIDOC
## GET /map/getMetatileLayerOpacity

### Description
Gets the opacities that metatile layers are rendered with for the current layout, where the first element is the bottom layer, the second element is the middle layer, and the third element is the top layer. The default opacities are `[1.0, 1.0, 1.0]`.
If you’d like to get the default metatile layer opacities for all layouts, see `utility.getMetatileLayerOpacity` instead.

### Method
GET

### Endpoint
/map/getMetatileLayerOpacity

### Response
#### Success Response (200)
- **opacities** (array) - An array of opacities for each layer.
```

--------------------------------

### Project Callbacks

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Callbacks triggered when project files are opened or closed.

```APIDOC
## onProjectOpened(projectPath)

### Description
Called when Porymap successfully opens a project.

### Parameters
- **projectPath** (string) - Required - the directory path of the opened project

## onProjectClosed(projectPath)

### Description
Called when Porymap closes a project.

### Parameters
- **projectPath** (string) - Required - the directory path of the closed project
```

--------------------------------

### Porymap Changelog - Version 5.4.1

Source: https://huderlem.github.io/porymap/manual/tileset-editor.html

Summary of changes for Porymap version 5.4.1, including bug fixes.

```APIDOC
## Changelog: 5.4.1 - 2024-03-21

### Description
This entry details the updates included in Porymap version 5.4.1, released on March 21, 2024.

### Changes

- **Fixed**: Bug fixes and resolved issues.
```

--------------------------------

### Define Species Prefix

Source: https://huderlem.github.io/porymap/manual/project-files.html

Used in `include/constants/species.h` to find species names. Requires 'yes' for read access.

```c
#define define_species_prefix(name) name
```

--------------------------------

### Constants Metatile Behaviors

Source: https://huderlem.github.io/porymap/manual/project-files.html

Located in `include/constants/metatile_behaviors.h`. Used to evaluate `regex_behaviors` constants.

```c
constants_metatile_behaviors
```

--------------------------------

### Porymap Scripting API: onBlockChanged Callback

Source: https://huderlem.github.io/porymap/manual/settings-and-options.html

Example of the `onBlockChanged` callback function in Porymap's scripting API. This function is executed when a map block is changed.

```lua
function onBlockChanged(map, blockX, blockY, newBlockID)
  print(string.format("Block changed at (%d, %d) to %d", blockX, blockY, newBlockID))
end
```

--------------------------------

### Scripting API Callbacks

Source: https://huderlem.github.io/porymap/reference/related-projects.html

List of available event-driven callbacks that can be registered in custom scripts.

```APIDOC
## Scripting API Callbacks

### Description
These callbacks are triggered by specific actions within the Porymap application, allowing scripts to respond to project, map, or UI changes.

### Available Callbacks
- **onProjectOpened** - Triggered when a project is loaded.
- **onProjectClosed** - Triggered when a project is closed.
- **onMapOpened** - Triggered when a map is opened for editing.
- **onLayoutOpened** - Triggered when a layout is opened.
- **onBlockChanged** - Triggered when a metatile block is modified.
- **onBorderMetatileChanged** - Triggered when a border metatile is modified.
- **onBlockHoverChanged** - Triggered when the mouse hovers over a different block.
- **onBlockHoverCleared** - Triggered when the mouse leaves a block.
- **onMapResized** - Triggered when a map's dimensions are changed.
- **onBorderResized** - Triggered when the border dimensions are changed.
- **onMapShifted** - Triggered when the map content is shifted.
- **onTilesetUpdated** - Triggered when tileset data is updated.
- **onMainTabChanged** - Triggered when the main application tab changes.
- **onMapViewTabChanged** - Triggered when the map view tab changes.
- **onBorderVisibilityToggled** - Triggered when the border visibility is toggled.
```

--------------------------------

### Porymap Scripting API: onMapResized Callback

Source: https://huderlem.github.io/porymap/manual/settings-and-options.html

Example of the `onMapResized` callback function in Porymap's scripting API. This function is executed when a map's dimensions are changed.

```lua
function onMapResized(map, newWidth, newHeight)
  print(string.format("Map resized to %dx%d", newWidth, newHeight))
end
```

--------------------------------

### Porymap Changelog - Version 5.1.1

Source: https://huderlem.github.io/porymap/manual/tileset-editor.html

Summary of changes for Porymap version 5.1.1, including added features, modifications, and bug fixes.

```APIDOC
## Changelog: 5.1.1 - 2023-02-20

### Description
This entry details the updates included in Porymap version 5.1.1, released on February 20, 2023.

### Changes

- **Added**: New features and functionalities introduced in this version.
- **Changed**: Modifications to existing features or behavior.
- **Fixed**: Bug fixes and resolved issues.
```

--------------------------------

### Scripting API Constants

Source: https://huderlem.github.io/porymap/manual/navigation.html

Constants provide predefined values for various aspects of the game and Porymap, useful for scripting and configuration.

```javascript
constants.max_primary_tiles
constants.max_secondary_tiles
constants.max_primary_metatiles
constants.max_secondary_metatiles
constants.num_primary_palettes
constants.num_secondary_palettes
constants.layers_per_metatile
constants.tiles_per_metatile
constants.metatile_behaviors
constants.base_game_version
constants.version.major
constants.version.minor
constants.version.patch
```

--------------------------------

### Overlay Transformation API

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Methods for scaling, rotating, and moving overlay layers.

```APIDOC
## overlay.getRotation(layer)

### Description
Gets the angle the specified overlay layer is rotated to.

### Parameters
#### Arguments
- **layer** (number) - Optional - The layer id. Defaults to 0.

### Response
- **return** (number) - The angle the layer is rotated to.

## overlay.setRotation(angle, layer)

### Description
Sets the angle the specified overlay layer is rotated to. Can also be used to set the angle for all active layers.

### Parameters
#### Arguments
- **angle** (number) - Required - The angle to set.
- **layer** (number) - Optional - The layer id.

## overlay.rotate(degrees, layer)

### Description
Rotates the specified overlay layer or all active layers. Positive values are clockwise, negative are counterclockwise.

### Parameters
#### Arguments
- **degrees** (number) - Required - The number of degrees to rotate.
- **layer** (number) - Optional - The layer id.
```

--------------------------------

### overlay.createImage

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Creates a transformed image on an overlay layer. Allows for scaling, flipping, and defining specific areas of the source image to be used.

```APIDOC
## overlay.createImage

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

### Method
Not applicable (function call)

### Endpoint
Not applicable (local function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **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) - Optional. 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) - Optional. 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`.
* **xOffset** (number) - Optional. The x pixel coordinate on the original image where data should be read from. Defaults to `0`.
* **yOffset** (number) - Optional. The y pixel coordinate on the original image where data should be read from. Defaults to `0`.
* **hScale** (number) - Optional. The horizontal scale for the image. Negative values will be a horizontal flip of the original image. Defaults to `1`.
* **vScale** (number) - Optional. The vertical scale for the image. Negative values will be a vertical flip of the original image. Defaults to `1`.
* **paletteId** (number) - Optional. 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) - Optional. Whether the color at index 0 should be overwritten with transparent pixels. Defaults to `false`.
* **layer** (number) - Optional. The layer id. Defaults to `0`.
* **useCache** (boolean) - Optional. Whether the image should be saved/loaded using the cache. Defaults to `true`.

### Request Example
```javascript
overlay.createImage(50, 50, "path/to/sprite.png", 32, 32, 0, 0, 2, 2, -1, false, 0, true);
```

### Response
#### Success Response (200)
None (function modifies overlay state)

#### Response Example
None
```

--------------------------------

### Porymap Scripting API - Constants

Source: https://huderlem.github.io/porymap/manual/tileset-editor.html

This section defines the constants available for use in custom scripts, providing fixed values for various project parameters and configurations.

```APIDOC
## Porymap Scripting API - Constants

### Description
Constants represent fixed values used throughout Porymap's scripting environment. They provide a standardized way to reference important project parameters.

### Constants

- **`constants.max_primary_tiles`**: Maximum number of primary tiles.
- **`constants.max_secondary_tiles`**: Maximum number of secondary tiles.
- **`constants.max_primary_metatiles`**: Maximum number of primary metatiles.
- **`constants.max_secondary_metatiles`**: Maximum number of secondary metatiles.
- **`constants.num_primary_palettes`**: Number of primary palettes.
- **`constants.num_secondary_palettes`**: Number of secondary palettes.
- **`constants.layers_per_metatile`**: Number of layers per metatile.
- **`constants.tiles_per_metatile`**: Number of tiles per metatile.
- **`constants.metatile_behaviors`**: An object or array containing definitions for metatile behaviors.
- **`constants.base_game_version`**: The base game version Porymap is targeting.
- **`constants.version.major`**: Major version number of Porymap.
- **`constants.version.minor`**: Minor version number of Porymap.
- **`constants.version.patch`**: Patch version number of Porymap.
```

--------------------------------

### Porymap Changelog - Version 5.1.0

Source: https://huderlem.github.io/porymap/manual/tileset-editor.html

Summary of changes for Porymap version 5.1.0, including added features, modifications, and bug fixes.

```APIDOC
## Changelog: 5.1.0 - 2023-01-22

### Description
This entry details the updates included in Porymap version 5.1.0, released on January 22, 2023.

### Changes

- **Added**: New features and functionalities introduced in this version.
- **Changed**: Modifications to existing features or behavior.
- **Fixed**: Bug fixes and resolved issues.
```

--------------------------------

### utility.getInputItem

Source: https://huderlem.github.io/porymap/manual/scripting-capabilities.html

Displays a text input dialog with an items dropdown.

```APIDOC
## utility.getInputItem

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

### Parameters
#### Arguments
- **title** (string) - Required - The text in the window title bar
- **label** (string) - Required - The text adjacent to the input entry area
- **items** (array) - Required - An array of text items that will populate the dropdown
- **default** (number) - Optional - The index of the item to select by default. Defaults to 0
- **editable** (boolean) - Optional - Whether the user is allowed to enter their own text instead. Defaults to false

### Response
#### Success Response
- **input** (string) - The input text
- **ok** (boolean) - True if OK was selected, false if Cancel was selected or window closed
```

--------------------------------

### Porymap Changelog - Version 5.3.0

Source: https://huderlem.github.io/porymap/manual/tileset-editor.html

Summary of changes for Porymap version 5.3.0, including added features, modifications, and bug fixes.

```APIDOC
## Changelog: 5.3.0 - 2024-01-15

### Description
This entry details the updates included in Porymap version 5.3.0, released on January 15, 2024.

### Changes

- **Added**: New features and functionalities introduced in this version.
- **Changed**: Modifications to existing features or behavior.
- **Fixed**: Bug fixes and resolved issues.
```

--------------------------------

### Initial Facing Table

Source: https://huderlem.github.io/porymap/manual/project-files.html

Read from `src/event_object_movement.c`. This table is used to determine the initial facing direction of event objects.

```c
initial_facing_table
```

--------------------------------

### Constants Species

Source: https://huderlem.github.io/porymap/manual/project-files.html

Located in `include/constants/species.h`. Used to find names using `define_species_prefix`.

```c
constants_species
```

--------------------------------

### Porymap Changelog - Version 5.0.0

Source: https://huderlem.github.io/porymap/manual/tileset-editor.html

Summary of changes for Porymap version 5.0.0, including breaking changes, added features, modifications, and bug fixes.

```APIDOC
## Changelog: 5.0.0 - 2022-10-30

### Description
This entry details the updates included in Porymap version 5.0.0, released on October 30, 2022. This version includes breaking changes.

### Changes

- **Breaking Changes**: Significant changes that may require project updates.
- **Added**: New features and functionalities introduced in this version.
- **Changed**: Modifications to existing features or behavior.
- **Fixed**: Bug fixes and resolved issues.
```
Tokens:
Raw