← Back to RPG Maker

Scripting Reference

Every hook and every game API method available to Accessible RPG Creator project scripts — the same reference available in-app under F1 → Scripting Reference.

Hooks

Hooks fire automatically when something happens in the game. Attach a handler with a decorator, e.g. @on_step(), above a function that takes game as its first argument.

@on_pre_game_start()

Fires before the built-in name/class creation flow, letting you replace it with a custom intro. Return False from a handler to skip the default flow; call game.start_default_flow() when your intro is done.

@on_game_start()

Fires once, right after the player is fully created and about to begin exploring.

@on_enter_map()

Fires when the player enters a map, including after game.teleport(). Filter by map name: @on_enter_map('town').

@on_leave_map()

Fires when the player leaves a map. Filter by map name.

@on_step()

Fires after every successful player move. Filter by map name.

@on_interact_npc()

Fires when the player interacts with an NPC. kwargs: npc_name, npc_custom (the NPC's custom editor fields). Filter by NPC name. Return False to block the NPC's default dialogue.

@on_combat_start()

Fires when a combat encounter begins. kwargs: enemy_id, enemy_name. Filter by enemy id.

@on_combat_end()

Fires when combat ends. kwargs: result ('victory' or 'defeat'), enemy_id, enemy_name. Filter by enemy id.

@on_item_use()

Fires when the player uses an item. Filter by item name. Return False to block the item's default effect.

@on_item_pickup()

Fires when the player picks up an item. Filter by item name.

@on_key_press()

Fires on every key press during gameplay (Test Mode only). kwargs: key. Filter by key name.

@on_game_load()

Fires when a saved game is loaded.

Game API

Methods and properties available on the game object passed into every hook handler.

Speech/Audio

game.speak(text, interrupt=False)

Speak text via the active TTS engine (NVDA or SAPI).

game.play_sound(name)

Play a loaded sound by name (one-shot effect).

game.play_music(filename, loops=0, volume=1.0)

Stream a long audio file (intro narration, cinematic music). loops=-1 repeats forever.

game.stop_music(fadeout_ms=0)

Stop music started with play_music(); fadeout_ms=0 stops immediately.

game.set_music_state(state)

Switch the background-music state: exploration, combat, dialogue, danger, victory, defeat, or silent. Tracks per state are set per-map in the editor's Map Music Settings.

Menus/Input

game.ask_choice(prompt, options, callback, on_cancel=None)

Show a choice menu; calls callback with the chosen option string.

game.ask_text(prompt, callback)

Ask the player to type text; calls callback with the entered string.

game.start_default_flow()

Resume the built-in name/class creation flow after a custom on_pre_game_start intro.

Inventory

game.give_item(item_name)

Add an item to the player's inventory by name.

game.remove_item(item_name)

Remove an item from inventory. Returns False if not found.

game.has_item(item_name)

Check whether the player has an item. Returns True/False.

game.item_count(item_name)

Count how many of an item the player has.

Quests

game.set_quest(quest_id, status)

Set a quest's status directly, e.g. 'active' or 'completed'.

game.get_quest_status(quest_id)

Get a quest's current status, or None if not started.

Map/World

game.current_map

Property: the name of the current map.

game.get_tile(x, y)

Get the tile type at a position on the current map, or None.

game.change_tile(x, y, tile_type)

Change a tile on the current map.

game.teleport(map_name, x, y)

Move the player to (x, y) on another map. Loads the map, updates audio/position, and fires on_leave_map / on_enter_map — useful for a heal-point return after a loss, or a Fly/warp item.

game.get_npc(name)

Get info (name, x, y, dialogue) about an NPC on the current map, or None.

Combat

game.start_combat(enemy_id)

Start a combat encounter with the given enemy definition id.

Settings

game.currency_name

Property: the in-game currency's display name (from Game Settings).

Utility

game.log(message)

Print a message to the game log, for debugging scripts.

Persistent Data

game.variables

A plain dict for your own persistent state, e.g. game.variables['isNight'] = True. Saved and loaded with the game.

Player

game.player.health / .mana

Read or set current health/mana; writes are clamped to max_health/max_mana.

game.player.max_health / .max_mana

Read-only: the player's maximum health/mana.

game.player.stats / get_stat(name) / set_stat(name, value)

Read the full stats dict, or get/set a single stat by name.

game.player.level / .xp

Read the player's level; read or set experience points.

game.player.gold

Read or set the player's currency amount.

game.player.inventory / .equipment / .quests

Read-only snapshots: inventory list, equipped-slot dict, quest-status dict.

game.player.x / .y

Read-only: the player's current position on the map.

game.player.name / .player_class

Read-only: the player's chosen name and class id.