Overpy

https://github.com/zezombye/overpy
Admin
High-level language for the Overwatch Workshop with support for compilation and decompilation.
Tokens:70,359
Snippets:605
Trust Score:7.3
License:GPL-3.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example of adding a new hero to customGameSettingsSchema

Source: https://github.com/zezombye/overpy/wiki/Add-support-for-a-new-hero

Shows how to add a new hero entry with an ability duration scalar and weapons enabled setting. The example includes placeholder comments and uses '__percent__' for percentage values.

```javascript
const customGameSettingsSchema = {
  // ...
  "heroes": {
    "values": {
      // ...
      "__eachHero__": { /* ... */ },
      // ...
      "otherHero": {
        "values": {
          // ...
        }
      },
      "newHero": {
        "values": {
          "ability1Duration%": {
            "values": "__percent__",
            "min": 10,
            "max": 500,
            "default": 100,
            "en-US": "(Name of Ability 1) Duration Scalar"
          },
          "weaponsEnabled": {
            "values": {
              "all": {
                "en-US": "All (or something like that)"
              },
              "weapon1": {
                "en-US": "Name of main weapon"
              },
              "weapon2": {
                "en-US": "Name of secondary weapon"
              }
            }
          }
        }
      }
    }
  }
}
```

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

### Comment-based documentation example

Source: https://github.com/zezombye/overpy/blob/master/src/languageServer/docs/language-server.md

Shows how to document declarations with comments. A trailing same-line comment wins, otherwise a contiguous comment block above is used. The example includes a globalvar, playervar, def, and enum with comments.

```overpy
globalvar score # The team's current score          ← trailing wins

# Charge toward the ultimate ability.
# Capped at 100.
playervar ultCharge                                  ← comment block above (joined)

def resetScore(): # Sets every team's score back to 0

enum GameStatus:
    # Waiting for players to join the lobby
    SETUP = 0
    PLAYING = 1 # The match is live
```

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

### #!mainFile directive example

Source: https://github.com/zezombye/overpy/wiki/Compiler-options

Specifies an .opy file as the main file (implying the current file is a module). This directive MUST be placed at the very beginning of the file.

```hs
#!mainFile "../main.opy"
```

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

### OverPy development commands: pnpm install, dev, package, publish

Source: https://github.com/zezombye/overpy/blob/master/README.md

Install dependencies with pnpm and run the available build and publish scripts. The build in dev is tested with the demo, while the package script creates out/overpy_standalone.js and publish builds and pushes to production.

```bash
pnpm install
```

```bash
pnpm run dev
```

```bash
pnpm run package
```

```bash
pnpm run publish
```

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

### Configure #!postCompileHook and its example hook script

Source: https://github.com/zezombye/overpy/blob/master/README.md

The first block shows the directive used in an OverPy source file. The second block is an example hook script referenced by the directive; it manipulates the compiled text through the `content` variable and returns the final output. The hook path is resolved from the compilation rootPath, and only one hook is allowed per compilation.

```opy
#!postCompileHook "hooks/postCompileHook.js"
```

```opy
content = content.replace(/abc/g, "def");

// If the last operation returns an interpreter object,
// force a plain string as final output.
content.toString();
```

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

### #!include directive example

Source: https://github.com/zezombye/overpy/wiki/Compiler-options

Inserts the text of the specified file. The file path can be relative; if so, it is relative to the main file.

```hs
#!include "heroes/zenyatta.opy"
#!include "../main.opy"
```

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

### Custom game settings with settings keyword

Source: https://github.com/zezombye/overpy/blob/master/README.md

Example of custom game settings in OverPy. Includes macros, an enum, and a settings block with directives. Values must resolve to dict/array/string/number/boolean; unknown settings are accepted but not translated for other languages.

