syntax_reference.txt

========================================
 TORCH v0.3.6 — TORSCRIPT REFERENCE
========================================

COMMANDS
--------
  torch                        Main menu
  torch gui                    Launch web GUI
  torch init                   First-time setup
  torch sync MapName           Sync one map to game folder
  torch sync                   Sync all enrolled maps
  torch build                  Build ROM (auto-syncs stale maps)
  torch restore                Verified build snapshot restore
  torch restore MapName        Interactive workspace restore
  torch status                 Map health indicators
  torch enroll [MapName|--all] Enroll maps in registry
  torch unenroll MapName       Remove map from registry
  torch script MapName         Script Studio (TUI)
  torch trainers               Trainer editor
  torch wild / encounters      Encounter editor
  torch npc MapName            NPC editor
  torch dex                    Pokemon browser
  torch items                  Item editor
  torch moves                  Move editor
  torch learnsets              Learnset editor
  torch flags [MapName]        Flag browser
  torch shops [MapName]        Shop editor
  torch heal                   Heal location manager
  torch music                  Music browser
  torch explore [MapName]      Map Explorer
  torch tileset                Tileset assistant
  torch template [type] [args] Building templates
  torch rom                    ROM metadata editor
  torch settings               Game settings menu
  torch scorch                 SCORCH wizard
  torch scorch phoenix         Full vanilla wipe
  torch scorch report          Scan-only report
  torch scorch restore         Restore from SCORCH snapshot
  torch config                 Configuration manager
  torch backup [tag]           Create backup
  torch backup list            List backups
  torch backup prune           Enforce retention policy
  torch fork                   Clone project for experimentation
  torch new                    Create new project from GitHub
  torch upgrade [--check|--to] Upgrade expansion version
  torch versions [subcommand]  Game version control
  torch decompile file [Map]   Decompile .pory to TorScript
  torch decompile-inc file     Decompile .inc to Poryscript
  torch --project "Name" cmd   Select project for this command
  torch <name>                 Standalone compile (.txt -> .pory)

========================================
 WORKSPACE
========================================
  ~/ROMHacking/TORCH/<Project>/<MapName>/
    setup.pory               Mapscripts, shared text/movement
    legacy.pory              Auto-migrated old assembly
    battle_TRAINER_*.pory    Battle text from torch battle
    *.txt                    TorScript files (compiled)
    *.pory                   Raw Poryscript (passed through)
    backups/                 Snapshots + safety net zips

========================================
 TEXTBOX LIMITS
========================================
  38 chars max per line
  2 lines per textbox
  Line break codes:
    \n   New line (within same box)
    \p   New paragraph (press A, new box)
    \l   Scroll line
    $    End of string

========================================
 SCRIPT STRUCTURE
========================================

TOP-LEVEL DIRECTIVES
--------------------
alias name npcN              Define actor alias (auto-creates LOCALID)
pokemon species npcN         Declare Pokemon actor (enables faint/revive)
mapscripts LabelName         Mapscripts block
text Label "content$"        Named text block (reusable)
movement Label               Start named movement block
endmovement                  End named movement block
movement Label { cmd, cmd }  Inline movement block
label ScriptName             Start a script block
script ScriptName            Same as label

SCRIPT FLOW
-----------
lock                         Lock all movement (unfreezes Pokemon actors)
end                          Release all + end script
release                      Release single NPC + end script
goto Label                   Unconditional jump
call Label                   Call subroutine
return                       Return from subroutine
closemessage                 Close dialogue box
faceplayer                   NPC faces player
special FuncName             Call special C function
waitstate                    Wait for special to complete
gotoif FLAG_NAME Label       Jump if flag is set

----------------------------------------
 ACTORS
----------------------------------------
player                     The player character
npc5                       Object event local ID 5
alias buster npc5          "buster" = LOCALID_BUSTER (5)
                           Auto-generates const declaration.
pokemon pikachu npc2       Pokemon actor with idle animation.
                           Auto-generates const + tracks freeze state.

----------------------------------------
 DIALOGUE
----------------------------------------
Inline (auto-creates text label):
  "Hello there!"
  "This is a second text box."

