@neocompose/cli 0.87.2 → 0.89.0

package/skills/neocompose-cli/references/neoscript.md

@@ -1,990 +0,0 @@
-# NeoScript
-
-Use this reference for inline code, snippets, nullability, control flow,
-runtime ownership, evaluation, and migrations.
-
-## Contents
-
-- Inline bodies and snippets
-- Nullability and ownership
-- Tuples and destructuring
-- References
-- Overloaded calls
-- Numeric builtins
-- Collection builtins
-- Conditional and logical operators
-- Loops and transfer
-- Switch
-- Try/catch
-- Debug output
-- Triggering dialogues
-- Evaluation and migrations
-
-## Inline bodies and snippets
-
-Keep computed getters, setters, functions, dialogue logic, group logic, and
-constructors inline in their owning `.neo` or `.neoflow` declaration. Do not
-create `Scripts/<Class>/<Member>.neo` sidecars.
-
-Explicit constructions such as `new MissingClass(5)` require a declared type,
-including inside stored object initializers, constructor arguments, and collections.
-The editor reports an unresolved class at its type name and refreshes the diagnostic
-when the declaration changes. Contextual `new(...)` still uses the expected type.
-
-If resolving a stored reference encounters an invalid initializer elsewhere,
-the diagnostic points to that initializer's authored file and position. Fix the
-reported initializer; a valid downstream `Reference(...)` is not the error site.
-
-Declare a setter's value type explicitly with the canonical form
-`set(int value) { ... }`. Project analysis, candidate materialization, and
-focused script commands all use the same accessor extraction. A property can have at most one getter and one setter. Concrete setters need a body (an empty body is a valid no-op); typed setters must use the property type and the parameter name `value`. Abstract and interface properties declare bodyless accessor contracts.
-
-A body whose whole point is one expression may be written as an expression
-body, `=> expr;`. It is pure sugar for the block form — same compiled
-instructions, same diagnostics, same stored source — and is available on
-getter-only properties, individual accessors, and functions:
-
-```neo
-public bool HasVisited => this.VisitCount > 0;
-
-public int Clamped {
-  get => Math.Clamp(this.Raw, 0, 10);
-  set(int value) { this.Raw = value; }
-}
-
-public bool Unlocked(int level) => this.Level >= level;
-```
-
-The `=>` is only an expression body where it directly follows the member name
-or the parameter list's `)`. An arrow after an `=` initializer is always a
-NeoFlow destination, so `override Trigger Trigger = new(...) => Welcome;`
-keeps its meaning.
-
-In a void context — a `void` function, a setter, or a void delegate — `=> expr`
-is an expression statement rather than a return, so the expression must do
-something: a call such as `void Ping() => this.OnUpdated();`, or an assignment
-such as `set(int value) => this.Raw = value;`. An expression whose value would
-simply be discarded is rejected with a diagnostic that names the block body as
-the fix.
-
-`neo pull` and canonical emission write a body as the shorthand when it is
-exactly one `return` statement that fits on one line, and anything else as a
-block. Setters are always blocks. `neo push` keeps the body form you authored,
-so choosing longhand for a one-line getter is stable.
-
-Properties require a getter implementation. A bodyless `{ get; }` contract
-requires `abstract` on the member, even inside an abstract class, for example
-`public abstract int Count { get; }`. For stored data, declare a field such as
-`public int Count = 0;`. VSCode and the CLI diagnose a missing getter body at
-the property name. Interface property contracts remain bodyless.
-
-Declare a bodyless NeoScript contract with `abstract`, for example
-`public abstract bool Equals(Item other);`. Reserve `native` for host-provided
-functions; concrete NeoScript overrides inherit the abstract signature.
-
-Inside an override body, use `base.Member(args)` or `base.Property` to invoke
-its nearest ancestor implementation. The ancestor receives the same `this`,
-so ordinary virtual calls inside that implementation still reach the most
-derived override. `base` outside an override or targeting an abstract member
-is a compile error. Base constructors and stored-field reads are not supported.
-
-Use the shared language service through focused commands:
-
-```sh
-neo script check --all
-neo script check --this Outpost --returns string 'return $"{this.Name}!";'
-neo script check --mode setter --member ComputedName 'root.Session.Name = value;'
-neo script check --mode nsfunction --member Outpost.RefreshUnlock 'return this.Level > 0;'
-neo script compile --mode nsfunction --member Outpost.RefreshUnlock 'return this.Level > 0;'
-neo script eval --returns string 'return root.Assets.Outposts[0].FullDisplayText;'
-neo script eval --function Outpost.RefreshUnlock --this-value <id> --args '[3]'
-```
-
-Method calls may be used as statements even when they return a value. The
-runtime evaluates the call and discards the result. This also applies to
-collection methods, delegates, actions, and fluent calls:
-
-```neo
-this.TryRefresh();
-this.Items.Insert(0, item);
-this.Items.Remove(item);
-```
-
-A generic receiver may call methods from its class or interface constraint,
-including void calls used as statements. Generic arguments substitute through
-the constraint; nullable receivers still require narrowing or null handling.
-
-Runtime `is` tests on generic values check whether the bound can overlap the
-tested type. A class bound need not implement an interface itself when a
-subclass can implement it. A successful pattern binding exposes that interface's
-members, including after `if (item.Data is not IReceiver receiver) continue;`.
-Sealed classes without the interface and unrelated class bounds remain disjoint.
-
-An interface guard also narrows the original receiver without a pattern binding.
-After `if (item is not IReceiver) continue;`, `item` exposes both its declared
-class members and `IReceiver` members. The same applies to guards that return,
-throw, or break. Reassignment clears the proof, and paths that did not pass the
-guard cannot use it.
-
-A class can construct each interface only once. A class value known to implement
-`IBox<int>` cannot pass an `is IBox<string>` check, including through inherited
-interfaces. Open classes can still acquire an unrelated interface. Checks between
-interface-only receivers retain their runtime behavior.
-
-Guards preserve a generic receiver's `T` identity and its declared bound. A
-declaration pattern also keeps the original receiver's members: after
-`if (item is not IReceiver receiver) return;`, `item` still has its class or
-generic type, while `receiver` exposes `IReceiver`.
-
-A later class guard retains these capabilities. For example, after checking
-`item is IReceiver` and then `item is Furnace`, the original `item` exposes both
-`Furnace` and `IReceiver` members. A sealed class that cannot implement the
-proven interface remains an impossible test.
-
-Guards also narrow named global values and static member paths. Qualified and
-unqualified static access share the same proof, including inherited statics.
-Assignments clear affected proofs. A closure must establish its own guard
-because the stored value can change before the closure runs.
-
-Functions, natives and interface functions can declare their own type
-parameters after the name, each with an optional constraint and default:
-
-```neo
-public static T? FirstOf<T extends Item = Item>(List<T> items) => items.FirstOrDefault();
-```
-
-A call writes every type argument or omits the defaulted tail
-(`FirstOf<Seed>(items)`, `FirstOf(items)`). When `<...>` is omitted, supplied
-arguments infer the function's type arguments. Lambda inputs bind first so their
-returns can infer output parameters, as in `Map(seed, (value) => value.Price)`.
-Defaults fill parameters with no inference evidence. The destination/expected
-return type does not provide evidence. Explicit `<...>` keeps explicit/default
-binding and does not infer omitted trailing arguments. Conflicting types require
-explicit arguments; inference does not invent a shared ancestor for siblings. Function type
-parameters take no `@id`, and an override declares the same count, constraints
-and defaults, though it may rename them.
-
-Prefer `--json` for automation.
-
-`neo script check --all` reconstructs the prospective project entirely from
-the local workspace. It checks local schema bodies and stored dialogue,
-migration, and text-variable bodies against that same source transaction, so
-new declarations do not depend on a prior push or a network fetch.
-
-Inside an inline Class body, unqualified names resolve against that Class;
-invoke delegate and action members directly with `Selector()` or `OnUpdated()`.
-Spell a zero-argument action as bare `NeoAction`; type arguments name action
-parameters, so `NeoAction<void>` is invalid rather than a zero-argument alias.
-Clear every subscribed listener from a stored action with
-`this.OnUpdated.Clear()`. `Clear()` is a mutating statement and follows the
-action member's effective storage and writability. Only the action's declaring
-class and derived classes may invoke it or call `Clear()`; public external
-callers may subscribe and unsubscribe with `+=` and `-=` but cannot raise or
-reset the action.
-
-Inline `NeoDelegate` lambdas may be returned, stored, or assigned to a typed
-local such as `NeoDelegate<int, int> twice = (x) => x * 2;`, and may read
-surrounding locals and parameters. Those values are captured when the lambda is
-created, so later changes to the outer binding do not alter the closure.
-Any non-null delegate expression can be called directly, including
-`callbacks[0](value)`, `(condition ? first : second)()`, and `Factory.Make()()`.
-Force-unwrap a nullable delegate before calling it, as in `callbacks["key"]!()`.
-Void delegates can only be called as statements.
-Instance delegate field defaults are compiled against their declared signature.
-Each instance binds defaults that read `this` to itself; invalid lambda bodies
-are reported at the declaration by status, editor validation, and preparation.
-Static delegate fields use static class scope: they can read static members
-without an instance owner, and cannot access `this` or instance members.
-Field initializers can read their declaring class's static members without a
-qualifier, including inherited statics and reads inside nested object defaults:
-`public int First = Run();` and `public static int Copy = Number;`.
-Eager initializers cannot read instance members or `this`; static defaults also
-cannot capture class-header parameters. Defer instance reads inside a delegate
-lambda. A delegate field default may also name a method group bare.
-`Value = Read` or `this.Read` binds each new instance to its own `Read`, and a
-static function may be named as `Read` or qualified as `Holder.Read`/`Other.Read`.
-A qualified method group must name a static function. Method groups use the same
-signature rule as in a body, and a mismatch is reported at the declaration.
-A static field that names another static copies a value, as in
-`public static int B = Holder.A;`. A class, List, Set, or Dictionary static
-already owns its value, so call `Clone()` or use `Reference`. A static delegate cannot copy another Class's delegate field, including an inherited one,
-because its closure compiles in its own Class; wrap it as `() => Other.Call()`.
-Omitted constructor fields use their authored defaults, including optional fields.
-Writable collection defaults belong to each instance; mutations persist on later
-reads without changing another instance's default. Fields without defaults remain
-absent, and `null` arguments in generated member-wise constructors mean omission.
-Collection type arguments in constructions, such as `new Box<List<int>>([1, 2])`,
-work even when no field declares that collection type. Preparation includes the
-needed type descriptors; spec-only types remain in the test candidate.
-Generic primary constructors also accept stored collection arguments, such as
-`public static Box<List<int>> Value = new([1, 2]);`. Stored replay uses the closed
-parameter type to preserve collection references.
-Stored constructors validate every authored type argument, including names nested
-inside collections and generic types. An expected field type cannot hide an unknown
-type in `new Box<List<MissingType>>()`.
-Typed locals also accept generic class types such as `Box<int> box = new(1);`.
-Generic class arguments remain invariant through inheritance: `IntBox : Box<int>`
-can be assigned to `Box<int>`, but not `Box<string>`. Arguments are substituted
-through every intermediate base class, including nested generic arguments.
-Explicit lambda parameter annotations accept the same type grammar as
-declarations, including `decimal`, generic parameters, collections, arrays, and
-nullable types.
-
-Instance reads in collection-entry initializers must be deferred. A default such
-as `List<int> Values = [this.Number + 1]` (or `[Number + 1]`) is a compile error:
-the instance does not exist while the entry initializer runs. Delegate lambdas
-such as `() => this.Number` and method groups such as `Read` or `this.Read`
-remain valid, including inside `new Callback { Read = Read }` entries.
-
-A lambda may use an expression body too: `(x) => x * 2` is the block body
-`(x) => { return x * 2; }`. In a void delegate the expression is a statement,
-so it must call or assign. A dictionary-literal body needs parentheses,
-`() => ({ "a": 1 })`, because a bare `{` after the arrow always opens a block.
-
-```neo
-List<Item> ready = this.Items.Where((item) => item.Count > 0);
-```
-
-`==`, `!=`, `Contains`, `IndexOf`, and `Remove` compare Class, interface,
-List, Set, and Dictionary values by identity: two reads of one stored value are
-equal, and two values with identical fields are not. Primitives, enums,
-vectors, and media references compare by value. The static type decides, so an
-unconstrained generic `T` compares by value.
-
-Calling `Equals(other)` on a non-null generic value dynamically uses the
-runtime Class's one-argument `Equals` Function or NSFunction when it returns
-`bool`, including the effective override. Values without that member fall back
-to value equality. For local sets, that fallback compares their current entries
-in insertion order, regardless of prior reads or mutations.
-
-Object initializers are available in method bodies and `.spec.neo` tests:
-
-```neo
-var tile = new DirtWetTile { Cell = Vector2Int(3, -2) };
-```
-
-An entry that settles a required member is evaluated with construction, as the
-constructor argument it stands in for. The remaining entries then use ordinary
-assignment rules in source order, including property setters, access checks,
-and readonly restrictions. Initializer expressions read the caller's scope.
-
-## Nullability and ownership
-
-Do not access a nullable receiver directly. First narrow it with a condition, or
-use null propagation `?.`, coalescing `??`, or explicit force unwrap `!` when
-failure is intended:
-
-```neo
-if (player.Target != null) {
-  return player.Target.Name;
-}
-return player.Target?.Name ?? "Unknown";
-```
-
-Null propagation remains active across following required accesses in the same
-chain, so `config.Hat?.Head.Idle.Down.Frames` safely returns null when `Hat` is
-null. A descendant that is itself nullable still needs its own `?.`, `??`, `!`,
-or narrowing guard before the next access.
-
-Inside an instance body, `Member` and `this.Member` share null and type-check
-narrowing. A local or parameter named `Member` shadows the implicit member;
-`this.Member` still names the instance field. Reassigning a narrowed path to a
-nullable value clears its non-null fact and facts about its descendants. Writes to
-unrelated members preserve existing guards, including inside loops. Earlier
-conditions being false also narrow receivers in later `else if` conditions.
-
-A nullable value coalesced with a non-null fallback produces a non-null result,
-including in constructor arguments: `new Sprite(item.Sprite ?? SpriteInfo.Empty)`.
-A nullable fallback keeps the result nullable when the left operand can be null.
-When a reference result is expected, `first ?? fallback` selects the reference
-itself. A present reference to a null target does not select the fallback.
-In a scalar context, references still read their targets before coalescing.
-
-Treat lookup-return values with the same nullable narrowing rules.
-
-Runtime declaration patterns follow the possible runtime type, not only the
-static declaration. An open Class value may match an otherwise unrelated
-interface through a derived Class that implements it; a sealed Class with no
-such relationship remains a compile-time impossible pattern.
-
-A declaration pattern introduced by `is` stays available after a guard when
-every path that falls through matched the pattern, including when the guard's
-other paths return from a nested block:
-
-```neo
-if (item is not BedItem bedItem) {
-  throw "Expected a bed item";
-}
-return bedItem.Name;
-```
-
-`value is not SomeClass` negates a type test. An optional binding, as in
-`value is not SomeClass item`, exists only where the test is known to be false:
-the `else` branch, the right side of `||`, or after a rejecting guard. The
-operand is evaluated once. `not` remains a normal identifier elsewhere.
-
-Use `SpriteInfo.Empty` when a required sprite should intentionally render no
-image. It is the canonical non-null empty sprite: it has no backing file and
-uses slice index zero.
-
-Let runtime ownership—not body kind—decide whether a write target is Immutable,
-Save, Session, Setter, or otherwise writable. A constructor writes only its
-`this` instance. A writable structured-leaf field still inherits the receiver's
-effective storage restrictions.
-
-## Tuples and destructuring
-
-A tuple has at least two ordered elements. Labels are optional and explicit;
-`Item1`, `Item2`, and later positional aliases always work. Labels do not affect
-type identity. Slots are immutable, so replace a whole tuple to change a value.
-Referenced objects retain their normal permissions and identity.
-
-```neo
-(int Row, int Col) position = (Row: 2, Col: 3);
-var (row, col) = position;
-(int first, (bool enabled, int _)) = (1, (true, 9));
-var score = positions.Select(((r, c)) => r + c);
-foreach (var (key, value) in weights) { Debug.Log(key); }
-```
-
-`((r, c)) =>` accepts one tuple; `(r, c) =>` accepts two parameters. Recursive
-patterns work in declarations, loop bindings, and tuple lambda parameters. `_`
-discards a position. Assignment deconstruction is not supported.
-
-Tuple equality compares corresponding values recursively. Decimal scale does
-not affect equality. Classes, collections, and explicit references compare by
-identity. `Contains`, `IndexOf`, `Remove`, and `ToSet` use the same rule.
-Nullable tuples use `(int, int)?`; nullable elements use `(int?, int)`.
-
-## References
-
-`Reference<T>` names one stored row. `T` can be any value type, including
-collections and other references. Code types such as `Action<int>` are
-rejected. `T` picks one of two categories:
-
-- A handle is a class, interface, list, set, or dictionary. The reference is the
-  object itself, so `Reference<Item>` reads as `Item`. Assigning an `Item`
-  rebinds it.
-- A slot is any other value type: `bool`, numbers, `string`, enums, vectors,
-  `Color`, sprites, audio clips, `NeoVariant<T>`, `NeoDialogueReference`, or a
-  single `Reference<U>`. The reference names another member and reads and writes
-  that member's value. It converts to its `T` by reading.
-
-`Reference(place)` forms a reference to a stored member, such as `this.Gold`,
-`root.Player.Gold`, `Npc.Mood`, or `item.Count`. Its type comes from the
-member's declaration. When `Selected` is `Reference<Item>`,
-`Reference(this.Selected)` is `Reference<Reference<Item>>` and names the
-selection slot itself. Locals, parameters, list or dictionary elements, vector
-components, getters, query results, and new values have no row to reference.
-Access checks apply where the reference is formed.
-
-Assigning to a reference rebinds it when the right side is a reference of the
-same type. Otherwise the value is written into the target:
-
-```neo
-this.A = 5;                       // writes 5 into A's target
-this.A = this.Count;              // writes Count's value into A's target
-this.A = this.B;                  // A now names B's target
-this.A = Reference(this.Count);   // A now names Count
-this.A += 1;                      // reads A's target, writes it back
-```
-
-Conditional assignments such as `this.A = choose ? first : second` rebind `A`
-when both branches supply references. Scalar branches write through `A`; a mixed
-reference and scalar choice reads the selected reference's target. Constructors
-may initialize their own reference fields this way, but cannot write through
-external targets.
-
-A plain value never becomes a reference: passing `3` to a `Reference<int>`
-parameter is an error. A handle reference never owns, so it can't hold a new
-list or a query result.
-
-`==` compares handles by identity and slots by value. A collection of
-references compares entries by target, so a `Set<Reference<int>>` holds
-distinct slots. Narrow a `Reference<T>?` with a null check before writing
-through it.
-
-The target row decides every write. Writing an asset-owned target errors, and a
-`readonly` target can't be written after initialization. A slot reference's
-`OnChanged` listeners fire when it rebinds and when its target's value changes.
-Inside a generic body, `Reference<T>` takes the category of `T`'s binding.
-
-## Overloaded calls
-
-A call to an overloaded function picks one overload at compile time from its
-arguments. Candidates are every overload the receiver's type sees, across all
-inheritance levels; a type qualifier takes static ones, an instance receiver
-instance ones. An overload applies when the argument count fits its required
-and default parameters and each argument converts to its parameter. Lambdas,
-method groups, `null`, collection literals, and `.North` apply by shape.
-
-Among applicable overloads, the one whose parameters are closer to the
-argument types wins: an exact type beats a conversion, and `Bag` beats `Item`
-when `Bag : Item`. On a tie, the overload filling no defaults wins, then the
-non-generic one. Otherwise the call is ambiguous: `Scale(float)` and
-`Scale(decimal)` can't take an `int`, so write `2.0` or `2m`. A generic
-overload takes explicit type arguments, or infers them from the arguments the
-way a lone generic call does, with defaults filling parameters nothing infers.
-An overload whose type arguments can't be inferred isn't a candidate: beside
-`F(int a, string b)`, `F<T>(T a, T b)` takes `F(1, 2)` but not `F(1, "a")`.
-
-A method group picks the overload whose parameters match the target delegate
-type exactly, in assignments, `+=`, `OnChanged`, `@listeners`, and delegate
-arguments. `var f = Read` is an error when `Read` is overloaded; give `f` a
-delegate type.
-
-Pass the delegate type to mock or spy on an overloaded function:
-
-```neo
-var quote = mock.function<NeoDelegate<int, Item, int>>(Pricing.Quote);
-```
-
-Script evaluation selects an overload with a signature:
-`neo script eval --function "Inventory.Add(Item, int)"`.
-
-## Numeric types
-
-`int` stores whole numbers and division truncates toward zero. Ordinary integer
-arithmetic retains the precision of the stored number. `float` literals, stored
-values, and every float arithmetic step round to 32 bits, matching Unity.
-`decimal` is exact base-10 and is the only type to use for currency or other
-values that must not drift.
-
-## Bitwise integer operators
-
-Use `~`, `&`, `^`, `|`, `<<`, `>>`, and `>>>` with non-nullable `int` operands.
-The compound forms are `&=`, `^=`, `|=`, `<<=`, `>>=`, and `>>>=`.
-Enums, bools, float literals such as `1.0`, and decimals are not accepted.
-Use `Set<Enum>` for enum membership.
-
-```neo
-int mask = (region << 8) | (tile & 255);
-bool hasEast = (mask & 2) != 0;
-mask &= ~2;
-```
-
-Each operand wraps modulo 2^32 into signed int32 at the bitwise boundary.
-Every result is signed int32. Ordinary integer arithmetic is unchanged.
-Shift counts use their low five bits: 32 means 0, 33 means 1, and -1 means 31.
-`>>` extends the sign bit; `>>>` fills with zero but still returns a signed
-result. Thus `-1 >>> 1` is 2147483647 and `-1 >>> 0` is -1.
-Operands evaluate once, left to right. A compound assignment captures its
-target and reads its old value before evaluating the right operand.
-
-Precedence from tightest to loosest: unary, switch expressions, multiplication/division/remainder,
-addition/subtraction, shifts, comparisons, equality and `is`, `&`, `^`, `|`,
-`&&`, `||`, `??`, then `?:`. Binary bitwise operators associate left to right.
-Keep shift characters contiguous: `x >> 1` is valid; `x > > 1` is not.
-
-## Numeric builtins
-
-Use the `Math` namespace for numeric utilities with C# names and C# semantics:
-`Min`, `Max`, `Clamp`, `Round`, `Floor`, `Ceiling`, `Truncate`, `Abs`, `Sign`,
-`Sqrt`, and the `PI` and `E` constants.
-
-```neo
-return Math.Clamp(this.Quality + bonus, 0, 10);
-```
-
-Each result follows the arithmetic join of its argument types: all-`int` gives
-`int`, any `float` gives `float`, any `decimal` gives `decimal`, and `decimal`
-never mixes with `float`. `Round`, `Floor`, `Ceiling`, and `Truncate` are the
-language's `float`-to-`int` conversions: they return `int` for `int` and
-`float` input, keep a `decimal` a `decimal`, and reject a non-finite argument
-at runtime. `Round` rounds midpoints to even, matching `decimal.Round(0)`.
-`Sign` always returns `int`; `Sqrt` takes `int` or `float` only.
-
-`Math` is an unqualified builtin qualifier, never a type or value, so no Class,
-enum, parameter, or local may shadow it. Qualified members use their owner's
-namespace and may be named `Math`; access one as `this.Math` or
-`SomeValue.Math` without colliding with the builtin qualifier.
-
-## Vector math
-
-`Vector2`, `Vector3`, `Vector2Int`, and `Vector3Int` support `+`, `-`, unary
-`-`, multiplication by a scalar in either order, and division by a scalar.
-Both vector operands must have the same type. Integer vectors accept only
-integer scalars; float vectors accept int or float. Integer division truncates
-toward zero. Division by zero throws. `==` and `!=` keep exact component equality.
-
-```neo
-Vector2 next = position + direction * speed;
-float distance = Vector2.Distance(position, target);
-Vector2 heading = (target - position).normalized;
-Vector2 step = Vector2.MoveTowards(position, target, speed);
-```
-
-All vectors expose read-only `magnitude` and `sqrMagnitude`, static `Distance`,
-`Min`, `Max`, and constants `zero`, `one`, `up`, `down`, `left`, and `right`.
-Three-dimensional vectors also have `forward` and `back`. Float vectors add
-`normalized`, `Dot`, `Lerp`, and `MoveTowards`; `Vector3` adds `Cross`.
-Integer vectors have no implicit conversion to float vectors.
-
-`Color.Lerp(a, b, t)` interpolates all four channels, including alpha.
-Both vector and Color `Lerp` clamp t to [0, 1]. `normalized` returns zero when
-the magnitude is at most 0.00001. A negative MoveTowards delta moves away.
-Computed properties are read-only; arithmetic, math results, and constants
-are fresh values. Component writes retain the ordinary vector aliasing rules.
-
-## String builtins
-
-Use `text.Replace(search, replacement)` to return a string with every
-non-overlapping occurrence replaced. Matching is ordinal and case-sensitive.
-The search must be nonempty; an empty search throws an error. Neither argument
-may be null. The receiver stays unchanged.
-
-```neo
-return "banana".Replace("a", "o"); // "bonono"
-```
-
-Strings also have `Length`, `Substring(startIndex[, length])`, `IndexOf`,
-`LastIndexOf`, `Split(separator)`, `PadLeft`/`PadRight(totalWidth[,
-paddingChar])`, `Trim`, `TrimStart`, and `TrimEnd`, plus the statics
-`string.Join(separator, values)`, `string.IsNullOrEmpty`, and
-`string.IsNullOrWhiteSpace`. Lengths and indices count UTF-16 code units, every
-comparison is ordinal, and whitespace is C#'s `char.IsWhiteSpace` set. `Split`
-keeps empty entries and returns a new list. `Join` takes a `List<string>` or
-`Set<string>`; turn other entries into text first with
-`values.Select(v => $"{v}")`. `s?.Length` is an error; use
-`string.IsNullOrEmpty(s)` or narrow first.
-
-```neo
-List<string> parts = this.Text.Trim().Split(" ");
-int quantity = int.TryParse(parts[1]) ?? 0;
-return $"{slot.ToString("D3")} {price.ToString("N2")}";
-```
-
-`int.Parse`, `float.Parse`, and `decimal.Parse` accept ASCII digits with an
-optional sign (plus a fraction for `float` and `decimal`, and an exponent for
-`float`) after trimming ASCII whitespace, and throw on anything else or on a
-value the type can't hold. `TryParse` returns `null` instead of throwing.
-`decimal.Parse` never rounds: more than 28 significant or fractional digits is
-an error.
-
-Numbers format only with an explicit format: `D<n>` (int only, zero-padded),
-`F<n>` (fixed point), or `N<n>` (fixed point with `,` grouping), where `n` is 0
-to 28 and defaults to 2 (1 for `D`). `float` rounds half to even from its exact
-value, `decimal` rounds half away from zero, and a result that is all zeros has
-no `-` sign. For plain text, use interpolation: `$"{value}"`.
-
-Integer inputs assigned to `float` round to float32. This also applies to
-function arguments and returns, collection entries, and `List.Repeat` with a
-float entry type. `Contains` and `IndexOf` on float collections also convert
-integer search arguments. Nullable assignments preserve `null`.
-
-## Collection builtins
-
-Lists expose their size as either `items.Count` or `items.Count()`. Use
-`items.Count((item) => predicate)` to count only matching entries without
-materializing a filtered list. The same Count forms work on Dictionary and Set
-collections; dictionary predicates may accept `(key, value)` just like the
-other collection callbacks.
-
-Use `Any()` or `Any((item) => predicate)` to check for a match, and
-`All((item) => predicate)` to check every entry. Both short-circuit; an empty
-collection has `Any() == false` and `All(...) == true`.
-
-`First`, `FirstOrDefault`, `Last`, `LastOrDefault`, `Single`, and `SingleOrDefault` accept zero arguments
-or one predicate. `First` and `Last` throw when no entry matches. Enum sets
-return enum values, including when a predicate selects the entry. `Single` throws unless
-exactly one matches; `SingleOrDefault` still throws for multiple matches.
-The `OrDefault` forms return nullable entries and use `null` for no match.
-
-Build eager, read-only list results with `SelectMany((item) => item.Children)`,
-`OrderBy((item) => item.Name)`, `OrderByDescending((item) => item.Score)`,
-`Skip(count)`, `Take(count)`, `SkipWhile((item) => predicate)`,
-`TakeWhile((item) => predicate)`, `Reverse()`, and `Concat(other)`.
-`SelectMany` requires a non-null list or set from its selector. Sorting is
-stable, evaluates each key once, uses ordinal string comparison, and accepts
-bool, int, float, decimal, or string keys, including nullable keys. Null sorts
-first ascending and last descending. Negative skip/take counts
-behave as zero. Reference entries keep their identity and storage permissions;
-a read-only result does not grant additional write access to its entries.
-
-```neo
-return this.Beds
-  .SelectMany((bed) => bed.Plants)
-  .Where((plant) => plant.Ready)
-  .OrderBy((plant) => plant.Name)
-  .Take(10);
-```
-
-`Sum`, `Average`, `Min`, and `Max` accept zero arguments or one selector.
-Sum/Average require int, float, or decimal values; Min/Max also accept strings
-and bools. Null values are skipped. Sum returns zero on empty input; the other
-reductions return null for nullable input and throw for required input.
-Average of ints returns float. Decimal calculations stay exact; decimal Average
-rounds half-even within Neo's 28-digit envelope. Float Min stops at the first
-NaN; Max prefers ordinary values to NaN.
-
-`MinBy((item) => item.Score)` and `MaxBy(...)` return the first entry with the
-winning key. They skip null keys unless every key is null, then keep the first
-entry. Empty input throws unless the entry type is nullable.
-
-List and Set support `Aggregate((acc, item) => ...)`,
-`Aggregate(seed, (acc, item) => ...)`, `Distinct()`, and
-`Zip(other, (left, right) => ...)`. Aggregate visits entries in order; an empty
-unseeded fold throws. Distinct retains first occurrences using Contains equality
-and returns a read-only List, including nullable entries. Zip stops at the
-shorter input.
-
-`GroupBy((item) => item.Category)` returns a read-only dictionary of read-only
-lists. `ToDictionary((item) => item.Name)` optionally accepts a second value
-selector. Keys must be non-null strings or enum values; duplicate dictionary
-keys throw. Dictionary callbacks take `(key, value)`. `.Keys` and `.Values`
-return read-only lists in dictionary traversal order (integer-looking string
-keys precede other strings in numeric order).
-
-Chain `ThenBy` or `ThenByDescending` after OrderBy to add stable secondary keys.
-An inferred `var` retains this capability; ordinary List/Set annotations,
-function boundaries, and non-ordering queries erase it. Every ordering call is
-eager: it caches keys and sorts the snapshot, costing O(n log n * k) for k key
-levels. Each selector runs once per entry per level. Mutating a snapshot through an explicitly writable local alias invalidates its cached keys; ThenBy then throws until a new OrderBy establishes an ordering.
-
-Writable ordered lists support `items.Sort()` for scalar entries or
-`items.Sort((left, right) => left.Score - right.Score)` for an int comparison.
-Sort returns void, preserves entry identity, and is stable. It rejects mutation
-of the target list through aliases while comparisons run; entry fields retain
-their existing write permissions. A failed comparison leaves the order unchanged.
-
-Use `items.IndexOf(value)` to return the zero-based index of the first equal
-list entry, or `-1` when the value is absent. `IndexOf` is list-only and uses
-the same equality as `Contains`.
-`Remove(value)` removes the first equal entry using that same equality, including
-scalar entries supplied by instance field defaults. Removing a missing value is a no-op.
-
-Use `items.Insert(index, value)` to insert an entry into a writable ordered
-list. The index may range from zero through `items.Count`; the count appends
-the entry. Other indices throw an error. `Insert` returns void.
-
-Use `List.Repeat(value, count)` to build a list of `count` copies of a value
-instead of hand-counting a literal or looping around `Add`:
-
-```neo
-List<int> scores = List.Repeat(0, 10);
-```
-
-The entry type is normally inferred from the value and joined with the
-assignment context, exactly like a list literal, so assigning
-`List.Repeat(0, 4)` to a `List<float>` widens the entries to `float`. When the
-value cannot carry the type by itself, use a call-site type argument, for
-example `List.Repeat<InventoryItemStack?>(null, slotCount)`. Never spell type
-arguments on the qualifier: `List<int>.Repeat(0, 3)` is an error, and bare
-`List` is a qualifier, not a value.
-
-`count` must be an `int` — a `float` count is a compile error, and a negative
-count fails at runtime with `List.Repeat count must be non-negative; got
-{count}.`. A count of `0` produces an empty `List<T>` whose entry type is
-still known. The value is evaluated exactly once, then the count exactly once,
-so side effects happen once regardless of `count`, and every entry is that one
-value: for a reference-typed entry the same reference repeats `count` times.
-
-## Conditional and logical operators
-
-Use `condition ? whenTrue : whenFalse` for a value chosen by a condition:
-
-```neo
-T modified = this.Modifier != null ? this.Modifier(value) : value;
-```
-
-The operator has lower precedence than `??`, `||`, and `&&`, associates from
-the right, and evaluates only the selected result arm. Both arms must share a
-common assignable type or fit the surrounding expected type.
-
-Use `&&` and `||` with C# precedence: `&&` binds tighter than `||`, and
-parentheses preserve explicit grouping. Both operators short-circuit, so the
-right operand is evaluated only when it can change the result. Chained
-expressions retain every operand; `a || b || c` never skips `b`.
-
-## Loops and transfer
-
-Use C#-shaped loops:
-
-```neo
-for (int i = 0; i < Items.Count; i++) {
-  if (Items[i].Disabled) {
-    continue;
-  }
-  Visit(Items[i]);
-}
-
-foreach (var item in root.Save.Items) {
-  item.Enabled = true;
-}
-```
-
-A `foreach` receiver must be non-null. It snapshots membership/order once at
-entry, so adding/removing collection rows does not alter the scheduled
-iterations. `foreach (var value in dictionary)` binds each value. To read keys
-as well, deconstruct a dictionary entry:
-
-```neo
-foreach (var (key, value) in this.Damage) {
-  if (key == ToolType.Pickaxe) {
-    ApplyDamage(value);
-  }
-}
-
-foreach ((ToolType key, float value) in this.Damage) {
-  ApplyDamage(value);
-}
-```
-
-Deconstruction accepts a dictionary local or member path. Assign a computed
-receiver to a local first. It snapshots keys once at loop entry and reads each
-value through `dictionary[key]`; removing a key follows the normal missing-key
-read behavior. Both bindings are read-only, although writes through a writable
-entry remain valid. Enum-keyed dictionaries yield enum keys, including in
-collection lambdas such as `Where((key, value) => key == ToolType.Pickaxe)`
-and `Select((key, value) => key)`. String-keyed dictionaries yield strings.
-
-Use `break` for the nearest loop or switch and `continue` for the nearest
-loop. A `continue` inside a switch nested in a loop continues the loop.
-
-A `while` loop checks its boolean condition before each iteration. A
-`do / while` loop runs its body once before checking the condition. Both
-require braces; the `do / while` condition ends with a semicolon.
-
-```neo
-while (this.HasWork()) {
-  this.ProcessNext();
-}
-
-do {
-  this.ProcessNext();
-} while (this.HasWork());
-```
-
-`continue` checks the condition again in both loops.
-
-## Switch
-
-Use scalar, enum, or nullable selectors with compile-time constant labels:
-
-```neo
-switch (direction) {
-  case Direction.North:
-    Move(0, 1);
-    break;
-  case Direction.East:
-  case Direction.West:
-    Stop();
-    break;
-  default:
-    throw $"Unknown direction: {direction}";
-}
-```
-
-Permit `int`, `string`, `bool`, enum, and nullable forms. Stack labels when
-they share one body. End every reachable non-empty section with `break`,
-`return`, `throw`, or `continue` when a surrounding loop makes it valid.
-Do not use implicit fallthrough, pattern cases, guards, or `goto` in statement switches.
-
-### Switch expressions
-
-Use `value switch { pattern => result, ... }` to produce one value. Arms may
-use scalar/enum constants, `null`, type patterns (`Damage`), declaration
-patterns (`Damage damage`), or `_`. A declaration binding is scoped to its
-arm's optional `when` guard and result. Patterns and guards run in order; the
-selector runs once and only the chosen result runs.
-
-```neo
-closed class HitResult {}
-sealed class Miss : HitResult {}
-sealed class Damage : HitResult { public int Amount = 0; }
-class Combat {
-  public string Describe(HitResult result) => result switch {
-    Miss => "miss",
-    Damage damage when damage.Amount > 10 => "strong hit",
-    Damage damage => $"{damage.Amount}",
-  };
-}
-```
-
-Every switch expression must be exhaustive. Handle every bool/enum option or
-closed-class branch, plus null for nullable input. Other types require a
-covering type or `_` fallback. A guard contributes no exhaustive coverage
-unless it is literally `true`. Missing and unreachable cases are compile
-errors. Adding a new subtype recompiles affected consumers.
-
-Result arms must fit the expected type or have a common assignable type.
-Property, relational, list, and positional patterns are unsupported. Pattern
-cases in statement switches remain unsupported. Install the matching Unity
-SDK before exporting the new switch-expression IR; older SDKs reject it.
-
-## Structured errors and finally
-
-Throw a required string or any `NeoError` subclass. String throws create
-`NeoError` values. Each error has a required read-only `Message`, including
-an empty message. Derive ordinary classes from `NeoError` to carry typed data.
-
-```neo
-try {
-  return GetUnsafe();
-}
-catch (NeoArgumentError error) when (error.Message != "") {
-  Report(error.Message);
-  throw;
-}
-catch (NeoError error) {
-  return Fallback();
-}
-finally {
-  ReleaseResource();
-}
-```
-
-A try needs catches, a finally block, or both. Catch bindings are read-only.
-Typed catches match subclasses, and `catch (string message)` matches every
-ordinary error while binding its Message. An unfiltered base catch must follow
-all catches it covers. Filters run before any intervening finally blocks,
-including across calls. A false or failing filter continues the original search.
-Bare `throw;` rethrows the original payload from a catch.
-
-Finally runs on normal completion, return, break, continue, and ordinary errors.
-The return value is evaluated before cleanup. An error escaping cleanup replaces
-the pending error; an error caught inside cleanup does not. Return and loop
-transfers cannot escape a finally block. A nested loop may break or continue.
-Bare throw inside finally needs its own inner catch.
-
-Runtime failures use `NeoNullReferenceError`, `NeoIndexOutOfRangeError`,
-`NeoKeyNotFoundError`, `NeoArgumentError`, `NeoArithmeticError`, or
-`NeoInvalidOperationError`. Unexpected native failures become `NeoHostError`
-with Message `"Check logs for more details."`. Execution limits, unavailable
-preview natives, cancellation, and invalid compiled data are noncatchable.
-Suspended Unity calls retain cleanup until resumed; abandonment skips cleanup.
-Completed writes are not rolled back. Install the matching SDK for schema 45.
-
-## Debug output
-
-Use `Debug.Log(message)`, `Debug.LogWarning(message)`, and
-`Debug.LogError(message)` as void statements. `Debug.Assert(condition, message)`
-logs an assertion failure when its non-null bool condition is false. Errors
-and failed assertions log without throwing. Both assertion arguments are
-evaluated once even when the condition passes; disabling a host sink also
-preserves argument evaluation.
-
-```neo
-Debug.Log($"Loaded {this.Items.Count} items");
-Debug.Assert(this.Items.Any(), "Expected at least one item");
-```
-
-Messages include authored NeoScript line/column locations and stack frames
-when source metadata is available. Browser consoles and Unity use the matching
-severity; CLI logs go to stderr so JSON stdout stays machine-readable. Getter
-re-evaluation may emit the same log again. `Debug` is a builtin qualifier,
-not a type; an authored local or Class named `Debug` takes precedence.
-
-## Triggering dialogues
-
-`root.Dialogues` mirrors the generated C# `Dialogues`: the same folders and
-groups under their generated C# property names.
-
-```neo
-public bool TryTalk() {
-  return root.Dialogues.NPCs.Talk.TryTrigger(this, () => {
-    this.AfterTalk();
-  });
-}
-
-public bool HasSomethingToSay => root.Dialogues.NPCs.Talk.CanTrigger(this);
-```
-
-- `root.Dialogues` has `TryTrigger(string dialogueId, onFinish)`,
-  `CanTrigger(string dialogueId)`, `VisitCount(pointer)`, and
-  `HasVisited(pointer)`.
-- A standard group has `TryTrigger(onFinish)` and `CanTrigger()`. A lookup
-  group takes its collection's entry class: `TryTrigger(value, onFinish)` and
-  `CanTrigger(value)`. The value must be a stored row.
-- A `NeoDialogueReference` has `id`, `TryTrigger(onFinish)`, and
-  `CanTrigger()`. Elements of a `Set<NeoDialogueReference>` are bare ids, so
-  pass one to `root.Dialogues.TryTrigger`.
-- `onFinish` is an optional `NeoDelegate<void>`: a lambda or a function member.
-  It runs after the dialogue finishes, fails, or is disposed.
-
-`TryTrigger` compiles only in functions, including effects, lifecycle hooks,
-and listeners, and in dialogue actions. `CanTrigger`, `VisitCount`, and
-`HasVisited` are reads, allowed wherever the `VisitCount` global is. Folders
-and groups aren't values. User code can't trigger dialogues.
-
-The Unity SDK queues every accepted request and shows one dialogue at a time
-through `Dialogues.OnTrigger`. A request for the running or an already queued
-dialogue returns false, as does every request when the game has no `OnTrigger`
-handler. `neo test`, `neo script eval`, dialogue dry runs, and the web editor
-have no dialogue runtime: `TryTrigger` and `CanTrigger` return false there and
-`onFinish` never runs.
-
-Source type names match C#: `class X : NeoDialogue` in `.neoflow`,
-`NeoDialogueGroup` and `NeoPriorityGroup` declarations, and
-`NeoDialogueReference` for a reference member. The old names `Dialogue`,
-`DialogueGroup`, `PriorityGroup`, and `DialogueRef` are compile errors that
-name their replacement.
-
-## Evaluation and migrations
-
-`neo script eval` uses authored values and the same evaluator as the web app.
-It reports effects from the isolated evaluation but never commits them. Put
-persistent NeoScript and data changes in tracked source and use `neo push`.
-
-Keep migrations as tracked action files under `Migrations/`:
-
-```sh
-neo migrate new <name> --target <ClassName|project>
-neo migrate list
-neo migrate check
-neo migrate run [--dry-run] [--skip-invalid]
-neo migrate prune
-```
-
-Run checks before migration execution. Review storage ownership and every write
-intent; do not assume an action body is writable merely because it compiled.
-
-`neo migrate run` reads the project from the server and prepares its writes
-locally, like push. If another commit lands while it runs, the run is refused:
-run it again. `neo loc` writes work the same way: a write refused because
-another commit landed is run again.
-
-VS Code rename follows override families and class constructors, resolves contextual enum options such as `.Success`, renames a constructor parameter's named arguments (`new Item(count: 1)`) in bodies, initializers, specs, and base clauses, and keeps local-variable renames scoped to their declaration. Assigned IDs are not required for these refactorings. Inferred locals initialized with conditional expressions retain their common branch type for member completion, navigation, and rename. Direct parenthesized expressions and chained delegate factory calls retain their result type too. `List.Repeat` results infer their element type from the value, explicit call-site type arguments, and expected list type, including for inferred locals and direct indexed access. Lambda returns use the delegate signature for target-typed constructors and enum argument suggestions. Member completion also follows optional access and null-forgiving receivers, including dictionary lookups.
-
-## Member change listeners
-
-Subscribe to a writable stored instance member with `owner.Field.OnChanged +=
-receiver.Handler`; use `-=` to remove the same receiver/handler pair. Handlers
-are noncapturing, return void, and accept the field's type. Bindings to Session
-receivers stay Session-only. Gameplay hosts dispatch after the write batch.
-Authoring, replay, migration, and dialogue dry-run hosts retain wiring without
-invoking callbacks. `owner.Field.OnChanged.Clear()` removes every handler,
-including `@listeners` defaults, in both Save and Session wiring.
-
-Instance getters take the same syntax, for example
-`this._quantity.Value.OnChanged += this.QuantityChanged`. A getter
-subscription lives only in memory for the play session, so subscribe from a
-function, effect, lifecycle hook, or dialogue action, never a constructor,
-initializer, or migration. Subscribing reads the getter once. The SDK calls the
-handler with a fresh result whenever something that read depended on changes,
-even if the result is equal, and several changes before the next read call it
-once. `Clear()` ends the subscription, and a constructor can't call it on a
-getter. Static getters, `base.Value`, and `@listeners` can't observe a getter.
-`neo test` dispatches getter subscriptions the same way, treating the test body
-as the host: handlers run after each of its statements, so the next statement
-sees their effects. A getter that reads through `Clone()` or a grid query can
-run more often in `neo test` than in Unity: any write but its own handlers'
-counts as a change. Other TypeScript hosts validate getter subscriptions and
-never call the handler.
-
-Persist wiring on the owning class value with named arguments, for example:
-
-```neo
-@listeners(Count: [root.Save.Tracker.CountChanged], Label: [root.Save.Tracker.LabelChanged])
-new Counter()
-```
-
-Every supplied argument must name a writable stored field. Names are contextual
-and may appear in any order. Use the existing nested positional override for a
-virtual owner; changing its listeners alone must not add a value override.
-Omitting a field inherits its listeners. An empty array suppresses inherited
-listeners and disappears when there is no inherited wiring to suppress.
-
-Decimal collection membership compares numeric values: `1.0` and `1.00` are
-equal for `ToSet`, `Contains`, `IndexOf`, `Add`, and `Remove`. Decimal scale
-is retained for display; string entries such as `"1.0"` and `"1.00"` stay distinct.