@neocompose/cli 0.87.1 → 0.88.0

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

@@ -0,0 +1,110 @@
+# Values
+
+How stored values are written: the root envelope, static members, local
+initializers, and the single-owner rule. Open a leaf from
+[References](#references) for IDs, `Reference<T>`, defaults, localization, or
+files.
+
+## Root and static bindings
+
+Edit only the initializer after `=` in the compiler-owned `Root.neo`. The root
+member's name, type, ID, lock, and storage are read-only.
+
+```neo
+Root root = new() {
+  @id("root-assets-member-id")
+  @storage(allowed: .Immutable)
+  Assets Assets = new() {
+    Outposts = [Assets.Capitol.Clone()],
+  };
+}
+```
+
+Persisted reusable values are static members on ordinary classes:
+
+```neo
+@id("assets-class-id")
+@storage(allowed: .Immutable)
+class Assets {
+  @id("capitol-member-id")
+  static Outpost Capitol = new {
+    Name = "Capitol",
+    Image = Images.Capitol.Slice(0),
+  };
+
+  static Outpost Home => Assets.Capitol;
+}
+```
+
+The member ID owns a root or static binding; never add a second `@id` before
+its initializer. A computed static getter such as `Home` is an alias with no
+binding or row. Statics created together may refer to each other in any
+order with no preliminary push.
+
+## One owner per value
+
+Class, List, Set, and Dictionary values have exactly one owner. Scalars and
+delegates copy. Placing an owned value elsewhere is refused at its authored
+position by status, push, and `neo test`: a static, a static's field, a
+collection entry, a local placed twice, or a constructor parameter stored in
+an ordinary field. Clone it or reference it:
+
+```neo
+static Outpost Annex = Assets.Capitol.Clone();
+static Reference<Outpost> Seat = Reference(Assets.Capitol);
+```
+
+## Local initializers
+
+Project initializers may live in any `.neo` file and need no imports. They
+are source organization, not runtime globals or server records.
+
+```neo
+List<NeoSortingLayer> SORTING_LAYERS = [
+  @id("existing-layer-id")
+  new NeoSortingLayer() { Name = "Default" }
+];
+```
+
+- Consume it with `SortingLayers = SORTING_LAYERS`. The consuming member owns
+  the identity; add no ID at the use. Keep existing nested IDs when
+  extracting; omit IDs on new rows.
+- An aggregate local has one owning use. Use `Reference(SORTING_LAYERS)` where
+  the member allows it; for an independent copy, copy the initializer without
+  IDs.
+- Scalars may have several uses. If the web later makes them diverge, pull
+  inlines the differing uses.
+- Complete member and collection entries compose inside constructor-backed
+  initializers and keep their concrete class.
+- A class local passed as a constructor argument or executable operand names
+  its single stored instance; see
+  [identities](identities.md#locals-as-constructor-arguments).
+- Scalar locals can't be used in expressions such as `BASE + 1`; inline the
+  expression. Executable closures can't read locals.
+- The editor offers extract-to-file, inline on a sole use, and duplicate at a
+  use. Move created files freely.
+
+## Dictionary keys
+
+Enum-keyed dictionaries take contextual or qualified option keys:
+
+```neo
+Dictionary<ToolType, float> Damage = { .Pickaxe: 10, ToolType.Axe: 2 };
+```
+
+Pull writes `.Option`. A quoted raw option ID also works; a quoted option name
+such as `"Pickaxe"` is not an ID. Keys of deleted options stay as quoted IDs.
+String keys are data: `dictionary["Id"]` reads an entry, while a class's
+`.Id` is its identity. String keys may be empty, contain whitespace, or use
+names like `__proto__`.
+
+## References
+
+- [Identities](identities.md): when to keep, omit, or author `@id`; moving
+  nested values; locals as constructor arguments.
+- [References](references.md): `Reference<T>` declaration, handle vs slot
+  semantics, source forms, same-push resolution.
+- [Defaults and localization](defaults-and-localization.md): virtual
+  members, sparse overrides, construction rebuilds, localized text, `neo loc`.
+- [Managed files](files.md): image and audio registries, binaries, Unity
+  import settings.

package/skills/neocompose-cli/references/world/animation.md

@@ -0,0 +1,133 @@
+# Animation
+
+Frame overrides, child selectors, segments, and tracks.
+
+A `NeoAnimationClip<T>` has `FPS`, `Duration`, `Frames`, and `Tracks`. Its
+`NeoAnimationFrame<T>` rows hold `Index`, `Overrides`, `ChildOverrides`, and
+`Actions`. Frames are sparse: each applies from its index until the next row.
+
+## Partial overrides
+
+Frame `Overrides` and [variant overrides](variants.md) accept partial
+structured literals:
+
+```neo
+new NeoAnimationFrame<MySprite> {
+  Index = 2,
+  Overrides = new { Sprite = new { SliceIndex = 1 } },
+}
+```
+
+An empty `new { }` changes nothing. A partial changes only named fields; a
+whole-leaf value replaces the leaf. Frame overrides may change `Enabled`,
+`FlipX`, and `SortingOrder` but never add, remove, or reorder `Children`.
+
+## Child selectors
+
+Tracks and frame overrides find direct children through selector delegates,
+not row IDs. Match on the project's own stable identity, such as an immutable
+`Name`, slug, or semantic position:
+
+```neo
+class LegPart : NeoObject {
+  public PantsSprite SelectPants() {
+    var child = this.Children.FirstOrDefault((candidate) => {
+      return candidate.Name == "Pants";
+    });
+    if (child is PantsSprite pants) {
+      return pants;
+    }
+    throw "Pants child is missing or has the wrong type";
+  }
+}
+```
+
+- Prefer a named function when the rule is reused or deserves a clear
+  failure; compatible inline closures also work.
+- A selector such as `this.SelectPants` runs in the lexical scope of the
+  class that declares the clip: `this` is the `LegPart`, not the track row or
+  an outer object that later copies the default.
+- Only for a deliberately authored child slot whose placement clones carry
+  `sourceValueId`, return
+  `Reference<T>(id: "<authored-child-id>", withProvenance: true)`. Missing
+  optional slots are skipped with diagnostics. A plain exact-ID reference
+  reintroduces the row-ID coupling selectors exist to avoid.
+
+## Segments
+
+`NeoAnimationSegment<T>` is a frame-indexed value lane. Its
+`NeoAnimationSegmentFrame<T>` rows have `Index` and `Value`; sparse values
+hold until the next row or `Duration`. Pass `Value` through the constructor:
+`new NeoAnimationSegmentFrame<int>(value: 60)`. `NeoSpriteAnimationSegment`
+is the sprite specialization.
+
+## Tracks
+
+`NeoAnimationClip.Tracks` is one polymorphic list:
+
+- `NeoAnimationChildTrack` plays `ClipKey` on the child its `Selector`
+  returns.
+- A project subclass of `NeoAnimationSegmentTrack<TChild, TValue>` plays a
+  segment onto one target member. Implement `Segment` as a stored value,
+  lookup, or getter.
+- `NeoSpriteAnimationSegmentTrack<TChild extends NeoSpriteObject>` targets
+  `NeoSpriteObject.Sprite`.
+
+```neo
+class StoredPantsTrack : NeoSpriteAnimationSegmentTrack<PantsSprite> {
+  public override NeoSpriteAnimationSegment Segment = new();
+}
+
+// inside LegPart
+public NeoAnimationClip<LegPart> Walk = new NeoAnimationClip<LegPart> {
+  Tracks = [
+    new StoredPantsTrack(selector: this.SelectPants) {
+      StartFrame = 0,
+      Direction = .Reverse,
+      OffsetEndIndex = 3,
+    },
+  ]
+};
+```
+
+- Tracks have `StartFrame`, `Direction` (`.Forward`/`.Reverse`), and a crop
+  window `OffsetStartIndex`/`OffsetEndIndex`. Cropping happens before
+  reversing; content past the clip truncates. Empty or inverted windows and
+  tracks that never enter the clip are rejected.
+- The selector's return type must fit `TChild` and the segment value `TValue`.
+- `Refresh` controls selector re-evaluation; track reads and segment getters
+  re-resolve on the next frame after a watched dependency changes.
+- Tracks writing the same member in one frame apply in list order; the last
+  wins.
+- New track rows omit `@id`; keep IDs already on pulled rows.
+
+## Animating class members
+
+A track can target a class member. Each frame writes the whole value, and a
+`null` frame clears it. The target must be a writable Save, Session, or
+Writable member on the child, and the segment class must fit it. Every
+`NeoObjectBase` declares `Collider`, so an attack hit box is a Session
+`Collider` override plus a `NeoCollider?` track:
+
+```neo
+class ColliderAnimationSegment : NeoAnimationSegment<NeoCollider?> {
+}
+
+@settings(target: NeoObjectBase.Collider)
+class SwingColliderTrack(NeoDelegate<SwordSprite> selector)
+  : NeoAnimationSegmentTrack<SwordSprite, NeoCollider?>(selector: selector) {
+  public override ColliderAnimationSegment Segment = new ColliderAnimationSegment() {
+    Duration = 3,
+    Frames = [
+      new NeoAnimationSegmentFrame<NeoCollider?>(value: new NeoCollider() {
+        Size = new(1, 1),
+        Offset = new(1, 1),
+        IsTrigger = true
+      }) { Index = 1 },
+      new NeoAnimationSegmentFrame<NeoCollider?>(value: null) { Index = 2 }
+    ]
+  };
+}
+```
+
+On `SwordSprite`: `@storage(allowed: .Session) public override NeoCollider? Collider;`

package/skills/neocompose-cli/references/world/grids-and-cell-patterns.md

@@ -0,0 +1,55 @@
+# Grids and cell patterns
+
+## NeoCellPattern
+
+An immutable ordered list of `Vector2Int` offsets. The constructor copies its
+input and keeps duplicates.
+
+```neo
+NeoCellPattern neighbors = NeoCellPattern.Box(1, excluding: .Center);
+NeoCellPattern custom = new(offsets: [new(-1, 0), new(2, 1)]);
+```
+
+- Shapes: `Box`, `Cross`, `Ring`, `Rect`, `Line`. Presets: `Center`,
+  `FourNeighbors`, `EightNeighbors`, `Empty`.
+- Box, Cross, and Line include the origin unless `excluding: .Center`.
+  Line's `length` counts steps beyond the origin, so `Line(new(1, 0), 3)` has
+  four cells.
+- `WithCenter`, `WithoutCenter`, `Translate`, and `Union` return patterns;
+  `Union` drops duplicates, keeping first occurrences.
+- `Cells(origin)` returns absolute cells in pattern order.
+- Presets are stored statics, so a field that owns a pattern can't default to
+  one (`= NeoCellPattern.EightNeighbors` is refused). Clone it or reference it:
+
+```neo
+class Sprinkler : NeoObject {
+  public NeoCellPattern Reach = NeoCellPattern.EightNeighbors.Clone();
+  public Reference<NeoCellPattern> Splash = NeoCellPattern.Center;
+}
+```
+
+In C#, `NeoCellPattern` implements `INeoCellPattern`
+(`IReadOnlyList<Vector2Int>`), which SDK grid helpers accept. The exclusion
+argument is `NeoCellPatternExcluding.None` or `.Center`.
+
+## Grid queries
+
+On a placed `NeoObject`:
+
+- `this.Cell` is its grid cell.
+- `this.GetObjects<Plant>(pattern)` returns placed objects in the same grid
+  that are `Plant` or a subclass.
+- `this.GetTile(pattern)` returns the first tile in pattern order, or null.
+- `this.GetTiles(pattern)` returns the tile at each occupied cell in pattern
+  order. `GetTiles<DirtDryTile>(pattern)` filters each cell's top tile and
+  skips cells whose top tile differs, even with a dry tile underneath.
+- Each query takes an optional `offset` that shifts the whole pattern:
+  `this.GetTiles(neighbors, new(0, 2))`.
+- Queries track empty cells too, so getters update when a neighbor appears.
+  Calling them on an unplaced object is an error.
+
+`this.GetArea()` works on any `NeoObjectBase` or `NeoTile` and returns the
+nearest owning `NeoTileGrid`, or null. Sprite children, objects held in
+another object's field, and tiles in nested layer links answer with their
+placed root's grid. `this.GetArea<FarmGrid>()` is null in any other grid. It
+sees spawns, moves, and removals made earlier in the same evaluation.

package/skills/neocompose-cli/references/world/variants.md

@@ -0,0 +1,112 @@
+# Object variants
+
+A variant is a named configuration of one `NeoObject`-derived class: how to
+construct a fresh instance and how to move an existing one into the
+configuration. Variants are records parented to their class, not values in
+it.
+
+```neo
+// Variants/ExampleObject.neo
+@id("5f0c2b9e-7d41-4a58-9b1a-3f6f0e2d8c11")
+NeoVariant<ExampleObject> Down = new(
+  initialize: () => { return new ExampleObject(.Down); },
+  apply: (source) => { source.FacingDir = .Down; },
+  overrides: new { Name = "Facing down" },
+);
+```
+
+- `initialize` is required, takes no parameters, and returns the class.
+- `apply` takes one parameter of the class and is void. Omit it for a
+  construct-only variant.
+- Both are ordinary closures with block or expression bodies:
+  `() => new ExampleObject(.Down)`, `(source) => source.FacingDir = .Down`.
+  Each has its own scope. The server compiles them.
+- `overrides` and child overrides' `overrides` are `Partial<T>` deltas,
+  written `new { ... }` or `new Partial<T> { ... }`. They never pass
+  constructor arguments, even when `T` has a required constructor.
+
+A nested class partial changes only named members. A list override replaces
+the whole list; it does not patch entries by index. In particular, overriding
+a clip's `Frames` requires the complete desired list, not just the changed
+frame. For editing an existing clip, see [frame overrides](animation.md).
+
+## Applying
+
+- `Variants.X.Initialize()` runs `initialize`, then overrides and child
+  overrides.
+- `obj.ToVariant(X)` runs `apply`, then overrides and child overrides, never
+  `initialize`.
+- An instance remembers the variant that built it and the one last applied.
+  The applied variant's overrides win where they answer, `apply` writes stay
+  as instance overrides, and `ToVariant(Base)` removes the applied layer.
+- On an object nested inside another instance's construction, `ToVariant`
+  applies in place and records nothing.
+- Selections compare equal when class, variant, and bound lookup row match.
+  An unset optional selection differs from `Base`.
+
+## Folders
+
+```neo
+// Variants/ExampleObject/Inverted.neo
+@id("b7d2e9f0-3c15-4a68-8b24-9e0f1a2c3d44")
+NeoVariantFolder<ExampleObject> Inverted = new("Inverted");
+
+@id("e3b9c0d1-4a26-4f81-92e7-6b5a4c3d2e66")
+@settings(folder: Inverted)
+NeoVariant<ExampleObject> Down = new(
+  initialize: () => { return new ExampleObject(.Down); },
+);
+```
+
+Nest with `/` in the path; intermediate segments are implicit
+(`new("Trees/Oak")` needs no `Trees` record).
+
+Rules push and the language service enforce:
+
+- A variant or folder belongs to its type argument's class; a variant may use
+  only its own class's folders.
+- Variant names and folder segments share one static scope per folder and
+  are unique case-insensitively. Different classes may reuse names.
+- `Base` is reserved case-insensitively; `<Class>.Variants.Base` is the class
+  with no variant.
+- Names must survive C# identifier normalization.
+
+Push accepts variants in any `.neo` file. Pull writes
+`Variants/<Class>.neo` and `Variants/<Class>/<Folder path>.neo`, one file per
+class and folder, folder record first and variants by name.
+
+## Lookup folders
+
+A lookup folder binds one concrete list and offers the same variants for each
+row. The second type argument is the entry class. An empty path binds the
+class root.
+
+```neo
+@id("18b93b80-5733-4747-bf5f-3609336e4f17")
+NeoLookupVariantFolder<ExampleObject, NeoSortingLayer> Root = new(
+  path: "",
+  collection: Assets.SortingLayers,
+  collectionValue: Reference(root.Assets.SortingLayers),
+);
+
+@id("736dddf8-2881-47e1-a1d3-55fb65ea9f2a")
+@settings(folder: Root)
+NeoLookupVariant<ExampleObject, NeoSortingLayer> Layered = new(
+  initialize: (value) => { return new ExampleObject(); },
+);
+```
+
+- `collection` names the eligible list member; `collectionValue` the stored
+  list whose rows it enumerates. Prefer the `Reference(root...)` form pull
+  emits.
+- Lookup `initialize` receives the row; lookup `apply` receives the object,
+  then the row.
+- A `NeoLookupVariant<TObject, TValue>` member holds an unbound handle. A
+  plain `NeoVariant<TObject>` member may pick one row with
+  `.Bind(Reference(...))`; never bind a row to the lookup-handle type.
+
+## Type restrictions
+
+`NeoVariantFolder` and `NeoLookupVariantFolder` are top-level records, never
+member or parameter types. Variant handles are valid as Variant members only,
+not as collection entries, lookup targets, parameters, or generic bindings.

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

@@ -0,0 +1,105 @@
+# World objects
+
+Objects, tiles, sorting, and structured leaf values. Open a leaf from
+[References](#references) for grid queries, variants, or animation.
+
+## Contracts
+
+Extend visible system world classes with ordinary project classes and
+overrides. Never copy `@system` into project source. A layer link is a
+concrete project subclass of `NeoTileLayerLink` or `NeoObjectLayerLink` that
+resolves exactly one `targetLayer` relation; add no value-level target
+metadata and don't ask painting operations to create or repair relation
+targets.
+
+## Tiles
+
+A placement is a concrete `NeoTile` value with a `Cell`, listed directly in a
+layer link's `Tiles`:
+
+```neo
+new GlassFloorTile { Cell = new(9, -4) }
+```
+
+- `Name`, `Sprite`, and `SmartTile` are class-level `readonly` members; tiles
+  render per class, so override them on a subclass. Push rejects placements
+  that set them. `Cell` is the writable field.
+- `tile.TryConvert<GlassFloorTile>()` or `tile.TryConvert(nextTile)` changes a
+  writable placement's class, keeping its row and cell. The second form uses
+  the value's runtime class without copying fields. Both return `false` when
+  placement validation (grid imports, compatible-layer relations) rejects it.
+- `Tiles.Add` and `Tiles.Remove` edit placement data directly; the SDK
+  validates and re-renders from the data changes. Flattened SDK layers also
+  have `TrySetTile<T>(cell)`.
+
+## Objects
+
+- `PlacementTiles` is a `List<NeoPlacementTile>`, each marking a footprint
+  cell with its own `Cell`. It is not `NeoTile`; rendered tile classes don't
+  belong there. An object with no placement tiles occupies no cells, blocks
+  nothing, and isn't returned by cell queries, but still has a `Cell`.
+- Spawn with `TrySpawn(cell, constructedObject)`; adoption keeps the object's
+  identity. Clone an owned object explicitly before placing another copy.
+- `NeoSpriteObject` extends `NeoObject`. Place it like any object, give it
+  `Children`, and override `OnObjectSpawned`/`OnObjectDespawned`. Spawn hooks
+  run parent first, despawn children first. `NeoObjectBehaviour.IsRoot` is
+  true only on the placed root.
+- Painting a different class replaces the placement with a new row. To change
+  configuration in place, use [variants](variants.md).
+- Authored placements may carry variant and source metadata beside their
+  schema keys. Keep it when editing and never declare it as schema fields.
+  Tile placements carry only their class and `Cell`.
+
+## Sorting and optional children
+
+```neo
+class Tree : NeoObject {
+  public virtual NeoSortingGroup? SortingGroup = null;
+}
+```
+
+- A non-null `NeoSortingGroup` makes the object and descendants sort as one
+  unit. `SortAtRoot` hoists a nested group to the scene root. `SortPoint` is
+  the Y-sort point in cells from the origin cell's corner (default
+  `(0.5, 0)`, bottom center); moving it never moves art. Set it per class,
+  variant, or frame.
+- Order: sorting layer, order in layer, sort-point Y (lower draws in front),
+  then document order. `NeoSpriteObject.SortingOrder` is an offset added to
+  the layer order, not a replacement. Sprites also expose `FlipX`, `FlipY`,
+  and `MaskInteraction`.
+- `NeoObjectBase.Enabled = false` hides an object and its subtree without
+  removing its `Children` row: no rendering or collision, but values and
+  animation keep running. Runtime structural children aren't supported, so
+  author known optional slots and toggle `Enabled`.
+
+## Structured leaves
+
+Addressable fields: `SpriteInfo.FileId` and `SliceIndex` (PascalCase), vector
+components `x`, `y`, `z`, `w` where the type has them, and Color `r`, `g`,
+`b`, `a` (lowercase).
+
+```neo
+Sprite = Images.Hero.Slice(0);
+Placeholder = SpriteInfo.Empty;
+Position = new(0, 0, 0);
+Tint = Color(1, 1, 1, 1);
+
+Leg.Sprite.SliceIndex = 2;   // in NeoScript, when storage permits
+Leg.Position.y = 0.25;
+```
+
+- Use `.Slice(index)` for a complete `SpriteInfo`. `SpriteInfo.Empty` is the
+  canonical non-null empty sprite (no file, slice zero); use `null` only for
+  `SpriteInfo?`.
+- Field writes are read-modify-write of the whole leaf. Unknown fields,
+  missing vector components, non-integer values on int vectors, and color
+  channels outside [0, 1] are rejected.
+
+## References
+
+- [Grids and cell patterns](grids-and-cell-patterns.md): `NeoCellPattern`,
+  `GetObjects`, `GetTile(s)`, `GetArea`.
+- [Variants](variants.md): `NeoVariant`, folders, lookup variants,
+  `Initialize`/`ToVariant`.
+- [Animation](animation.md): partial overrides, child selectors, segments,
+  tracks, animated colliders.