```opy
macro VERSION = "1.4.3"
macro DEBUG = false
macro CLIP_SIZE_MULTIPLIER = 2
enum HeroUltModifiers:
    ASHE = 400

settings {
    /* comment */
    "main": {
        "modeName": w"Tower Meifense",
        "description": f"Tower Meifense by Zezombye v{VERSION}",
    },
    "gamemodes": {
        "general": {
            "respawnTime%": 50 if DEBUG else 100,
        }
    },
    "heroes": {
        "allTeams": {
            "ashe": {
                "ammoClipSize%": 100 * CLIP_SIZE_MULTIPLIER,
                "ultDuration%": HeroUltModifiers.ASHE
            },
        }
    }
}
```

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

### Architecture diagram: VS Code client and language server

Source: https://github.com/zezombye/overpy/blob/master/src/languageServer/docs/language-server.md

ASCII diagram showing the client-server architecture, with extension.ts starting the language server over stdio JSON-RPC, and server.ts registering capabilities and request handlers.

```text
VS Code (client)                         Language server (separate Node process)
─────────────────                        ───────────────────────────────────────
extension.ts                             server.ts          ← entry point, registers
  startLanguageServer()  ──stdio JSON-RPC──►  capabilities + request handlers
  LanguageClient                              │
                                              ├─ validation.ts → compiler/compiler.ts
                                              ├─ completionState.ts (shared symbol store)
                                              └─ per-feature modules (hover.ts, …)
```

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

### Debug Setup Rule: Spawn Dummy Bots and Disable Inspector

Source: https://github.com/zezombye/overpy/blob/master/src/tests/results/z_uno.txt

This rule runs on an ongoing global event. It checks if debug is disabled, disables inspector recording, and then spawns dummy bots with a 2-second wait between each until the debug bot count reaches zero.

```overpy
rule ("[Setup][Debug] init debug settings") {
    event {
        Ongoing - Global;
    }
    actions {
        "Check if debug is disabled"
        If(Not(Global.SETTING_DEBUG));
            "Disable the inspector"
            Disable Inspector Recording;
        End;
        "Loop until all debug bots have spawned"
        While(Global.SETTING_DEBUG_BOTS);
            "Wait between spawing multiple bots"
            Wait(2, Ignore Condition);
            "Spawn a dummy bot"
            Create Dummy Bot(Random Value In Array(All Heroes), All Teams, -1, Global.MapPosition, Up);
            Modify Global Variable(SETTING_DEBUG_BOTS, Subtract, 1);
        End;
    }
}
```

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

### Declare custom game settings with settings keyword

Source: https://github.com/zezombye/overpy/wiki/Custom-game-settings

Declares custom game settings inline using the `settings` keyword. The example configures the main description, gamemode settings (skirmish enabled maps, hero and role limits), and hero-specific settings for Junkrat (infinite ult and spawning with ult).

```js
settings {
    "main": {
        "description": "Zez's Awesome Gamemode | 31ZG4M"
    },
    "gamemodes": {
        "skirmish": {
            "enabledMaps": [
                "horizonLunarColony"
            ]
        },
        "general": {
            "heroLimit": "off",
            "roleLimit": "off"
        }
    },
    "heroes": {
        "allTeams": {
            "junkrat": {
                "enableInfiniteUlt": true,
                "enableSpawningWithUlt": true
            }
        }
    }
}
```

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

### OverPy General Syntax: Rules, Annotations, Variables, and Function Call Patterns

Source: https://github.com/zezombye/overpy/blob/master/README.md

The OverPy syntax guide presents a single commented code block that covers rules, annotations, subroutines, delimiters, variable declarations, and function-call conventions. It shows the recommended structure for a rule, including required indentation, and demonstrates concrete examples such as the @Event and @Condition annotations, the eventPlayer.teleport() and hudHeader() member functions, and the globalvar/playervar keywords with optional indices and initialization. The block also notes that default variable names (A-Z, AA-DX) do not need to be declared and that wait() defaults to wait(0.016, Wait.IGNORE_CONDITION).

```opy
rule "setup":
    disableInspector() #don't forget to add that to your gamemodes
```

```opy
rule "player has spawned":
    @Event eachPlayer
    @Condition eventPlayer.hasSpawned()
    @Condition eventPlayer.A == 1
    @Team 1
    @Hero widowmaker
    @Slot 11
    # You can suppress a warning within the rule with the @SuppressWarnings annotation,
    # followed by the warning names separated by spaces.
    @SuppressWarnings w_player_closest_to_reticle w_wait_9999 #don't do this, it's just for the example

    eventPlayer.B = eventPlayer.getPlayerClosestToReticle(Team.ALL)
    wait(9999)
```

