Map Events and Regions
Connect NPCs, chests, transfers, triggers, encounter regions, weather, and map state.
Map events
Map events are user-facing gameplay objects placed on maps. They are useful for classic adventure/RPG workflows and for visual no-code logic.
| Event type | Use it for | Common mistake |
|---|---|---|
| Door / Transfer | Move player to another area, scene, or map point. | Missing destination, wrong target scene, no spawn point. |
| Chest | Give an item, play SFX/VFX, then mark opened. | Missing item resource, repeated rewards, no opened state. |
| NPC | Show dialogue, start quest, open shop, or give information. | Missing dialogue resource, no interaction trigger, broken quest reference. |
| Trigger | Start a cutscene, change variable, spawn enemy, play sound, or transition. | Trigger area too small, wrong collision layer, no action assigned. |
| Spawn / Exit | Mark where actors enter or leave a map. | Missing link between entrance and destination. |
Regions, encounters, music, weather, collision, and navigation
Regions give parts of a map gameplay meaning. v0.9.4 documentation can describe more than only encounters/music/weather. Public map-region behavior can include biome, encounter, music zone, weather zone, quest zone, cutscene trigger, safe zone, danger zone, fast travel, spawn, collision, navigation, and custom markers.
Practical examples:
- Paint an encounter region to control enemy encounter behavior.
- Paint a music zone to mark where a map BGM should apply.
- Paint a weather zone to mark rain, fog, storm, or ambience behavior.
- Paint a safe zone where random encounters or danger effects should stop.
- Paint collision and navigation helpers to guide movement and pathfinding setup.
- Paint a fast travel region to connect to another map or hub.
Map events, pages, conditions, commands, self-switches
Event templates
| Template | Typical use |
|---|---|
| door | Transfer to another map/scene/cell |
| chest | Give item/gold once, play SFX/VFX, set self-switch |
| npc | Dialogue, quest, shop, relationship |
| sign | Show text |
| save_point | Open save menu or save game |
| shopkeeper | Open shop resource |
| quest_giver | Start or complete quest |
| enemy_encounter | Start battle/encounter |
| pickup | Give item on touch/interact |
| cutscene_trigger | Run cinematic or sequence |
| damage_tile | Damage player on touch/step |
| healing_tile | Heal player on touch/step |
| teleport | Move player to target map/marker/cell |
| region_trigger | React to region entry/exit |
| music_zone | Change BGM or ambience |
| weather_zone | Apply weather |
Event page triggers
| Trigger | Use when |
|---|---|
| action_button | Player presses interact near event |
| player_touch | Player touches/enters event |
| event_touch | Another event touches this event |
| autorun | Runs automatically and can block/drive flow |
| parallel | Runs repeatedly/periodically; use carefully |
| region_enter | Runs when actor enters region |
| region_leave | Runs when actor leaves region |
| on_map_load | Runs when map loads |
| on_quest_state_changed | Runs when linked quest state changes |
Event page conditions
| Condition | Example |
|---|---|
| always | Page is always available |
| switch | Door open if global switch is on |
| self_switch | Chest opened state A/B/C/D |
| variable | Run page if variable is above/below value |
| item | Door opens if player has key |
| quest | NPC changes dialogue based on quest status |
| actor_in_party | Event requires specific party member |
| enemy_defeated | Trigger after boss is defeated |
| region | Page only available in specific region |
| visual_logic | Page depends on graph/context flag |
Event commands
| Command | Beginner example |
|---|---|
| dialogue | Show NPC/sign/chest text |
| show_choice | Ask yes/no or route choice |
| set_switch | Mark door unlocked |
| set_variable | Count kills, score, route points |
| add_item | Chest gives potion/key |
| remove_item | Door consumes key |
| change_gold | Quest reward |
| teleport | Move player |
| change_scene | Load another scene |
| play_se | Chest/door/pickup sound |
| play_bgm | Change music |
| stop_bgm | Stop music |
| fade_screen | Transition/cutscene |
| shake_screen | Hit/scare/earthquake |
| force_battle | Start battle |
| change_quest | Start/update/complete quest |
| open_shop | Open shop UI/resource |
| save_game | Save point |
| open_menu | Open feature list/pause/etc. |
| set_weather | Apply weather |
| show_animation | Visual feedback |
| change_hp | Damage/heal actor |
| wait | Delay sequence |
| branch | Conditional flow |
Self-switch tutorial
Self-switches for one-shot events
Use self-switches for event-local state.
Chest Page 1: Condition: self_switch A is OFF Commands: add_item potion → play_se chest_open → set self_switch A ON
Chest Page 2: Condition: self_switch A is ON Commands: dialogue "The chest is empty."
Self-switches are better than global switches for repeated objects because each event remembers its own state.