NPC-style (different message box):
  msgnpc "Hey!$"

Multi-line (continuation lines in quotes):
  "This is a long\n"
  "piece of dialogue.\p"
  "And it continues."

Named text block (top-level, outside scripts):
  text MyTextLabel "The content here.$"

Auto-adds $ at end if you forget it.

Note: msg "text" also works but bare quoted strings
inside a script block are the preferred syntax.

----------------------------------------
 MOVEMENT
----------------------------------------
buster face down           Face direction (up/down/left/right)
buster face player         Face toward the player
buster face away           Face away from the player
buster walk up 3           Walk 3 tiles up (normal speed)
buster walkfast up 7       Walk fast (run speed)
buster walkslow down 2     Walk slow
buster run left 4          Same as walkfast
buster jump up             1-tile jump
buster jump up 2           2-tile jump
buster slide right 3       Slide (no walk animation)
buster do MyMoveLabel      Play a named movement block

Walk-to-target (dynamic destination, resolves at runtime):
  clyde walkto 25 61             Absolute: walk to tile (25,61)
  clyde walkto player 0 1        Relative: walk to (player_x, player_y+1)
  clyde walkto buster -1 0       Relative: walk to (buster_x-1, buster_y)
  clyde walkfastto player 1 0    Fast walk to target
  clyde walkslowto buster 0 2    Slow walk to target
  clyde runto player 0 1         Same as walkfastto

  Walks L-shaped (X axis first, then Y axis).
  Offsets: positive X = right, positive Y = down.
  Uses VAR_0x8004-0x8007 as scratch variables.
  Cannot use + parallel syntax (use separate lines).

Parallel movement (same line, + separator):
  buster face down + player face down

All movement auto-generates applymovement + waitmovement.

----------------------------------------
 NAMED MOVEMENT BLOCKS
----------------------------------------
Multi-line (top-level, outside scripts):

  movement MyMoveLabel
    face_player
    delay_16
    delay_16
    face_up
  endmovement

Single-line:
  movement MyMoveLabel { face_down, walk_up, walk_up }

Repeat syntax:
  movement MyMoveLabel { walk_down * 3, face_up }

Then reference with: buster do MyMoveLabel

AVAILABLE MOVEMENT COMMANDS:
  Face:      face_down, face_up, face_left, face_right,
             face_player, face_away_player
  Walk:      walk_down, walk_up, walk_left, walk_right
  Walk slow: walk_slow_down, walk_slow_up, walk_slow_left,
             walk_slow_right
  Walk fast: walk_fast_down, walk_fast_up, walk_fast_left,
             walk_fast_right
  Walk in place: walk_in_place_down, walk_in_place_up,
             walk_in_place_left, walk_in_place_right,
             walk_in_place_fast_down, walk_in_place_fast_up,
             walk_in_place_fast_left, walk_in_place_fast_right
  Jump:      jump_down, jump_up, jump_left, jump_right
  Jump 2:    jump_2_down, jump_2_up, jump_2_left, jump_2_right
  Jump in place: jump_in_place_down, jump_in_place_up,
             jump_in_place_left, jump_in_place_right
  Slide:     slide_down, slide_up, slide_left, slide_right
  Delay:     delay_1, delay_2, delay_4, delay_8, delay_16
  Visibility: set_visible, set_invisible
  Locking:   lock_facing_direction, unlock_facing_direction,
             disable_anim, enable_anim
  Emotes:    emote_exclamation_mark, emote_question_mark,
             emote_double_exclamation_mark, emote_x,
             emote_heart, emote_dot_dot_dot
  End:       step_end

----------------------------------------
 EMOTES
----------------------------------------
emote buster !             Exclamation mark
emote buster ?             Question mark
emote buster !!            Double exclamation
emote buster x             X mark
emote buster heart         Heart
emote buster ...           Dot dot dot

Custom emotes: add to config/emotes.conf

----------------------------------------
 SCREEN EFFECTS
----------------------------------------
fade black                 Fade to black
fade in                    Fade from black
fade from black            Fade from black (explicit)
fade white                 Fade to white
fade from white            Fade from white
fade in white              Fade from white (alias)