```opy
def teleportPlayerToSpawn():
    @Name "Subroutine: Teleport the player to spawn"
    eventPlayer.teleport(vect(10, 0, 10))
```

```opy
rule "---------- Boss fight code ----------":
    @Delimiter
    @Disabled
    @NewPage #adds empty rules to put the rule at the top of a page
```

```opy
globalvar gameStatus 2
playervar score #index is automatically calculated
```

```opy
globalvar spawnLocation = vect(10, 0, 10)
```

```opy
rule "functions":
    @Event eachPlayer

    # The vast majority of functions follow these rules:

    # 1. The function name is camelCased.
    # Create Effect() -> createEffect().
    setMatchTime(3600)

    # 2. Function names taking a player, array or string as a first argument are "member functions".
    # Teleport(Event Player, Vector(10,0,10)) -> eventPlayer.teleport(vect(10,0,10))
    eventPlayer.cancelPrimaryAction()

    # 3. Functions to get constants such as Hero(), Map() or Gamemode() are replaced by enums.
    # Map(Hanamura) -> Map.HANAMURA.
    eventPlayer.startForcingHero(Hero.ANA)

    # 4. Operators and some functions have significant syntax changes.
    # You can expand the list below to see all such functions.

    # Some functions also have default values.
    wait() #Equivalent to wait(0.016, Wait.IGNORE_CONDITION)

    # You can also specify individual arguments using the name=value syntax.
    # hudHeader() is a macro for hudText() that only displays the header.
    hudHeader(getAllPlayers(), "Some text", sortOrder=5, color=Color.YELLOW)
    hudHeader(text="Some text")
```

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

### #!obfuscate with disabled methods

Source: https://github.com/zezombye/overpy/wiki/Compiler-options

Obfuscates the resulting code. Methods can be disabled by prefixing them with 'no'. This example disables rule filling and constant obfuscation, useful if the obfuscation adds too many elements.

```hs
#!obfuscate noRuleFilling noConstantObfuscation
```

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

### Element count example: rule with condition and action

Source: https://github.com/zezombye/overpy/wiki/Element-saving-techniques

Shows a rule with a condition and an action that takes up 4 elements. The rule costs 1, the condition costs 1 (top-level arguments reduce cost), and the action costs 2 (A is top-level, 0 is Number(0) costing 2-1).

```python
rule "Rule 1": #1 element
    @Condition isGameInProgress() == true #1 element
    A = 0 #2 elements
```

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

### #!rulePrefixTemplate examples

Source: https://github.com/zezombye/overpy/blob/master/README.md

Shows the two documented forms of the #!rulePrefixTemplate directive. The first is the default template that adds the prefix in square brackets before the rule name when both the prefix and rule name are non-empty and the rule is not a delimiter. The second, used when the directive is specified without an expression, replaces underscores with spaces in the titlecased file path prefix.

```overpy
#!rulePrefixTemplate f"[{$prefix}] {$rule}" if $prefix and $rule and not $isDelimiter else $rule
```

```overpy
#!rulePrefixTemplate f"[{$pathTitle.replace('_', ' ')}] {$rule}" if $rule and not $isDelimiter else $rule
```

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

### spacesForString alignment example for key:value list

Source: https://github.com/zezombye/overpy/blob/master/README.md

Use the spacesForString macro to align text in a progress bar world text, demonstrating a key:value attribute list. Requires the final string to use the Blizzard Global font and respect casing, and the provided string for spacesForString must be a literal string. The comment notes that without createCasedProgressBarIwt, the strings must be uppercase.

