overpy 9.6.10 → 9.7.3

package/README.md

@@ -33,56 +33,7 @@ You first need to install the [pnpm package manager](https://pnpm.io/installatio
 - Build `out/overpy_standalone.js`: `pnpm run package`
 - Build and publish to prod: `pnpm run publish`
 
-# NPM usage
-
-![NPM Version](https://img.shields.io/npm/v/overpy) ![NPM Type Definitions](https://img.shields.io/npm/types/overpy)
-
-Install:
-
-- As a dependency: `pnpm i overpy`
-- Global CLI (optional): `pnpm i -g overpy`
-- One-off CLI without install: `npx overpy --help`
-
-JS/TS API usage:
-
-```js
-// JavaScript (CommonJS)
-const overpy = require("overpy");
-
-async function main() {
-    await overpy.readyPromise;
-    const compileResult = await overpy.compile(
-        'rule "hello":\n    @Event global\n    wait(1)\n',
-        "en-US",
-        process.cwd(),
-        "inline.opy"
-    );
-    console.log(compileResult.result);
-}
-
-main().catch(console.error);
-```
-
-```ts
-// TypeScript
-import * as overpy from "overpy";
-
-async function main() {
-    await overpy.readyPromise;
-    const workshopText = "rule(\"hello\") { event { Ongoing - Global; } actions { Wait(1, Ignore Condition); } }";
-    const decompiled = overpy.decompileAllRules(workshopText, "en-US");
-    console.log(decompiled);
-}
-```
-
-CLI usage:
-
-- Compile a file: `overpy compile -i script.opy -o script.txt`
-- Compile from stdin to stdout: `cat script.opy | overpy compile > script.txt`
-- Decompile a file: `overpy decompile -i workshop.txt -o script.opy`
-- Decompile from stdin to stdout: `cat workshop.txt | overpy decompile --ignore-variable-index > script.opy`
-
-Run `overpy --help` to see all options (`-l/--language`, `--root`, `--main-file`, `--ignore-variable-index`, `--ignore-subroutine-index`).
+See at the bottom for NPM usage and LSP building.
 
 # Installation
 
@@ -132,7 +83,7 @@ You may get warnings when compiling; do not ignore them, as they can lead to bug
 
 It is recommended to also decompile one of your existing gamemodes to get a better feel of the OverPy syntax.
 
-```py
+```opy
 
 # Line comments are made with "#".
 # Multiline comments are made with /* */.
@@ -296,7 +247,6 @@ If a function is not in that list, then the name is the English name in camelCas
 <code>Loop If(A == 2)</code>                                     | <code>if A == 2:</code><br><code>&nbsp;&nbsp;&nbsp;&nbsp;loop()</code>
 <code>Loop If Condition Is False</code>                  | <code>if not ruleCondition:</code><br><code>&nbsp;&nbsp;&nbsp;&nbsp;loop()</code>
 <code>Loop If Condition Is True</code>                   | <code>if ruleCondition:</code><br><code>&nbsp;&nbsp;&nbsp;&nbsp;loop()</code>
-<code>Magnitude Of</code>                                | <code>magnitude()</code>
 <code>Map(Workshop Island)</code>                                         | <code>Map.WORKSHOP_ISLAND</code>
 <code>Mapped Array(<i>array</i>, Current Array Element + 2)</code><br><code>Mapped Array(<i>array</i>, Current Array Element * Current Array Index)</code> | <code><i>array</i>.map(lambda <i>elem</i>: <i>elem</i>+2)</code><br><code><i>array</i>.map(lambda <i>elem</i>, <i>idx</i>: <i>elem</i> * <i>idx</i>)</code><br>Python-style comprehension syntax also works but is not recommended: <code>[<i>elem</i>+2 for <i>elem</i> in <i>array</i>]</code>
 <code>Modify Global Variable(A, Add, 2)</code>                      | <code>A += 2</code>
@@ -321,7 +271,6 @@ If a function is not in that list, then the name is the English name in camelCas
 <code>Not(<i>a</i>)</code>                                         | <code>not <i>a</i></code>
 <code>Number(1234)</code>                                      | <code>1234</code>
 <code>Objective Index</code>                             | <code>getCurrentObjective()</code>
-<code>Objective Position</code>                          | <code>getObjectivePosition()</code>
 <code>Opposite Team Of(Team Of(Event Player))</code>                            | <code>getOppositeTeam(eventPlayer.getTeam())</code><br>Or for a player: `eventPlayer.getOppositeTeam()`
 <code>Or(A == 2, B == 4)</code>                                          | <code>A == 2 or B == 4</code>
 <code>Player Carrying Flag</code>                        | <code>getFlagCarrier()</code>
@@ -332,9 +281,6 @@ If a function is not in that list, then the name is the English name in camelCas
 <code>Random Real</code>                                 | <code>random.uniform()</code>
 <code>Random Value In Array</code>                       | <code>random.choice()</code>
 <code>Randomized Array</code>                            | <code>random.shuffle()</code>
-<code>Raycast Hit Normal(<i>start</i>, <i>end</i>, <i>include</i>, <i>exclude</i>, <i>includePlayerObjects</i>)</code> | <code>raycast(<i>start</i>, <i>end</i>, <i>include</i>, <i>exclude</i>, <i>includePlayersObjects</i>).getNormal()</code>
-<code>Raycast Hit Player(<i>start</i>, <i>end</i>, <i>include</i>, <i>exclude</i>, <i>includePlayerObjects</i>)</code> | <code>raycast(<i>start</i>, <i>end</i>, <i>include</i>, <i>exclude</i>, <i>includePlayersObjects</i>).getPlayerHit()</code>
-<code>Raycast Hit Position(<i>start</i>, <i>end</i>, <i>include</i>, <i>exclude</i>, <i>includePlayerObjects</i>)</code> | <code>raycast(<i>start</i>, <i>end</i>, <i>include</i>, <i>exclude</i>, <i>includePlayersObjects</i>).getHitPosition()</code>
 <code>Remove From Array(<i>array</i>, 2)</code>                           | <code><i>array</i>.exclude(2)</code>
 <code>Remove Player</code>                               | <code><i>player</i>.removeFromGame()</code>
 <code>Right</code>                                       | <code>Vector.RIGHT</code>
@@ -358,7 +304,6 @@ If a function is not in that list, then the name is the English name in camelCas
 <code>Start Forcing Dummy Bot Name</code>                | <code><i>player</i>.startForcingName()</code>
 <code>Start Holding Button</code>                        | <code><i>player</i>.startForcingButton()</code>
 <code>Start Modifying Hero Voice Lines</code>            | <code><i>player</i>.startModifyingVoicelinePitch()</code>
-<code>Start Rule(<i>subroutine</i>, <i>behavior</i>)</code> | <code>async(<i>subroutine</i>, <i>behavior</i>)</code>
 <code>Start Scaling Player</code>                        | <code><i>player</i>.startScalingSize()</code>
 <code>Stop Holding Button</code>                         | <code><i>player</i>.stopForcingButton()</code>
 <code>Stop Modifying Hero Voice Lines</code>             | <code><i>player</i>.stopModifyingVoicelinePitch()</code>
@@ -388,7 +333,7 @@ If a function is not in that list, then the name is the English name in camelCas
 
 OverPy supports including custom game settings, using the `settings` keyword. The settings are parsed with OverPy's parser, meaning you can do things such as:
 
-```py
+```opy
 macro VERSION = "1.4.3"
 macro DEBUG = false
 macro CLIP_SIZE_MULTIPLIER = 2
@@ -419,7 +364,7 @@ settings {
 
 Note that every value has to eventually resolve to a dict/array/string/number/boolean through the optimizer (you can't do `200 * A` where `A` is a variable).
 
-There are quite a lot of changes regarding the syntax, and it is recommended that you edit settings within Overwatch, then use the decompile command to convert to OverPy.
+Because I made the unfortunate mistake of trying to rename pretty much all settings (and because Overwatch periodically renames a setting or two), unknown settings are accepted by the compiler, so you can just put what Overwatch accepts (but they won't be translated if you are compiling for another language).
 
 You can also put the settings in a .json file and then import it with `settings "gamesettings.opy.json"`. This has the advantage of adding autocompletion (if ending with .opy.json), although it will display syntax errors if it doesn't perfectly conform to the JSON syntax (trailing comma, comment, etc).
 
@@ -431,7 +376,7 @@ Extensions are activated using the `#!extensions` compiler directive.
 
 An if/elif/else statement is simply represented by the following structure:
 
-```python
+```opy
 if A == 1:
     B = 2
 elif A == 2:
@@ -446,7 +391,7 @@ else:
 
 A while loop is represented by the following structure:
 
-```python
+```opy
 while A == 1:
     B = 2
     wait()
@@ -457,7 +402,7 @@ It compiles to the workshop's `While` instruction.
 ## For loop
 
 A for loop is represented by the following structure:
-```python
+```opy
 globalvar i
 rule "for loop":
     for i in range(1, 5, 2):
@@ -467,7 +412,7 @@ rule "for loop":
 
 Note that the `range(start, stop, step)` function, that can only be used here, has other forms:
 
-```python
+```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)
 ```
@@ -480,7 +425,7 @@ Although not recommended to use, gotos can be used in conjunction with a label.
 
 For example:
 
-```python
+```opy
 if A == 4:
    goto lbl_0
 B = 5
@@ -493,7 +438,7 @@ Labels are declared on their own line, and must include a colon at the end (but
 Due to the limitations of the workshop, labels must be in the same rule as the `goto` instruction, and cannot be before it.
 
 Additionally, dynamic gotos can be specified using the special keyword `loc`:
-```python
+```opy
 goto loc+A
 ```
 
@@ -566,7 +511,7 @@ Compiler options begin with the `#!` operator, not indented.
 
 Inserts the text of the specified file. The file path can be relative; if so, it is relative to the file with the `#!include` directive. For example:
 
-```c
+```opy
 #!include "heroes/zenyatta.opy"
 
 /* includes a file in the parent directory (".." is the parent directory) */
@@ -580,7 +525,7 @@ Inserts the text of the specified file. The file path can be relative; if so, it
 
 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. For example:
 
-```hs
+```opy
 #!mainFile "../main.opy"
 ```
 
@@ -590,7 +535,7 @@ This is so that you can compile your gamemode from any file and OverPy knows the
 
 Suppresses the specified warnings globally across the program. Warnings must be separated by a space. Example:
 
-```hs
+```opy
 #!suppressWarnings w_type_check w_unsuitable_event
 ```
 
@@ -634,7 +579,7 @@ This directive is added by default upon decompilation. Only remove it if you are
 
 All 3 of these directives are only effective in the current block scope (indentation level) once they are declared, and can be cancelled by `#!enableOptimizations`, `#!disableOptimizeForSize` and `#!disableOptimizeStrict` respectively. For example:
 
-```py
+```opy
 rule "default: optimizations, no optimize for size, no optimize strict"
     A = B+0 #will be optimized
     if A:
@@ -654,7 +599,7 @@ rule "optimize strict, no optimize for size":
 
 Several compiler options are available to automatically replace some constants, in order to save elements:
 
-```hs
+```opy
 #!replaceTeam1ByControlScoringTeam
 #!replace0ByCapturePercentage
 #!replace0ByPayloadProgressPercentage
@@ -674,7 +619,7 @@ Preprocessing is an important part of OverPy and allows extending its power way
 
 Use the `macro` keyword to declare a macro, which is an inline function or constant. For example:
 
-```python
+```opy
 macro BOSS_HP = 1000 + getNumberOfPlayers() * 300
 
 macro add(a, b):
@@ -689,7 +634,7 @@ Note that the replacement is done in the AST, meaning the order of operations wi
 
 You can also declare member macros, where the member is referenced with `self`. For example:
 
-```python
+```opy
 macro Vector.sum = self.x + self.y
 
 macro Player.setPowerLevel(powerLevel):
@@ -709,7 +654,7 @@ rule "power level":
 
 Default parameters can also be specified, and just like normal functions, you can use keyword arguments:
 
-```python
+```opy
 macro Player.setPowerLevel(powerLevel=1, damageDealt=null):
     self.setMaxHealth(powerLevel*200)
     self.setDamageDealt(damageDealt or powerLevel*2)
@@ -724,7 +669,7 @@ The `#!define` directive declares a text-based macro, meaning the replacement is
 
 For example, given this function:
 
-```hs
+```opy
 #!define sum(a,b) a+b
 ```
 
@@ -738,7 +683,7 @@ This problem does not occur with `macro`, which is why you should always use the
 
 You can do script macros with `#!define` and the special `__script__` function. For example:
 
-```hs
+```opy
 #!define addFive(x) __script__("addfive.js")
 ```
 
@@ -755,7 +700,7 @@ For the technical details:
 
 Enums can be declared to avoid manually declaring several macros:
 
-```java
+```opy
 enum GameStatus:
     GAME_NOT_STARTED = 1
     GAME_IN_PROGRESS
@@ -780,7 +725,7 @@ Note that enum members are inlined, so if you use a value such as `getAllPlayers
 
 Runs a JavaScript post-processing script after OverPy finishes compilation. This can effectively resolve certain compilation errors caused by language translation.
 
-```hs
+```opy
 #!postCompileHook "hooks/postCompileHook.js"
 ```
 
@@ -793,7 +738,7 @@ Runs a JavaScript post-processing script after OverPy finishes compilation. This
 
 Example `hooks/postCompileHook.js`:
 
-```js
+```opy
 content = content.replace(/abc/g, "def");
 
 // If the last operation returns an interpreter object,
@@ -809,7 +754,7 @@ Sets a prefix for all subsequent rules. The prefix is applied to the rule name u
 
 If a `#!rulePrefix` directive is in an included file, it only takes effect for rules within that file (and its child includes, if they don't have their own `#!rulePrefix`), after the directive. When the included file ends, the prefix is restored to what it was before the include.
 
-```hs
+```opy
 #!rulePrefix "Effects"
 
 rule "Spawn particles":
@@ -846,7 +791,7 @@ The expression has to evaluate to a string without arguments.
 
 Switches are a good way to transform an if/elif/else chain into something more optimized:
 
-```python
+```opy
 switch A:
     case Hero.ANA:
         B = 2
@@ -859,7 +804,7 @@ switch A:
 ```
 
 This is equivalent to:
-```python
+```opy
 if A == Hero.ANA:
     B = 2
 elif A == Hero.ASHE:
@@ -876,7 +821,7 @@ Keep in mind that fallthrough is enabled, so if you don't have a `break` instruc
 
 In the above case, we always set the same variable. Therefore, a dictionary can be used:
 
-```python
+```opy
 B = {
     0: 4,
     Hero.ANA: 2,
@@ -887,7 +832,7 @@ B = {
 If the key is not found in the dictionary, `null` will be returned. However, you can specify a `default` key for a default value.
 
 This dictionary is internally converted to:
-```python
+```opy
 B = [4, 2, 3][[0, Hero.ANA, Hero.ASHE].index(A)]
 ```
 
@@ -913,7 +858,7 @@ The `spacesForLength` and `strVisualLength` macros can also be used. `spacesForS
 
 This is useful to do alignment tricks. For example, the following code displays a key:value attribute list:
 
-```py
+```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":
@@ -933,7 +878,7 @@ The `ruleCondition` value compiles to all the conditions of the rule, joined wit
 
 This is mostly useful in `waitUntil`, so you can do the following:
 
-```py
+```opy
 rule "":
     @Event eachPlayer
     @Condition ...
@@ -952,7 +897,7 @@ You can use the `compressed()` function to store a large array of numbers or vec
 
 For example:
 
-```py
+```opy
 mapData = compressed([vect(-65.048, -18.007, -80.036), vect(0.92, 12.58, -18.32), vect(194.041, 6.128, -74.097), ...])
 ```
 
@@ -966,7 +911,7 @@ You can also use the `#!useVariableForCompressionAlphabet` compiler option to us
 
 `splitDictArray` maps an array of dictionaries to variables. For example:
 
-```python
+```opy
 splitDictArray({
     hero: waveHeroes,
     length: waveLengths
@@ -979,14 +924,14 @@ splitDictArray({
 
 Will yield the following:
 
-```python
+```opy
 waveHeroes = [Hero.ANA, Hero.SOLDIER, Hero.HAMMOND]
 waveLengths = [3, 8, null]
 ```
 
 For a terser syntax, `tabular` can be used, where the second argument is a raw array (not an array of arrays!)
 
-```
+```opy
 tabular([waveHeroes, waveLengths], [
     Hero.ANA, 3,
     Hero.SOLDIER, 8,
@@ -1075,13 +1020,13 @@ The `___` function is the same as the `_` function, but will never resolve the t
 
 This is useful when several strings are used in a single display action. For example:
 
-```python
+```opy
 bigMessage(text=[t"Choice 1", t"Choice 2"][eventPlayer.choice])
 ```
 
 This will add the code to resolve the translation twice, but it can be optimized to:
 
-```python
+```opy
 bigMessage(text=_([___("Choice 1"), ___("Choice 2")][eventPlayer.choice]))
 ```
 
@@ -1095,7 +1040,7 @@ Wrapping a string with `___` has the same caveats as putting a translated string
 
 **Example**:
 
-```py
+```opy
 #!translations en fr zh
 
 rule "Player got kill":
@@ -1136,7 +1081,7 @@ The way translations work is by casting a value to string (usually `Color.WHITE`
 
 However, this cast to string **must** be done client-side. You cannot do the following:
 
-```py
+```opy
 # Will not work properly, do not use!
 eventPlayer.language = ["White", "Blanc"].index("{}".format(Color.WHITE))
 ```
@@ -1145,7 +1090,7 @@ This will appear to work, but this is evaluated server-side, and what it actuall
 
 When in a reevaluated HUD text, `t"Some string"` resolves to:
 
-```py
+```opy
 ["Some string", "Une chaîne"][["White", "Blanc"].index("{}".format(Color.WHITE))]
 ```
 
@@ -1167,7 +1112,7 @@ Note: I used arrays in the example. OverPy concatenates arrays to strings using
 
 This is a bug introduced in Overwatch 2 where a rule condition check does not properly trigger while a variable is chased. For example:
 
-```py
+```opy
 playervar chasebug = 0
 
 rule "debug":
@@ -1190,9 +1135,21 @@ You would expect "Test chase" to display after 1 second, but the variable goes w
 
 To solve this bug, refactor your code to stop chasing the variable when you need to check it in a rule condition. Eg here, we could put the stop at 1 instead of 10. Then put `@SuppressWarnings w_ow2_rule_condition_chase` on the rule with the rule condition you checked is working. (It is not recommended to disable it for the whole project.)
 
+## w_start_rule_crash
+
+Found by Psyrius:
+
+It seems like repeatedly calling a `Start Rule` with its option `If Already Executing` set to `Restart Rule` and the subroutine being called has a `Wait` action inside (doesn't matter if there is more code before or after the wait inside the subroutine), the server will eventually crash - even if the server load is low. It will crash more frequently if the rule is called more often. In this workshop code/video, the calling frequency goes from every 1 to every 0.1s
+
+Edit 1: Crashes at ~465 accumulated restarts, confirmed stack overflow behavior.
+Edit 2: ~465 = shared pool, not per subroutine.
+Edit 3: It only accumulates toward the crash if the restarted subroutine has any remaining wait duration inside of it (doesn't matter how much duration is remaining).
+
+See https://discord.com/channels/570672959799164958/1485108807855247540/1485108807855247540 for more info.
+
 ## w_wait_until
 
-```py
+```opy
 globalvar waitUntilBug = 0
 
 rule "debug":
@@ -1216,7 +1173,72 @@ Since non-zero numbers are truthy, you would expect both `print` statements to r
 
 You can safely ignore this warning if you are using a variable that can only be a boolean.
 
-----------------------
+# Language Server Protocol
 
+OverPy can be built as a standalone Language Server Protocol server for editors that support custom LSP commands.
+
+```sh
+pnpm install
+pnpm run compile-lsp
+node out/languageServer.js --stdio
+```
+
+Configure your editor to run `node /path/to/overpy/out/languageServer.js --stdio` for `.opy` files. The server currently provides compiler diagnostics, completions (including type-aware argument values), signature help, hover documentation, semantic tokens, parameter inlay hints, document symbols, folding ranges, workspace go to definition, references and rename for user symbols, and warning suppression code actions by reusing the OverPy compiler metadata. You can also document your own `globalvar`/`playervar`/`def`/`enum` declarations with comments and they show up in hover and completion popups.
+
+See [`docs/language-server.md`](docs/language-server.md) for the architecture, per-feature internals, and the comment-documentation conventions.
+
+# NPM usage
+
+![NPM Version](https://img.shields.io/npm/v/overpy) ![NPM Type Definitions](https://img.shields.io/npm/types/overpy)
+
+Install:
+
+- As a dependency: `pnpm i overpy`
+- Global CLI (optional): `pnpm i -g overpy`
+- One-off CLI without install: `npx overpy --help`
+
+JS/TS API usage:
+
+```js
+// JavaScript (CommonJS)
+const overpy = require("overpy");
+
+async function main() {
+    await overpy.readyPromise;
+    const compileResult = await overpy.compile(
+        'rule "hello":\n    @Event global\n    wait(1)\n',
+        "en-US",
+        process.cwd(),
+        "inline.opy"
+    );
+    console.log(compileResult.result);
+}
+
+main().catch(console.error);
+```
+
+```ts
+// TypeScript
+import * as overpy from "overpy";
+
+async function main() {
+    await overpy.readyPromise;
+    const workshopText = "rule(\"hello\") { event { Ongoing - Global; } actions { Wait(1, Ignore Condition); } }";
+    const decompiled = overpy.decompileAllRules(workshopText, "en-US");
+    console.log(decompiled);
+}
+```
+
+CLI usage:
+
+- Compile a file: `overpy compile -i script.opy -o script.txt`
+- Compile from stdin to stdout: `cat script.opy | overpy compile > script.txt`
+- Decompile a file: `overpy decompile -i workshop.txt -o script.opy`
+- Decompile from stdin to stdout: `cat workshop.txt | overpy decompile --ignore-variable-index > script.opy`
+
+Run `overpy --help` to see all options (`-l/--language`, `--root`, `--main-file`, `--ignore-variable-index`, `--ignore-subroutine-index`).
+
+
+----------------------
 
 If you are still confused about something, or want to discuss a feature, please [join the discord](https://workshop.codes/discord) #hll-scripting :)