----------------------------------------
 SOUND
----------------------------------------
sound SE_EXIT              Play sound effect
music MUS_ROUTE101         Play background music
fanfare MUS_OBTAIN_ITEM    Play fanfare + wait
cry SPECIES_KOFFING        Play Pokemon cry

----------------------------------------
 TIMING
----------------------------------------
pause                      Short pause (~0.27s / 16 frames)
pause long                 Longer pause (~0.53s / 32 frames)
pause 60                   Custom frame count

----------------------------------------
 FLAGS & VARIABLES
----------------------------------------
flag set FLAG_NAME         Set a flag
flag clear FLAG_NAME       Clear a flag
var VAR_NAME value         Set a variable
gotoif FLAG_NAME Label     Goto if flag is set

----------------------------------------
 OBJECT MANAGEMENT
----------------------------------------
hide buster                Despawn (removeobject)
show buster                Spawn (addobject)
remove buster              Same as hide
add buster                 Same as show
setpos clyde 28 62         Set NPC position

----------------------------------------
 CAMERA
----------------------------------------
shake 1 8                  Shake camera (intensity, count)
camera pan down 2          Pan camera 2 tiles south
camera pan up 3            Pan camera 3 tiles north
camera pan left 1          Pan camera 1 tile west
camera pan right 4         Pan camera 4 tiles east
camera reset               Recenter camera on player
camera reset warp MAP X Y  Warp to specific location (ends script)
camera reset 0 2           Manual offset reset (cross-label use)

Camera pan auto-spawns an invisible camera object on
first use, then moves it via applymovement. Multiple
pans accumulate: pan down 3 + pan right 2 means reset
corrects by (2, 3). Opposing pans cancel.

Camera reset uses a small engine patch (auto-applied on
first use) to reverse the position offset caused by
CameraMove(). Script execution continues normally after
reset -- no warp, no music restart, no NPC position reset.

Camera reset warp is an alternative that warps the player
to explicit coordinates. It terminates script execution.
Use for cross-map cutscene endings.

Camera reset with manual offsets is for cross-label
scenarios where the compiler cannot track accumulated
pans (e.g. goto from a panning script to a reset script).

Notes:
- Camera commands cannot use '+' parallel syntax
- camera reset uses VAR_0x8004/VAR_0x8005 as scratch
- Battles destroy the camera object but the offset
  persists; camera reset still works after battles

----------------------------------------
 GIVE ITEM
----------------------------------------
give ITEM_CONSTANT [quantity]
    Give an item to the player with automatic bag-full
    safety check. Compiles to giveitem() + bag-full branch.
    BagFull label auto-generated at end of script.
    Examples:
        give ITEM_POTION        -- give 1 potion
        give ITEM_RARE_CANDY 3  -- give 3 rare candies

----------------------------------------
 POKEMON ACTORS
----------------------------------------
pokemon pikachu npc2       Declare a Pokemon NPC actor

faint pikachu              Stop idle animation (fainted state)
revive pikachu             Restart idle animation

Pokemon actors are declared at the top of a script file
using the `pokemon` directive instead of `alias`. This
tracks the actor's freeze state:
- lock auto-unfreezes Pokemon actors
- hide/remove waits for movement then freezes
- show/add unfreezes so idle animation resumes
- faint forces face-down + freeze
- revive unfreezes via callnative

Requires the ScriptUnfreezePokemonActor engine patch,
which TORCH auto-applies on first use.

----------------------------------------
 FOLLOWER NPCs
----------------------------------------
follower add local LOCALID PARTNER [FLAGS]
    Set an existing map NPC as follower

follower add dynamic GFX PARTNER [FLAGS]
    Create a new follower NPC dynamically

follower remove            Destroy follower NPC
follower face              Face follower toward player
follower hide [speed]      Hide follower (optional speed)
follower check             Check if follower exists
follower change PARTNER    Change follower's battle partner

FLAGS defaults to FNPC_ALL if omitted.
Speed options: FOLLOWER_MOVE_SLOW, FOLLOWER_MOVE_FAST, etc.

Requires pokeemerald-expansion follower NPC system.