```opy
#We use strVisualLength("M")*20 to specify a string that is longer than the longest key/value.
#!define dictLine(key, value) "{}{}{}{}".format(spacesForLength(strVisualLength("M")*20 - strVisualLength(key)), (key), (value), spacesForLength(strVisualLength("M")*20 - strVisualLength(value)))
rule "iwt":
    createProgressBarInWorldText(text=b" \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n{}\n{}\n{}".format(
        #If not using createCasedProgressBarIwt then you have to put the strings in uppercase
        dictLine("ABILITY 1: ", "KILLAURA"),
        dictLine("ABILITY 2: ", "WALLHACK"),
        dictLine("ULTIMATE: ", "CRASH THE SERVER")
    ), position=vect(0,0,0), scale=2)
```

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

### Subroutine Functions

Source: https://github.com/zezombye/overpy/wiki/Functions

OverPy provides functions for calling subroutines and starting rules asynchronously, corresponding to the Workshop's Call Subroutine and Start Rule functions.

```APIDOC
## subroutine()

### Description
Calls a subroutine. Equivalent to the Workshop function `Call Subroutine(subroutine)`.

### Method
Function

### Endpoint
`subroutine()`

### Parameters
- **subroutine** (subroutine) - Required - The subroutine to call.

### Return Value
- **void** - No return value.

```

```APIDOC
## async(subroutine, behavior)

### Description
Starts a rule asynchronously. Equivalent to the Workshop function `Start Rule(subroutine, behavior)`.

### Method
Function

### Endpoint
`async(subroutine, behavior)`

### Parameters
- **subroutine** (subroutine) - Required - The subroutine to start.
- **behavior** (behavior) - Required - The behavior of the started rule.

### Return Value
- **void** - No return value.

```

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

### For Loop with range

Source: https://github.com/zezombye/overpy/wiki/Control-flow

A for loop using the range function. The range function can only be used here and has forms: range(start, stop, step), range(start, stop), and range(stop).

```python
for i in range(1, 5, 2):
    B.append(i)
#B = [1,3,5]
```

```python
for i in range(1,5) -> for i in range(1,5,1)
for i in range(5) -> for i in range(0,5,1)
```

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

### Compile and run OverPy language server (pnpm)

Source: https://github.com/zezombye/overpy/blob/master/README.md

Builds and runs the OverPy language server as a standalone LSP server. Configure your editor to launch `node /path/to/overpy/out/languageServer.js --stdio` for `.opy` files. The server provides compiler diagnostics, completions, signature help, hover documentation, semantic tokens, inlay hints, document symbols, folding ranges, workspace go-to-definition, references, rename, and warning-suppression code actions.

```sh
pnpm install
pnpm run compile-lsp
node out/languageServer.js --stdio
```

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

### Run LSP adapter tests

Source: https://github.com/zezombye/overpy/blob/master/src/languageServer/docs/language-server.md

Executes the standalone adapter test for the language server, which bundles and runs the test file. Also suggests running type checks and linting.

```bash
pnpm run test:lsp     # bundles + runs src/test/languageServer.test.ts
```

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

### OverPy for loop with range

Source: https://github.com/zezombye/overpy/blob/master/README.md

For loop using range(). The first block shows a full rule with a for loop that appends values. The second block shows equivalent range signatures: range(start, stop) defaults step to 1, and range(stop) defaults start to 0 and step to 1. The range function can only be used in for loops.

```opy
globalvar i
rule "for loop":
    for i in range(1, 5, 2):
        B.append(i)
    #B = [1,3,5]
```

```opy
for i in range(1,5) -> for i in range(1,5,1)
for i in range(5) -> for i in range(0,5,1)
```

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

### #!suppressWarnings directive example

Source: https://github.com/zezombye/overpy/wiki/Compiler-options

Suppresses the specified warnings globally across the program. Warnings must be separated by a space.

```hs
#!suppressWarnings w_type_check w_unsuitable_event
```

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

### Load settings from JSON file with settings keyword

Source: https://github.com/zezombye/overpy/wiki/Custom-game-settings

Loads custom game settings from an external JSON file. This enables autocompletion using the JSON schema.

```js
settings "settings.opy.json"
```

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

### Using #!translations and t-prefix for translated strings

Source: https://github.com/zezombye/overpy/blob/master/README.md

Shows how to use the #!translations directive in OverPy to enable translations, then demonstrates the proper usage of the t prefix and _() function with display actions and variables, along with code that will not work and the correct way to handle translated strings.

