{"id":13760707,"url":"https://github.com/huderlem/poryscript","last_synced_at":"2025-05-16T18:08:47.658Z","repository":{"id":36052396,"uuid":"204747562","full_name":"huderlem/poryscript","owner":"huderlem","description":"High-level scripting language for gen 3 pokemon decompilation projects","archived":false,"fork":false,"pushed_at":"2025-02-16T17:28:15.000Z","size":448,"stargazers_count":223,"open_issues_count":5,"forks_count":24,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-03T20:10:12.418Z","etag":null,"topics":["go","golang","pokemon","scripting","scripting-language"],"latest_commit_sha":null,"homepage":"https://www.huderlem.com/poryscript-playground/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/huderlem.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-27T16:46:20.000Z","updated_at":"2025-04-03T06:11:07.000Z","dependencies_parsed_at":"2023-11-10T19:29:59.469Z","dependency_job_id":"aeaa67fe-1a15-4aae-8664-29f97c3d8393","html_url":"https://github.com/huderlem/poryscript","commit_stats":{"total_commits":241,"total_committers":12,"mean_commits":"20.083333333333332","dds":"0.15767634854771784","last_synced_commit":"f8cedb5a370b826bc9bf61f5e052687bd8688c72"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huderlem%2Fporyscript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huderlem%2Fporyscript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huderlem%2Fporyscript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huderlem%2Fporyscript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/huderlem","download_url":"https://codeload.github.com/huderlem/poryscript/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248606861,"owners_count":21132428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","pokemon","scripting","scripting-language"],"created_at":"2024-08-03T13:01:18.093Z","updated_at":"2025-05-16T18:08:47.650Z","avatar_url":"https://github.com/huderlem.png","language":"Go","readme":"# Poryscript\n\n[![Actions Status](https://github.com/huderlem/poryscript/workflows/Go/badge.svg)](https://github.com/huderlem/poryscript/actions) [![codecov](https://codecov.io/gh/huderlem/poryscript/branch/master/graph/badge.svg)](https://codecov.io/gh/huderlem/poryscript)\n\n\nUse the online [Poryscript Playground](http://www.huderlem.com/poryscript-playground/) to test it out, and install the [VS Code Poryscript extension](https://marketplace.visualstudio.com/items?itemName=karathan.poryscript) to make writing scripts even easier!\n\nPoryscript is a higher-level scripting language that compiles into the scripting language used in [pokeemerald](https://github.com/pret/pokeemerald), [pokefirered](https://github.com/pret/pokefirered), and [pokeruby](https://github.com/pret/pokeruby). It makes scripting faster and easier. Some advantages of using Poryscript are:\n1. Branching control flow with `if`, `elif`, `else`, `while`, `do...while`, and `switch` statements.\n2. Inline text\n3. Auto-formatting text to fit within the in-game text box\n4. Better map script organization\n\nView the [Changelog](https://github.com/huderlem/poryscript/blob/master/CHANGELOG.md) to see what's new, and download the latest version from the [Releases](https://github.com/huderlem/poryscript/releases).\n\n**Table of Contents**\n- [Usage](#usage)\n  * [Basic Installation](#basic-installation)\n  * [Install as a Git Submodule](#install-as-a-git-submodule)\n  * [Convert Existing Scripts](#convert-existing-scripts)\n  * [Using Poryscript in Your Favorite IDE or Text Editor](#extensions)\n- [Poryscript Syntax (How to Write Scripts)](#poryscript-syntax-how-to-write-scripts)\n  * [`script` Statement](#script-statement)\n    + [Boolean Expressions](#boolean-expressions)\n    + [`while` and `do...while` Loops](#while-and-dowhile-loops)\n    + [Conditional Operators](#conditional-operators)\n    + [Regular Commands](#regular-commands)\n    + [Early-Exiting a Script](#early-exiting-a-script)\n    + [`switch` Statement](#switch-statement)\n    + [Labels](#labels)\n  * [`text` Statement](#text-statement)\n    + [Automatic Text Formatting](#automatic-text-formatting)\n    + [Custom Text Encoding](#custom-text-encoding)\n  * [`movement` Statement](#movement-statement)\n  * [`mart` Statement](#mart-statement)\n  * [`mapscripts` Statement](#mapscripts-statement)\n  * [`raw` Statement](#raw-statement)\n  * [Comments](#comments)\n  * [Constants](#constants)\n  * [Scope Modifiers](#scope-modifiers)\n  * [AutoVar Commands](#autovar-commands)\n  * [Compile-Time Switches](#compile-time-switches)\n  * [Optimization](#optimization)\n  * [Line Markers](#line-markers)\n- [Local Development](#local-development)\n  * [Building from Source](#building-from-source)\n  * [Running the tests](#running-the-tests)\n- [Versioning](#versioning)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n\n# Usage\nPoryscript is a command-line program.  It reads an input script and outputs the resulting compiled bytecode script. You can either feed it the input script from a file or from `stdin`.  Similarly, Poryscript can output a file or to `stdout`.\n\n```\n\u003e ./poryscript -h\nUsage of poryscript:\n  -cc string\n        command config JSON file (default \"command_config.json\")\n  -f string\n        set default font id (leave empty to use default defined in font config file)\n  -fc string\n        font config JSON file (default \"font_config.json\")\n  -h    show poryscript help information\n  -i string\n        input poryscript file (leave empty to read from standard input)\n  -l int\n        set default line length in pixels for formatted text (uses font config file for default)\n  -lm\n        include line markers in output (enables more helpful error messages when compiling the ROM). (To disable, use '-lm=false') (default true)\n  -o string\n        output script file (leave empty to write to standard output)\n  -optimize\n        optimize compiled script size (To disable, use '-optimize=false') (default true)\n  -s value\n        set a compile-time switch. Multiple -s options can be set. Example: -s VERSION=RUBY -s LANGUAGE=GERMAN\n  -v    show version of poryscript\n```\n\nConvert a `.pory` script to a compiled `.inc` script, which can be directly included in a decompilation project:\n```\n./poryscript -i data/scripts/myscript.pory -o data/scripts/myscript.inc\n```\n\n## Basic Installation\nTo automatically convert your Poryscript scripts when compiling a decomp project, perform these two steps:\n1. Create a new `tools/poryscript/` directory, and add the `poryscript` command-line executable tool to it. Also copy `command_config.json` and `font_config.json` to the same location.\n```\n# For example, on Windows, place the files here.\npokeemerald/tools/poryscript/poryscript.exe\npokeemerald/tools/poryscript/command_config.json\npokeemerald/tools/poryscript/font_config.json\n```\nIt's also a good idea to add the poryscript binary to your `.gitignore` before your next commit. The config files _should_ be tracked by Git--therefore, don't add them to the `.gitignore`.\n\n2. Update the Makefile with these changes (Note, don't add the `+` symbol at the start of the lines. That's just to show the line is being added.):\n```diff\nFIX       := $(TOOLS_DIR)/gbafix/gbafix$(EXE)\nMAPJSON   := $(TOOLS_DIR)/mapjson/mapjson$(EXE)\nJSONPROC  := $(TOOLS_DIR)/jsonproc/jsonproc$(EXE)\n+ SCRIPT    := $(TOOLS_DIR)/poryscript/poryscript$(EXE)\n```\n```diff\ninclude audio_rules.mk\n\n+AUTO_GEN_TARGETS += $(patsubst %.pory,%.inc,$(shell find data/ -type f -name '*.pory'))\n\ngenerated: $(AUTO_GEN_TARGETS)\n```\n```diff\n%.s: ;\n%.png: ;\n%.pal: ;\n%.aif: ;\n+ %.pory: ;\n```\n```diff\n%.rl:     %      ; $(GFX) $\u003c $@\n+ data/%.inc: data/%.pory; $(SCRIPT) -i $\u003c -o $@ -fc tools/poryscript/font_config.json -cc tools/poryscript/command_config.json\n```\n\n## Install as a Git Submodule\nUsers may wish to install Poryscript as a dependency of their project if they work with other collaborators and require all contributors to use the same version. To accomplish this, we can integrate the tool as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). This has an additional benefit of automatically rebuilding Poryscript from source when bumping to a new version.\n\n1. Initialize the Git submodule. If you use a fork of Poryscript to implement custom features, replace the `https://github.com/huderlem/poryscript` URL with the appropriate URL for your fork.\n\n```bash\ncd path/to/your/pokeemerald\ngit submodule add https://github.com/huderlem/poryscript tools/poryscript\n```\n\n2. Pin your submodule to the latest release (or to your desired target version, if they differ).\n\n```bash\ncd tools/poryscript\ngit checkout 3.5.2\ncd -\ngit add tools/poryscript\n```\n\n3. Make the following changes to `make_tools.mk`:\n\n```diff\n- TOOL_NAMES := aif2pcm bin2c gbafix gbagfx jsonproc mapjson mid2agb preproc ramscrgen rsfont scaninc\n+ TOOL_NAMES := aif2pcm bin2c gbafix gbagfx jsonproc mapjson mid2agb preproc ramscrgen rsfont scaninc poryscript\n```\n\n4. Make the changes to `Makefile` as described above in [Basic Installation](#basic-installation).\n\n5. Commit your changes and push to the remote.\n\nThis installation method necessitates some changes in your project's workflow. When cloning your project to a fresh local copy, you should specify the `--recursive` option, which will ensure that Poryscript is checked out alongside your repository:\n\n```bash\ngit clone --recursive https://github.com/YOUR_USERNAME/pokeemerald.git\n```\n\nAfter receiving the updates to integrate the submodule, existing local copies of the repository must do the following:\n\n```bash\ngit submodule update --init\n```\n\nFinally, if/when new changes are pushed to Poryscript that you wish to receive, update the submodule like you would any other Git repository:\n\n```bash\ncd tools/poryscript\ngit fetch\ngit checkout REF # REF can be a version tag, a branch, or a commit hash\ncd -\ngit add tools/poryscript\ngit commit\ngit push\n```\n\n## Convert Existing Scripts\nIf you're working on a large project, you may want to convert all of the existing `scripts.inc` files to their `scripts.pory` equivalents. Since there are a large number of script files in the Gen 3 projects, you can save yourself a lot of time by following these instructions. **Again, this is completely optional, and you would only want to perform this bulk conversion if you're emabarking on large project where it would be useful to have all the existing scripts setup as Poryscript files.**\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick Here to View Instructions\u003c/summary\u003e\n\n  Convert all of your projects old map `scripts.inc` files into new `scripts.pory` files while maintaining the old scripts:\n\n  1. Create a file in your `pokeemerald/` directory named `convert_inc.sh` with the following content:\n     ```\n     #!/bin/bash\n\n     for directory in data/maps/* ; do\n     \tpory_exists=$(find $directory -name $\"scripts.pory\" | wc -l)\n     \tif [[ $pory_exists -eq 0 ]]; \n     \tthen\n     \t\tinc_exists=$(find $directory -name $\"scripts.inc\" | wc -l)\n     \t\tif [[ $inc_exists -ne 0 ]]; \n     \t\tthen\n     \t\t\techo \"Converting: $directory/scripts.inc\"\n     \t\t\ttouch \"$directory/scripts.pory\"\n     \t\t\techo 'raw `' \u003e\u003e \"$directory/scripts.pory\"\n     \t\t\tcat \"$directory/scripts.inc\" \u003e\u003e \"$directory/scripts.pory\"\n     \t\t\techo '`' \u003e\u003e \"$directory/scripts.pory\"\n     \t\tfi\n     \tfi \t\n     done\n     ```\n  \n  2. Run `chmod 777 convert_inc.sh` to ensure the script executable. \n\n  Finally you can execute it in your `pokeemerald/` directory by running `./convert_inc.sh` or `bash convert_inc.sh` in the console. This script will iterate through all your `data/map/` directories and convert the `scripts.inc` files into `scripts.pory` files by adding a `raw` tag around the old scripts. `convert_inc.sh` will skip over any directories that already have `scripts.pory` files in them, so that it will not overwrite any maps that you have already switched over to Poryscript.\n\u003c/details\u003e\n\n## Using Poryscript in Your Favorite IDE or Text Editor \u003ca id='extensions'\u003e\u003c/a\u003e\n\nFor VS Code, you can install the [Poryscript extension](https://marketplace.visualstudio.com/items?itemName=karathan.poryscript), which provides quality-of-life improvements such as autocomplete, syntax highlighting, and error diagnostics.\n\nFor other editors with [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) support (e.g. emacs, neovim, lapce, zed, helix, etc.), some Poryscript bindings are supported here: https://github.com/Elsie19/treesitter-poryscript\n\n# Poryscript Syntax (How to Write Scripts)\n\nA single `.pory` file is composed of many top-level statements. The valid top-level statements are `script`, `text`, `movement`, `mart`, `mapscripts`, and `raw`.\n```\nmapscripts MyMap_MapScripts {\n    ...\n}\n\nscript MyScript {\n    ...\n}\n\ntext MyText {\n    \"Hi, I'm some text.\\n\"\n    \"I'm global and can be accessed in C code.\"\n}\n\nmovement MyMovement {\n    walk_left\n    walk_right * 3\n}\n\nmart MyMart {\n    ITEM_POTION\n    ITEM_POKEBALL\n}\n\nraw `\nMyLocalText:\n    .string \"I'm directly included.$\"\n`\n```\n\n## `script` Statement\nThe `script` statement creates a global script containing script commands and control flow logic.  Here is an example:\n```\nscript MyScript {\n    # Show a different message, depending on the state of different flags.\n    lock\n    faceplayer\n    if (flag(FLAG_RECEIVED_TOP_PRIZE)) {\n        msgbox(\"You received the best prize!\")\n    } elif (flag(FLAG_RECEIVED_WORST_PRIZE)) {\n        msgbox(\"Ouch, you received the worst prize.\")\n    } else {\n        msgbox(\"Hmm, you didn't receive anything.\")\n    }\n    release\n    end\n}\n```\n\nAs you can see, using `if` statements greatly simplifies writing scripts because it does not require the author to manually define new sub-labels with `goto` statements everywhere.\n\n`if` statements can be nested inside each other, as you would expect.\n```\n    if (flag(FLAG_TEMP) == true) {\n        if (var(VAR_BADGES) \u003c 8) {\n            ...\n        } else {\n            ...\n        }\n    }\n```\n\nNote the special keyword `elif`.  This is just the way Poryscript specifies an \"else if\". Many `elif` statements can be chained together.\n\n### Boolean Expressions\nCompound boolean expressions are also supported. This means you can use the AND (`\u0026\u0026`) and OR (`||`) logical operators to combine expressions. For example:\n```\n    # Basic AND of two conditions.\n    if (!defeated(TRAINER_MISTY) \u0026\u0026 var(VAR_TIME) != DAY) {\n        msgbox(\"The Cerulean Gym's doors don't\\n\"\n               \"open until morning.\")\n    }\n    ...\n    # Group nested conditions together with another set of parentheses.\n    if (flag(FLAG_IS_CHAMPION) \u0026\u0026 !(flag(FLAG_SYS_TOWER_GOLD) || flag(FLAG_SYS_DOME_GOLD))) {\n        msgbox(\"You should try to beat the\\n\"\n               \"Battle Tower or Battle Dome!\")\n    }\n```\n\n### `while` and `do...while` Loops\n`while` statements are used to do loops.  They can be nested inside each or inside `if` statements, as one would expect.\n```\n    # Force player to answer \"Yes\" to NPC question.\n    msgbox(\"Do you agree to the quest?\", MSGBOX_YESNO)\n    while (var(VAR_RESULT) != 1) {\n        msgbox(\"...How about now?\", MSGBOX_YESNO)\n    }\n    setvar(VAR_QUEST_ACCEPTED, 1)\n```\n\nThe `while` statement can also be written as an infinite loop by omitting the boolean expression. This would be equivalent to `while(true)` in typical programming languages. (Of course, you'll want to `break` out of the infinite loop, or hard-stop the script.)\n```\n    while {\n        msgbox(\"Want to see this message again?\", MSGBOX_YESNO)\n        if (var(VAR_RESULT) != 1) {\n            break\n        }\n    }\n```\n\n`do...while` statements are very similar to `while` statements.  The only difference is that they always execute their body once before checking the condition.\n```\n    # Force player to answer \"Yes\" to NPC question.\n    do {\n        msgbox(\"Can you help me solve the puzzle?\", MSGBOX_YESNO)\n    } while (var(VAR_RESULT) == 0)\n```\n\n`break` can be used to break out of a loop, like many programming languages. Similary, `continue` returns to the start of the loop.\n\n### Conditional Operators\nThe condition operators have strict rules about what conditions they accept. The operand on the left side of the condition must be a `flag()`, `var()`, `defeated()`, or [AutoVar](#autovar-commands) check. They each have a different set of valid comparison operators, described below.\n\n| Type | Valid Operators |\n| ---- | --------------- |\n| `flag` | `==` |\n| `var` or [AutoVar](#autovar-commands) | `==`, `!=`, `\u003e`, `\u003e=`, `\u003c`, `\u003c=` |\n| `defeated` | `==` |\n\nAll operators support implicit truthiness, which means you don't have to specify any of the above operators in a condition. Below are some examples of equivalent conditions:\n```\n# Check if the flag is set.\nif (flag(FLAG_1))\nif (flag(FLAG_1) == true)\n\n# Check if the flag is cleared.\nif (!flag(FLAG_1))\nif (flag(FLAG_1) == false)\n\n# Check if the var is not equal to 0.\nif (var(VAR_1))\nif (var(VAR_1) != 0)\n\n#Check if the var is equal to 0.\nif (!var(VAR_1))\nif (var(VAR_1) == 0)\n\n# Check if the trainer has been defeated.\nif (defeated(TRAINER_GARY))\nif (defeated(TRAINER_GARY) == true)\n\n# Check if the trainer hasn't been defeated.\nif (!defeated(TRAINER_GARY))\nif (defeated(TRAINER_GARY) == false)\n```\n\nWhen not using implicit truthiness, like in the above examples, they each have different valid comparison values on the right-hand side of the condition.\n\n| Type | Valid Comparison Values |\n| ---- | --------------- |\n| `flag` | `TRUE`, `true`, `FALSE`, `false` |\n| `var` | any value (e.g. `5`, `VAR_TEMP_1`, `VAR_FOO + BASE_OFFSET`) |\n| `defeated` | `TRUE`, `true`, `FALSE`, `false` |\n\nOne quirk of the Gen 3 decomp scripting engine is that using the `compare` scripting command with a value in the range `0x4000 \u003c= x \u003c= 0x40FF` or `0x8000 \u003c= x \u003c= 0x8015` will result in comparing against a `var`, rather than the raw value. To force the comparison against a raw value, like `0x4000`, use the `value()` operator.  For example:\n\n```\nif (var(VAR_DAMAGE_DEALT) \u003e= value(0x4000))\n```\n\nThe resulting script use the `compare_var_to_value` command, rather than the usual `compare` command.\n\n### Regular Commands\nRegular non-branching commands that take arguments, such as `msgbox`, must wrap their arguments in parentheses. For example:\n```\n    lock\n    faceplayer\n    addvar(VAR_TALKED_COUNT, 1)\n    msgbox(\"Hello.\")\n    release\n    end\n```\n\n### Early-Exiting a Script\nUse `end` or `return` to early-exit out of a script.\n```\nscript MyScript {\n    if (flag(FLAG_WON) == true) {\n        end\n    }\n    ...\n}\n```\n\n### `switch` Statement\nA `switch` statement is an easy way to separate different logic for a set of concrete values. Poryscript `switch` statements behave similarly to other languages. However, the cases `break` implicitly. It is not possible to \"fall through\" to the next case by omitting a `break` at the end of a case, like in C. You *can* use `break` to break out of a case, though--it's just not required. Multiple cases can be designated by listing them immediately after another without a body. Finally, an optional `default` case will take over if none of the provided `case` values are met.  A `switch` statement's comparison value *must always be a `var()` operator*.  Of course, `switch` statements can appear anywhere in the script's logic, such as inside `while` loops, or even other `switch` statements.\n\n```\n    switch (var(VAR_NUM_THINGS)) {\n        case 0:\n            msgbox(\"You have 0 things.\")\n        case 1:\n        case 2:\n            msgbox(\"You have 1 or 2 things.\")\n        default:\n            msgbox(\"You have at least 3 things.\")\n    }\n```\n\n### Labels\nLabels can be defined inside a `script`, and they are very similar to C's `goto` labels. A label isn't usually desired or needed when writing Poryscript scripts, but it can be useful and in certain situations where you might want to jump to a common part of your script from several different places. To write a label, simply add a colon (`:`) after a name anywhere inside a `script`. Labels are rendered as regular assembly labels, and they can be marked as local or global. By default, labels have local scope, but they can be changed to global scope using the same syntax as other statements (e.g. `MyLabel(global):`).\n\nLabel Example:\n```\n// Note, this is a bad example of where a\n// label would be useful.\nscript MyScript {\n    lockall\n    if (flag(FLAG_TEST)) {\n        goto(MyScript_End)\n    } elif (flag(FLAG_OTHER_TEST)) {\n        addvar(VAR_SCORE, 1)\n        goto(MyScript_End)\n    }\n\nMyScript_End:\n    releaseall\n}\n```\n\n## `text` Statement\nUse `text` to include text that's intended to be shared between multiple scripts or in C code. The `text` statement is just a convenient way to write chunks of text, and it exports the text globally, so it is accessible in C code. Currently, there isn't much of a reason to use `text`, but it will be more useful in future updates of Poryscript.\n```\nscript MyScript {\n    msgbox(MyText)\n}\n\ntext MyText {\n    \"Hello, there.\\p\"\n    \"You can refer to me in scripts or C code.\"\n}\n```\nA small quality-of-life feature is that Poryscript automatically adds the `$` terminator character to text, so the user doesn't need to manually type it all the time.\n\n### Automatic Text Formatting\nText auto-formatting is also supported by Poryscript. The `format()` function can be wrapped around any text, either inline or `text`, and Poryscript will automatically fit the text to the size of the in-game text window by inserting automatic line breaks. A simple example:\n```\nmsgbox(format(\"Hello, this is some long text that I want Poryscript to automatically format for me.\"))\n```\nBecomes:\n```\n.string \"Hello, this is some long text that I\\n\"\n.string \"want Poryscript to automatically\\l\"\n.string \"format for me.$\"\n```\nLike other text, formatted text can span multiple lines if you use a new set of quotes for each line. You can also manually add your own line breaks (`\\p`, `\\n`, `\\l`), and it will still work as expected.\n```\ntext MyText {\n    format(\"Hello, are you the real-live legendary {PLAYER} that everyone talks about?\\p\"\n           \"Amazing!\\pSo glad to meet you!\")\n}\n```\nBecomes:\n```\n.string \"Hello, are you the real-live legendary\\n\"\n.string \"{PLAYER} that everyone talks about?\\p\"\n.string \"Amazing!\\p\"\n.string \"So glad to meet you!$\"\n```\n\nAdditionally, `format()` supports a special line break `\\N`, which will automatically insert the appropriate `\\n` or `\\l` line break. While this is an uncommon use case, it's useful in situations where a line break is desired for dramatic/stylistic purposes. In the following example, we want explicit line breaks for the `\"...\"` texts, but we don't know if the first one should use `\\n` or `\\l`. Using `\\N` makes it easy:\n```\ntext MyText {\n    format(\"You are my favorite trainer!\\N...\\N...\\N...\\NBut I'm better!\")\n}\n```\n\nThe font id can optionally be specified as the second parameter to `format()`.\n```\ntext MyText {\n    format(\"Hello, are you the real-live legendary {PLAYER} that everyone talks about?\\pAmazing!\\pSo glad to meet you!\", \"1_latin_rse\")\n}\n```\nBecomes:\n```\n.string \"Hello, are you the real-live legendary\\n\"\n.string \"{PLAYER} that everyone talks about?\\p\"\n.string \"Amazing!\\p\"\n.string \"So glad to meet you!$\"\n```\nThe font configuration JSON file informs Poryscript how many pixels wide each character in the message is, as well as setting a default maximum line length. Fonts have different character widths, and games have different text box sizes. For convenience, Poryscript comes with `font_config.json`, which contains the configuration for pokeemerald's `1_latin` font as `1_latin_rse`, as well as pokefirered's equivalent as `1_latin_frlg`. More fonts can be added to this file by simply creating anothing font id node under the `fonts` key in `font_config.json`.\n\n`cursorOverlapWidth` can be used to ensure there is always enough room for the cursor icon to be displayed in the text box. (This \"cursor icon\" is the small icon that's shown when the player needs to press A to advance the text box.)\n\n`numLines` is the number of lines displayed within a single message box. If editing text for a taller space, this can be adjusted in `font_config.json`.\n\nThe length of a line can optionally be specified as the third parameter to `format()` if a font id was specified as the second parameter.\n\n```\ntext MyText {\n    format(\"Hello, are you the real-live legendary {PLAYER} that everyone talks about?\\pAmazing!\\pSo glad to meet you!\", \"1_latin_rse\", 100)\n}\n```\nBecomes:\n```\n.string \"Hello, are you the\\n\"\n.string \"real-live\\l\"\n.string \"legendary\\l\"\n.string \"{PLAYER} that\\l\"\n.string \"everyone talks\\l\"\n.string \"about?\\p\"\n.string \"Amazing!\\p\"\n.string \"So glad to meet\\n\"\n.string \"you!$\"\n```\n\nFinally, `format()` takes the following optional named parameters, which override settings from the font config:\n- `fontId`\n- `maxLineLength`\n- `numLines`\n- `cursorOverlapWidth`\n```\ntext MyText {\n    format(\"This is an example of named parameters!\", numLines=3, maxLineLength=100)\n}\n```\n\n### Custom Text Encoding\nWhen Poryscript compiles text, the resulting text content is rendered using the `.string` assembler directive. The decomp projects' build process then processes those `.string` directives and substituted the string characters with the game-specific text representation. It can be useful to specify different types of strings, though. For example, implementing print-debugging commands might make use of ASCII text. Poryscript allows you to specify which assembler directive to use for text. Simply add the directive as a prefix to the string content like this:\n```\nascii\"My ASCII string.\"\ncustom\"My Custom string.\"\n\n// compiles to...\n.ascii \"My ASCII string.\\0\"\n.custom \"My Custom string.\"\n```\n\nNote that Poryscript will automatically add the `\\0` suffix character to ASCII strings. It will **not** add suffix to any other directives.\n\n## `movement` Statement\nUse `movement` statements to conveniently define movement data that is typically used with the `applymovement` command. `*` can be used as a shortcut to repeat a single command many times. Data defined with `movement` is created with local scope, not global.\n```\nscript MyScript {\n    lock\n    applymovement(2, MyMovement)\n    waitmovement(0)\n    release\n}\nmovement MyMovement {\n    walk_left\n    walk_up * 5\n    face_down\n}\n```\nBecomes:\n```\nMyScript::\n\tlock\n\tapplymovement 2, MyMovement\n\twaitmovement 0\n\trelease\n\treturn\n\nMyMovement:\n\twalk_left\n\twalk_up\n\twalk_up\n\twalk_up\n\twalk_up\n\twalk_up\n\tface_down\n\tstep_end\n```\n\nHowever, movement can also be *inlined* inside commands similar to text, using the `moves()` operator. This is often much more convenient, and it can help simplify your scripts. Anything that can be used in a `movement` statement can also be used inside `moves()`.\n\nLooking at the previous example, the movement can be inlined like this:\n```\nscript MyScript {\n    lock\n    applymovement(2, moves(\n        walk_left\n        walk_up * 5\n        face_down\n    ))\n    waitmovement(0)\n    release\n}\n```\nNote, whitespace doesn't matter. This can also be written all on a single line:\n```\napplymovement(2, moves(walk_left walk_up * 5 face_down))\n\n// You can even use commas to separate each movement command, since\n// that may be easier to read.\napplymovement(2, moves(walk_left, walk_up * 5, face_down))\n```\n\n## `mart` Statement\nUse `mart` statements to define a list of items for use with the `pokemart` command. Data defined with the `mart` statement is created with local scope by default. It is not neccesary to add `ITEM_NONE` to the end of the list, but if Poryscript encounters it, any items after it will be ignored.\n\n```\nscript ScriptWithPokemart {\n\tlock\n\tmessage(\"Welcome to my store.\")\n\twaitmessage\n\tpokemart(MyMartItems)\n\tmsgbox(\"Come again soon.\")\n\trelease\n}\n\nmart MyMartItems {\n\tITEM_LAVA_COOKIE\n\tITEM_MOOMOO_MILK\n\tITEM_RARE_CANDY\n\tITEM_LEMONADE\n\tITEM_BERRY_JUICE\n}\n```\n\nBecomes:\n```\nScriptWithPokemart::\n\tlock\n\tmessage ScriptWithPokemart_Text_0\n\twaitmessage\n\tpokemart MyMartItems\n\tmsgbox ScriptWithPokemart_Text_1\n\trelease\n\treturn\n\n\t.align 2\nMyMartItems:\n\t.2byte ITEM_LAVA_COOKIE\n\t.2byte ITEM_MOOMOO_MILK\n\t.2byte ITEM_RARE_CANDY\n\t.2byte ITEM_LEMONADE\n\t.2byte ITEM_BERRY_JUICE\n\t.2byte ITEM_NONE\n\nScriptWithPokemart_Text_0:\n\t.string \"Welcome to my store.$\"\n\nScriptWithPokemart_Text_1:\n\t.string \"Come again soon.$\"\n```\n\n## `mapscripts` Statement\nUse `mapscripts` to define a set of map script definitions. Scripts can be inlined for convenience, or a label to another script can simply be specified. Some map script types, like `MAP_SCRIPT_ON_FRAME_TABLE`, require a list of comparison variables and scripts to execute when the variable's value is equal to some value. In these cases, you use brackets `[]` to specify that list of scripts. Below is a full example showing map script definitions for a new map called `MyNewCity`:\n```\nmapscripts MyNewCity_MapScripts {\n    MAP_SCRIPT_ON_RESUME: MyNewCity_OnResume\n    MAP_SCRIPT_ON_TRANSITION {\n        random(2)\n        switch (var(VAR_RESULT)) {\n            case 0: setweather(WEATHER_ASH)\n            case 1: setweather(WEATHER_RAIN_HEAVY)\n        }\n    }\n    MAP_SCRIPT_ON_FRAME_TABLE [\n        VAR_TEMP_0, 0: MyNewCity_OnFrame_0\n        VAR_TEMP_0, 1 {\n            lock\n            msgbox(\"This script is inlined.\")\n            setvar(VAR_TEMP_0, 2)\n            release\n        }\n    ]\n}\n\nscript MyNewCity_OnResume {\n    ...\n}\n\nscript MyNewCity_OnFrame_0 {\n    ...\n}\n```\n\nFor maps with no map scripts, simply make an empty `mapscripts` statement:\n```\nmapscripts MyNewCity_MapScripts {}\n```\n\n## `raw` Statement\nUse `raw` to include raw bytecode script. Anything in a `raw` statement will be directly included into the compiled script. This is useful for defining custom data, or data types not supported in regular Poryscript.\n```\nraw `\nTestMap_MapScripts::\n\t.byte 0\n`\n\nscript MyScript {\n    lock\n    faceplayer\n    # Text can span multiple lines. Use a new set of quotes for each line.\n    msgbox(\"This is shorter text,\\n\"\n           \"but we can still put it\\l\"\n           \"on multiple lines.\")\n    applymovement(OBJ_EVENT_ID_PLAYER, MyScript_Movement)\n    waitmovement(0)\n    msgbox(MyScript_LongText)\n    release\n    end\n}\n\nraw `\nMyScript_Movement:\n    walk_left\n    walk_down\n    step_end\n\nMyScript_LongText:\n    .string \"Hi, there.\\p\"\n    .string \"This text is too long\\n\"\n    .string \"to inline above.\\p\"\n    .string \"We'll put it down here\\n\"\n    .string \"instead, so it's out of\\l\"\n    .string \"the way.$\"\n`\n```\n\n## Comments\nUse single-line comments with `#` or `//`. Everything after the `#` or `//` will be ignored. Comments cannot be placed in a `raw` statement. (Users who wish to run the C preprocessor on Poryscript files should use `//` comments to avoid conflict with C preprocessor directives that use the `#` character.)\n```\n# This script does some cool things.\nscript MyScript {\n    // This is also a valid comment.\n    ...\n}\n```\n\n## Constants\nUse `const` to define constants that can be used in the current script. This is especially useful for giving human-friendly names to event object ids, or temporary flags. Constants must be defined before they are used. Constants can also be composed of previously-defined constants.\n```\nconst PROF_BIRCH_ID = 3\nconst ASSISTANT_ID = PROF_BIRCH_ID + 1\nconst FLAG_GREETED_BIRCH = FLAG_TEMP_2\n\nscript ProfBirchScript {\n    applymovement(PROF_BIRCH_ID, moves(walk_left * 4, face_down))\n    showobject(ASSISTANT_ID)\n    setflag(FLAG_GREETED_BIRCH)\n}\n```\n\nNote that these constants are **not** a general macro system. They can only be used in certain places in Poryscript syntax. Below is an example of all possible places where constants can be substituted into the script:\n```\nconst CONSTANT = 1\n\nmapscripts MyMapScripts {\n    MAP_SCRIPT_ON_FRAME_TABLE [\n        // The operand and comparison values can both use constants in a\n        // table-based map script.\n        CONSTANT, CONSTANT: MyOnFrameScript_0\n    ]\n}\n\nscript MyScript {\n    // Any parameter of any command can use constants.\n    somecommand(CONSTANT)\n\n    // Any comparison operator can use constants, as well as their comparison values.\n    if (flag(CONSTANT)) {}\n    if (var(CONSTANT) == CONSTANT) {}\n    if (defeated(CONSTANT)) {}\n\n    // A switch var value can be a constant, as well as the individual cases.\n    switch (var(CONSTANT)) {\n        case CONSTANT: break\n    }\n}\n```\n\n## Scope Modifiers\nTo control whether a script should be global or local, a scope modifier can be specified. This is supported for `script`, `text`, `movement`, and `mapscripts`. In this context, \"global\" means that the label will be defined with two colons `::`.  Local scopes means one colon `:`.\n```\nscript(global) MyGlobalScript {\n    ...\n}\nscript(local) MyLocalScript {\n    ...\n}\n```\nBecomes:\n```\nMyGlobalScript::\n    ...\n\nMyLocalScript:\n    ...\n```\n\nThe top-level statements have different default scopes. They are as follows:\n\n| Type | Default Scope |\n| ---- | --------------- |\n| `script` | Global |\n| `text` | Global |\n| `movement` | Local |\n| `mart` | Local |\n| `mapscripts` | Global |\n\n## AutoVar Commands\nSome scripting commands always store their result in the same variable. For example, `checkitem` always stores its result in `VAR_RESULT`. Poryscript can simplify working with these commands with a concept called \"AutoVar\" commands.\n\n*Without* using an AutoVar, a script would be written like this:\n```\ncheckitem(ITEM_ROOT_FOSSIL)\nif (var(VAR_RESULT) == TRUE) {\n    // player has the Root Fossil\n}\n```\n\nHowever, AutoVars can be used *inside* the condition, which helps streamline the script:\n```\nif (checkitem(ITEM_ROOT_FOSSIL) == TRUE) {\n    // player has the Root Fossil\n}\n```\n\nAutoVars can be used ***anywhere*** a `var()` operator can be used.  e.g. `if` conditions, `switch` statements--any boolean expression!\n\n### Defining AutoVar Commands\nAutoVar commands are fully configurable with the `command_config.json` file.  Use the `-cc` command line parameter to specifying the location of that config.\n\nThere are two types of AutoVar commands:\n1. Implicit\n    - The stored var is defined in the config file, and is not present in the authored script.\n    - Examples: `checkitem`, `getpartysize`, `random`\n2. Explicit\n    - The stored var is provided as part of the command, and the config file stores the 0-based index of the command that specifies the stored var.\n    - Examples: `specialvar`, `checkcoins`\n\nLet's take a look at the example config file:\n```json\n// command_config.json\n{\n    \"autovar_commands\": {\n        \"specialvar\": {\n            \"var_name_arg_position\": 0\n        },\n        \"checkitem\": {\n            \"var_name\": \"VAR_RESULT\"\n        },\n    ...\n}\n```\n\nWith the above config, a script could be written like so:\n```\nif (checkitem(ITEM_POKEBLOCK_CASE)) {\n    if (specialvar(VAR_RESULT, GetFirstFreePokeblockSlot) != -1 \u0026\u0026 \n        specialvar(VAR_RESULT, PlayerHasBerries)\n    ) {\n        msgbox(\"Great! You can use the Berry Blender!)\n    }\n} else {\n    msgbox(\"You don't have a Pokeblock case!\")\n}\n```\n\n## Compile-Time Switches\nUse the `poryswitch` statement to change compiler behavior depending on custom switches. This makes it easy to make scripts behave different depending on, say, the `GAME_VERSION` or `LANGUAGE`. Any content that does not match the compile-time switch will not be included in the final output. To define custom switches, use the `-s` option when running `poryscript`.  You can specify multiple switches, and each key/value pair must be separated by an equals sign. For example:\n\n```\n./poryscript -i script.pory -o script.inc -s GAME_VERSION=RUBY -s LANGUAGE=GERMAN\n```\n\nThe `poryswitch` statement can be embedded into any script section, including `text`, `movement`, and `mart` statements. The underscore `_` case is used as the fallback, if none of the other cases match. Cases that only contain a single statement or command can be started with a colon `:`.  Otherwise, use curly braces to define the case's block.\n\nHere are some examples of compile-time switches. This assumes that two compile-time switches are defined, `GAME_VERSION` and `LANGUAGE`.\n\n```\nscript MyScript {\n    lock\n    faceplayer\n    poryswitch(GAME_VERSION) {\n        RUBY {\n            msgbox(\"Here, take this Ruby Orb.\")\n            giveitem(ITEM_RUBY_ORB)\n        }\n        SAPPHIRE {\n            msgbox(\"Here, take this Sapphire Orb.\")\n            giveitem(ITEM_SAPPHIRE_ORB)\n        }\n        _: msgbox(format(\"This case is used when GAME_VERSION doesn't match either of the above.\"))\n    }\n    release\n}\n\ntext MyText {\n    poryswitch(LANGUAGE) {\n        GERMAN:  \"Hallo. Ich spreche Deutsch.\"\n        ENGLISH: \"Hello. I speak English.\"\n    }\n}\n\nmovement MyMovement {\n    face_player\n    walk_down\n    poryswitch(GAME_VERSION) {\n        RUBY: walk_left * 2\n        SAPPHIRE {\n            walk_right * 2\n            walk_left * 4\n        }\n    }\n}\n\nmart MyMart {\n    ITEM_POTION\n    ITEM_POKEBALL\n    poryswitch(GAME_VERSION) {\n        RUBY {\n            ITEM_LAVA_COOKIE\n            ITEM_RED_SCARF\n        }\n        SAPPHIRE {\n            ITEM_FRESH_WATER\n            ITEM_BLUE_SCARF\n        }\n    }\n}\n```\n\nNote, `poryswitch` can also be embedded inside inlined `mapscripts` scripts.\n\n## Optimization\nBy default, Poryscript produces optimized output. It attempts to minimize the number of `goto` commands and unnecessary script labels. To disable optimizations, pass the `-optimize=false` option to `poryscript`.\n\n## Line Markers\nBy default, Poryscript includes [C Preprocessor line markers](https://gcc.gnu.org/onlinedocs/gcc-3.0.2/cpp_9.html) in the compiled output.  This improves error messages.  To disable line markers, specify `-lm=false` when invoking Poryscript.\n\n# Local Development\n\nThese instructions will get you setup and working with Poryscript's code. You can either build the Poryscript tool from source, or simply download the latest release from the Releases tab on GitHub.\n\n## Building from Source\n\nFirst, install [Go](http://golang.org).  Poryscript has no additional dependencies.  It uses Go modules, so you shouldn't need to be located in a Go workspace.\n\nNavigate to the Poryscript working directory, and build it:\n```\ncd your/path/to/poryscript\ngo build\n```\n\nThis will create a `poryscript` executable binary in the same directory. Then you can simply install it into your project by running `./install.sh ../yourprojectname` instead of manually copying the files over, similarly to how agbcc is installed into projects.\n\n## Running the tests\n\nPoryscript has automated tests for its `emitter`, `parser`, and `lexer` packages. To run all of the tests from the base directory:\n```\n\u003e go test ./...\n?       github.com/huderlem/poryscript  [no test files]\n?       github.com/huderlem/poryscript/ast      [no test files]\nok      github.com/huderlem/poryscript/emitter  0.523s\nok      github.com/huderlem/poryscript/lexer    0.273s\nok      github.com/huderlem/poryscript/parser   0.779s\n?       github.com/huderlem/poryscript/token    [no test files]\n```\n\n\n# Versioning\n\nPoryscript uses [Semantic Versioning](http://semver.org/). For the available versions, see the [tags on this repository](https://github.com/huderlem/poryscript/tags).\n\n# License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details\n\n# Acknowledgments\n\n* Thorsten Ball's *Writing An Interpreter In Go* helped bootstrap the lexer, AST, and parser for this project. A chunk of that code was derived and/or copied from that book, as I had never written something of this nature before.\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuderlem%2Fporyscript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuderlem%2Fporyscript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuderlem%2Fporyscript/lists"}