----------------------------------------
 MULTI BATTLES
----------------------------------------
multi 2v2 TRAINER_A TextA TRAINER_B TextB PARTNER
    2 vs 2 double battle

multi 2v1 TRAINER_A TextA PARTNER
    2 vs 1 double battle

multi 2v2_fixed TRAINER_A TextA TRAINER_B TextB PARTNER
    Fixed 2v2 (predetermined partner actions)

multi 2v1_fixed TRAINER_A TextA PARTNER
    Fixed 2v1

Text args are named text block labels.

----------------------------------------
 TRAINER BATTLES
----------------------------------------
Legacy single-line:
  trainerbattle_single TRAINER_ID, IntroText, DefeatText
  trainerbattle_double TRAINER_ID, Intro, Defeat, NotEnough
  trainerbattle_rematch TRAINER_ID, Intro, Defeat
  trainerbattle_rematch_double TRAINER_ID, Intro, Defeat, NotEnough
  trainerbattle_no_intro TRAINER_ID, DefeatText
  trainerbattle_two_trainers TRAINER_A, IntroA, DefeatA,
      TRAINER_B, IntroB, DefeatB

Expanded form (auto-generates text labels):
  trainerbattle_single TRAINER_RIVAL
      intro "Let's battle!"
      defeated "You're tough..."
      postbattle "I'll train harder."

Text labels must be named text blocks for legacy form.
Expanded form creates them automatically.

----------------------------------------
 PASS-THROUGH
----------------------------------------
pory somecommand(args)     Outputs Poryscript line as-is
raw somecommand args       Same as pory

Examples:
  pory applymovement(LOCALID_CLYDE, MyMovement)
  pory waitmovement(0)
  pory lock
  pory release
  pory end

----------------------------------------
 COMMENTS
----------------------------------------
# This line is ignored     Script comment (not in output)
// Asm comment             Preserved in .pory output
@ Alt comment              Also preserved in .pory output

========================================
 OUTPUT STRUCTURE (scripts.pory)
========================================
  1. const declarations (from aliases)
  2. setup.pory contents
  3. legacy.pory contents (if exists)
  4. compiled .txt scripts (alphabetical)
  5. raw .pory files (alphabetical, excl. setup/legacy)

Sections are marked with:
  // # REGION: filename
  // # END REGION: filename

Duplicate text blocks across regions are deduplicated
automatically (setup.pory definitions take priority).

========================================
 MAP HEALTH
========================================
Six states shown by torch status:

  [     OK     ]   In sync -- workspace matches last write
  [   STALE    ]   Workspace edited since last sync
  [   DRIFT    ]   Game file edited outside TORCH
  [  ORPHAN    ]   No game folder found for this map
  [ MISSING WS ]   Enrolled but workspace folder missing
  [    NEW     ]   Enrolled but never synced

torch build auto-syncs all STALE maps before building.
torch sync (all) skips ORPHAN and MISSING WS maps.

========================================
 BUILD FEATURES
========================================
torch build does three things:

  1. Auto-sync -- syncs all stale enrolled maps first
  2. Pre-build safety checks:
     a. Sanitise empty script fields in map.json
     b. Regenerate missing .inc files
     c. Precompile all .pory files
  3. Build -- runs make with all CPU cores
  4. Error diagnosis -- pattern-matches errors, suggests fix

Recognised error patterns:
  - stddef.h missing        -> run fixdev
  - ROM region overflowed   -> use SCORCH to remove content
  - Missing map data file   -> check map folder
  - Poryscript .pory error  -> check script syntax
  - Undeclared constant     -> check header files
  - C syntax error          -> check source file

Verified snapshots:
  After every successful build, TORCH saves a verified
  snapshot of all enrolled map workspaces. Use
  torch restore (no map name) to roll back to the last
  known-good state.

  max_verified_snapshots setting controls retention
  (default: 3).

auto_build setting:
  true (default) -- safe operations auto-build without
  prompting. Destructive operations always prompt.

========================================
 SYNC SAFETY
========================================
MAP GUARD (automatic, every sync):
  - Fixes Porymap "id" -> "map_section" rename bug
  - Restores missing "name" fields on MAPSEC entries
  - Restores custom mapsec entries from backup
  - Safe on any project -- all fixes check file existence