```opy
#!translations en fr zh

rule "Player got kill":
    @Event playerDied
    #here, the string can simply be prefixed with "t", as it is in a display action
    bigMessage(attacker, t"You killed {}!".format(victim))

rule "Set wave message":
    if wave == 1:
        waveMsg = t"First wave!"
    else:
        waveMsg = t"Wave {}".format(wave)
        waveMsg = _("Wave {}").format(wave) #equivalent to the above

    #waveMsg is now a translated string.
    #You CANNOT do any further operations on it until displaying it!
    waveMsg = waveMsg.replace("Wave", "wave") #This won't work!
    someMsg = "You are at {}".format(waveMsg) #This won't work either
    waveMsg = _(waveMsg).replace("Wave", "wave") #This won't work either

    #We have to wrap waveMsg with the _() function when displaying it, as it is a translated string
    bigMessage(getAllPlayers(), _(waveMsg))

    #This will work, as the _() function converts the translated string back to
    #a normal string when used in a display action
    bigMessage(getAllPlayers(), _(waveMsg).replace("Wave, wave"))

    #If two arguments are supplied to the _() function, the first argument is used as a context string
    #for translators. Note that the .format() function must be used outside of the _() function.
    bigMessage(getAllPlayers(), _("not the ocean kind", "Wave {}").format(wave))
```

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

### Optimization directives scope example

Source: https://github.com/zezombye/overpy/blob/master/README.md

Shows the scoped effect of optimization directives. The first block shows #!disableOptimizations and #!optimizeForSize affecting only the current scope. The second shows #!optimizeStrict applying to all subsequent rules.

```opy
rule "default: optimizations, no optimize for size, no optimize strict"
    A = B+0 #will be optimized
    if A:
        #!disableOptimizations
        B = B+0 #will not be optimized
    C = B+0 #will be optimized
    #!optimizeForSize
    D = B+1 #B + true
```

```opy
#!optimizeStrict
#All subsequent rules will have strict optimization enabled
rule "optimize strict, no optimize for size":
    E = B*1 #will not be optimized
```

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

### Command to regenerate strings file

Source: https://github.com/zezombye/overpy/wiki/Add-support-for-a-new-hero

Run this command to regenerate the strings/strings.json file with new translations. Replace DATATOOL_PATH and OVERWATCH_PATH with actual paths. For WSL, use Linux-like path for DataTool and Windows-like path for Overwatch.

```bash
DATATOOL_PATH="/path/to/DataTool.exe" OVERWATCH_PATH="/path/to/Overwatch-install-folder" node generate-the-other-languages-doc.js --regenerateStringsFile
```

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

### Incorrect server-side language assignment

Source: https://github.com/zezombye/overpy/blob/master/README.md

Example of code that appears to set the player's language but is evaluated server-sideanding to the host's language, so it does not work for per-player translations. Marked as 'Will not work properly, do not use!'

```opy
# Will not work properly, do not use!
eventPlayer.language = ["White", "Blanc"].index("{}".format(Color.WHITE))
```

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

### OverPy goto with label and dynamic loc

Source: https://github.com/zezombye/overpy/blob/master/README.md

Goto statements with labels. The first block shows a static goto with a label, and the second shows a dynamic goto using the special keyword 'loc'. Labels must be in the same rule and cannot appear before the goto. Dynamic gotos are not recommended; use switches instead. These compile to 'Skip' or 'Skip If' instructions.

```opy
if A == 4:
   goto lbl_0
B = 5
lbl_0:
C = 6
```

```opy
goto loc+A
```

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

### Trigger w_chased_var_in_for example

Source: https://github.com/zezombye/overpy/blob/master/README.md

Shows the w_chased_var_in_for bug: a variable used in a chase action will prevent a for loop from running, even if the chase action is in a disabled rule. The for loop and print(B) will not execute, leaving B at 0.

```opy
rule "":
    @Disabled
    chaseAtRate(A, 9999, 1)

rule "":
    #Will not run
    for A in range(5):
        B++
    print(B) #0

```
Tokens:
Raw