WORKSPACE SNAPSHOTS (automatic, every sync):
  - Zips all .txt and .pory files before sync
  - Stored in backups/snapshots/ inside the map folder
  - Pruned to max_snapshots (default 10)
  - Pinned snapshots exempt from pruning

LABEL VALIDATION (automatic, every sync):
  - Checks all goto/call/gotoif targets exist
  - Checks trainerbattle text label references
  - Checks movement block references (do commands)
  - Reports undefined labels with source file + context

CONSTANT VALIDATION (automatic, every sync):
  - Checks FLAG_, VAR_, TRAINER_, SE_, MUS_, FANFARE_,
    SPECIES_, ITEM_ constants against game headers
  - Checks special function names against specials.inc
  - Warns on unrecognised constants before build

COLLISION DETECTION (automatic, every sync):
  - Errors if both Foo.txt and Foo.pory exist (ambiguous)

========================================
 COMPILE-TIME VALIDATION
========================================
The compiler validates these constant types against
your game's actual header files:

  FLAG_*       include/constants/flags.h
  VAR_*        include/constants/vars.h
  TRAINER_*    include/constants/trainers.h
  SE_*         include/constants/songs.h
  MUS_*        include/constants/songs.h
  FANFARE_*    include/constants/songs.h
  SPECIES_*    include/constants/species.h
  ITEM_*       include/constants/items.h
  Special      data/specials.inc

Unrecognised constants produce a warning, not a hard
error, so pass-through Poryscript still compiles.

========================================
 SCORCH
========================================
Vanilla content removal wizard. Removes stock Pokemon
Emerald content you don't need in your ROM hack.

Modes:
  torch scorch             Full-scan wizard (Singe mode)
  torch scorch <category>  Single category
  torch scorch report      Scan only (saves report file)
  torch scorch restore     Restore from SCORCH snapshot
  torch scorch phoenix     Full vanilla wipe
  torch scorch phoenix plan  Dry-run report

Eight categories:
  maps        Vanilla maps
  trainers    Vanilla trainers
  encounters  Wild encounter tables
  frontier    Battle Frontier data
  scripts     Shared vanilla scripts
  tilesets    Unused tilesets
  graphics    Graphics (scan only)
  music       Music (scan only)

Items are tagged SAFE, BLOCKED, or CAUTION based on
cross-reference analysis. SCORCH takes a full snapshot
before any removal for safe rollback.

========================================
 EXPANSION COMPATIBILITY
========================================
TORCH auto-detects your pokeemerald-expansion version
and gates features accordingly.

Supported: v1.6.0 through latest + vanilla pokeemerald.

Version-sensitive features:
  .party trainer format      v1.9.0+
  Multi battle types         v1.11.0+
  Time-of-day encounters     v1.12.0+
  Smol compression           v1.13.0+
  make release               v1.14.0+
  Learnset teaching type     v1.14.0+

If a feature isn't available in your version, TORCH
shows a clear message and falls back gracefully.

========================================
 GOTCHAS
========================================
  - Never use Unicode ellipsis -- use three ASCII dots (...)
  - Escape \n and \p as \\n and \\p inside Python strings
    (they're Poryscript text commands, not escape codes)
  - Trainer display names: max 7 characters in .h format;
    .party format supports longer names
  - Deleting a .txt script: also update/delete the NPC
    in Porymap / TORCH Studio
  - Legacy maps: check legacy.pory for existing mapscripts
    before adding to setup.pory (avoid duplicate labels)
  - walkto uses VAR_0x8004-0x8007 -- don't use these vars
    in the same script
  - camera reset uses VAR_0x8004/VAR_0x8005 as scratch
  - Camera commands cannot use '+' parallel syntax
  - walkto cannot use '+' parallel syntax
  - Pokemon actor faint/revive requires the `pokemon`
    directive, not `alias`

========================================
 SEE ALSO
========================================
  Full user guide:  docs/guide.md
  Emotes config:    config/emotes.conf
  Web GUI:          torch gui (http://localhost:8642)