@vworlds/vecs 1.0.15 → 1.0.16

package/dist/query/query.d.ts

@@ -0,0 +1,53 @@
+import { type ComponentType } from "../component.js";
+import { type World } from "../world/index.js";
+import { Group } from "./query.07.groups.js";
+import { Groups } from "./query.07.groups.js";
+/**
+ * A reactive, always-up-to-date set of entities matching a {@link QueryDSL}
+ * predicate.
+ *
+ * `Query` listens to entity / component mutations through the world's command
+ * queue and tracks which entities currently satisfy its predicate. It fires
+ * `enter`, `exit`, and `update` callbacks as the matched set changes. The
+ * tracked set is exposed via {@link count}, {@link has}, iteration, and
+ * {@link forEach}.
+ *
+ * Callbacks fire **synchronously** when the world routes a command — so
+ * mutations made inside one of these callbacks are themselves observed
+ * immediately by other queries / systems.
+ *
+ * {@link System} extends `Query` and queues callbacks into an inbox replayed
+ * during `_run` instead of firing them immediately. Use `Query` directly when
+ * you want a reactive entity set without pipeline integration.
+ *
+ * @typeParam R - Component classes guaranteed present on every matched entity
+ *   (declared via {@link requires} or the `_guaranteed` hint of {@link query}).
+ *   Components in `R` appear as non-nullable in {@link sort}, {@link forEach},
+ *   and {@link update} callback tuples.
+ */
+export declare class Query<R extends ComponentType[] = []> extends Groups<R> {
+    constructor(name: string, world: World, track?: boolean);
+}
+/**
+ * A {@link Query} that has been partitioned by {@link Query.groupBy}. Adds the
+ * typed group-accessor surface ({@link group}, {@link groups}, etc.) on top of
+ * the query's usual reactive membership.
+ *
+ * `GroupedQuery` lives in the query module alongside `Query`. Instances are
+ * created lazily by {@link Query.groupBy} via `Object.setPrototypeOf`.
+ *
+ * @typeParam K - The grouping key type produced by the key function (or the
+ *   relationship target entity, for the relationship form).
+ * @typeParam R - Component classes guaranteed present on every matched entity.
+ */
+export declare class GroupedQuery<K = unknown, R extends ComponentType[] = []> extends Query<R> {
+    private _grouping;
+    group(key: K): Group<K, R> | undefined;
+    groups(): IterableIterator<Group<K, R>>;
+    groupKeys(): IterableIterator<K>;
+    get groupCount(): number;
+    onGroupEnter(callback: (group: Group<K, R>) => void): this;
+    onGroupExit(callback: (key: K, group: Group<K, R>) => void): this;
+    private _composeGroupMembership;
+    destroy(): void;
+}

package/dist/query/query.js

@@ -0,0 +1,138 @@
+import { _resolveRelationship } from "../dsl.js";
+import { Entity } from "../entity/index.js";
+import { directInjectEids, getInjected, injectArity, mapInject, } from "../inject.js";
+import { _setGroupedQueryCtor } from "./query.00.base.js";
+import { Grouping } from "./query.07.groups.js";
+import { Groups } from "./query.07.groups.js";
+/**
+ * A reactive, always-up-to-date set of entities matching a {@link QueryDSL}
+ * predicate.
+ *
+ * `Query` listens to entity / component mutations through the world's command
+ * queue and tracks which entities currently satisfy its predicate. It fires
+ * `enter`, `exit`, and `update` callbacks as the matched set changes. The
+ * tracked set is exposed via {@link count}, {@link has}, iteration, and
+ * {@link forEach}.
+ *
+ * Callbacks fire **synchronously** when the world routes a command — so
+ * mutations made inside one of these callbacks are themselves observed
+ * immediately by other queries / systems.
+ *
+ * {@link System} extends `Query` and queues callbacks into an inbox replayed
+ * during `_run` instead of firing them immediately. Use `Query` directly when
+ * you want a reactive entity set without pipeline integration.
+ *
+ * @typeParam R - Component classes guaranteed present on every matched entity
+ *   (declared via {@link requires} or the `_guaranteed` hint of {@link query}).
+ *   Components in `R` appear as non-nullable in {@link sort}, {@link forEach},
+ *   and {@link update} callback tuples.
+ */
+export class Query extends Groups {
+    constructor(name, world, track = true) {
+        super(name, world, Query, track);
+    }
+}
+const EMPTY_GROUPS = new Map();
+/**
+ * A {@link Query} that has been partitioned by {@link Query.groupBy}. Adds the
+ * typed group-accessor surface ({@link group}, {@link groups}, etc.) on top of
+ * the query's usual reactive membership.
+ *
+ * `GroupedQuery` lives in the query module alongside `Query`. Instances are
+ * created lazily by {@link Query.groupBy} via `Object.setPrototypeOf`.
+ *
+ * @typeParam K - The grouping key type produced by the key function (or the
+ *   relationship target entity, for the relationship form).
+ * @typeParam R - Component classes guaranteed present on every matched entity.
+ */
+export class GroupedQuery extends Query {
+    /** @internal */
+    _initialize(arg0, arg1) {
+        if (this._grouping !== undefined) {
+            throw `query '${this.name}' is already grouped`;
+        }
+        let keyOf;
+        let watchEids;
+        if (typeof arg1 === "function") {
+            const components = arg0;
+            const inject = mapInject(this.world, components);
+            const arity = injectArity(inject);
+            const resolved = new Array(arity);
+            keyOf = (e) => {
+                getInjected(e, inject, false, resolved);
+                return arg1(e, resolved);
+            };
+            watchEids = directInjectEids(inject);
+            this._composeGroupMembership(components);
+        }
+        else {
+            const relEid = _resolveRelationship(arg0, this.world);
+            keyOf = (e) => e.parent(relEid);
+            watchEids = [relEid];
+            this._composeGroupMembership([arg0]);
+        }
+        for (const eid of watchEids) {
+            this._watchlistBitmask.add(eid);
+        }
+        this.track();
+        this._grouping = new Grouping(this.world, keyOf, watchEids);
+        return this;
+    }
+    /** @internal */
+    _enter(e) {
+        this._grouping.enter(e);
+        super._enter(e);
+    }
+    /** @internal */
+    _exit(e) {
+        super._exit(e);
+        this._grouping.exit(e);
+    }
+    /** @internal */
+    _notifyModified(e, meta, c) {
+        super._notifyModified(e, meta, c);
+        this._grouping.refresh(e, meta.eid);
+    }
+    /** @internal */
+    _watchesUpdates() {
+        return super._watchesUpdates() || true;
+    }
+    group(key) {
+        return this._grouping?.get(key);
+    }
+    groups() {
+        return (this._grouping?.groups.values() ?? EMPTY_GROUPS.values());
+    }
+    groupKeys() {
+        return (this._grouping?.keys() ?? EMPTY_GROUPS.keys());
+    }
+    get groupCount() {
+        return this._grouping?.groups.size ?? 0;
+    }
+    onGroupEnter(callback) {
+        this._assertConfigurable();
+        this._grouping?.setOnGroupEnter(callback);
+        return this;
+    }
+    onGroupExit(callback) {
+        this._assertConfigurable();
+        this._grouping?.setOnGroupExit(callback);
+        return this;
+    }
+    _composeGroupMembership(refs) {
+        const componentRefs = refs.filter((ref) => typeof ref === "number" || typeof ref === "function" || ref instanceof Entity);
+        if (componentRefs.length === 0) {
+            return;
+        }
+        const existing = this._dsl ?? true;
+        this._dsl = { all: [existing, ...componentRefs] };
+        this._hasExplicitQuery = true;
+    }
+    destroy() {
+        this._grouping?.clear();
+        this._grouping = undefined;
+        super.destroy();
+    }
+}
+_setGroupedQueryCtor(GroupedQuery);
+//# sourceMappingURL=query.js.map

package/dist/query/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/query/query.ts"],"names":[],"mappings":"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"}

package/dist/relationship.d.ts

@@ -0,0 +1,19 @@
+import type { Entity } from "./entity/index.js";
+/** Base class for relationship components that point at another entity. */
+export declare abstract class Relationship {
+    target: Entity;
+}
+/** Built-in parent-child relationship. */
+export declare class ChildOf extends Relationship {
+}
+/**
+ * Built-in relationship marking a feedback **silence domain** for a query
+ * or system.
+ *
+ * When a query carries a `SilenceSource` pointing at a query entity, it
+ * ignores `update` notifications whose originating entity (the system
+ * that wrote the component) is a member of that query. Configure it through
+ * {@link Query.ignoreSource}.
+ */
+export declare class SilenceSource extends Relationship {
+}

package/dist/relationship.js

@@ -0,0 +1,18 @@
+/** Base class for relationship components that point at another entity. */
+export class Relationship {
+}
+/** Built-in parent-child relationship. */
+export class ChildOf extends Relationship {
+}
+/**
+ * Built-in relationship marking a feedback **silence domain** for a query
+ * or system.
+ *
+ * When a query carries a `SilenceSource` pointing at a query entity, it
+ * ignores `update` notifications whose originating entity (the system
+ * that wrote the component) is a member of that query. Configure it through
+ * {@link Query.ignoreSource}.
+ */
+export class SilenceSource extends Relationship {
+}
+//# sourceMappingURL=relationship.js.map

package/dist/relationship.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship.js","sourceRoot":"","sources":["../src/relationship.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,MAAM,OAAgB,YAAY;CAEjC;AAED,0CAA0C;AAC1C,MAAM,OAAO,OAAQ,SAAQ,YAAY;CAAG;AAE5C;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAc,SAAQ,YAAY;CAAG"}

package/dist/system.d.ts

@@ -1,9 +1,10 @@
-import { type ComponentClass } from "./component.js";
-import { Query } from "./query.js";
-import { type QueryDSL, type MaybeRequired } from "./dsl.js";
-import type { Entity } from "./entity.js";
+import { type ComponentType } from "./component.js";
+import { Iter, type FanInjectTuple, type MaybeResolvedInjectTuple } from "./inject.js";
+import { Query } from "./query/index.js";
+import { type QueryDSL } from "./dsl.js";
+import { Entity } from "./entity/index.js";
 import { type IPhase } from "./phase.js";
-import { type World } from "./world.js";
+import { type World } from "./world/index.js";
 import { type ITickSource } from "./timer.js";
 export type { QueryDSL as SystemQuery, EntityTestFunc } from "./dsl.js";
 type RunCallback = (now: number, delta: number) => void;
@@ -34,8 +35,7 @@ type RunCallback = (now: number, delta: number) => void;
  *
  * `enter`, `exit`, `update`, `each`, and `sort` accept an array of component
  * classes resolved from the entity and passed as a typed tuple to the
- * callback. Use `{ parent: SomeComponent }` to resolve from the entity's
- * parent instead of the entity itself.
+ * callback.
  *
  * Components declared via {@link requires} (or the `_guaranteed` argument of
  * {@link query}) are tracked as the type parameter `R`. Inside `sort`,
@@ -44,7 +44,7 @@ type RunCallback = (now: number, delta: number) => void;
  *
  * @typeParam R - Component classes guaranteed present on every matched entity.
  */
-export declare class System<R extends ComponentClass[] = []> extends Query<R> implements ITickSource {
+export declare class System<R extends ComponentType[] = []> extends Query<R> implements ITickSource {
     constructor(name: string, world: World);
     /** True when this system's cadence source fired during the current frame. */
     get didTick(): boolean;
@@ -151,11 +151,16 @@ export declare class System<R extends ComponentClass[] = []> extends Query<R> im
      *
      * `each` does **not** modify the system's query — define membership with
      * {@link requires} or {@link query} as usual. It does, however, implicitly
-     * enable {@link track}, so matched entities are exposed via {@link entities}.
+     * enable {@link track}, so matched entities are exposed via {@link count},
+     * {@link has}, iteration, and {@link forEach}.
      *
      * Only one `each` callback may be registered per system; calling `each` a
      * second time throws.
      *
+     * The resolved tuple is a single array reused for every entity each tick;
+     * treat it as valid only for the duration of the callback. The component
+     * instances it holds are stable — do not retain the tuple array itself.
+     *
      * @param components - Component classes to resolve from each entity.
      * @param callback - Receives the entity and a tuple of resolved component
      *   instances (`undefined` for any not covered by {@link requires}).
@@ -172,9 +177,20 @@ export declare class System<R extends ComponentClass[] = []> extends Query<R> im
      *   });
      * ```
      */
-    each<J extends ComponentClass[]>(components: readonly [...J], callback: (e: Entity, resolved: {
-        [K in keyof J]: MaybeRequired<J[K], R>;
-    }) => void): this;
+    each<J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    /**
+     * As above, but pass `Entity` first to make the entity-first signature
+     * explicit. Identical behavior to the no-marker form.
+     */
+    each<J extends FanInjectTuple>(cursor: typeof Entity, components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
+    /**
+     * As above, but pass `Iter` first to receive a reused {@link Iter}
+     * cursor instead of the bare entity. The cursor exposes the visited entity
+     * (`it.entity`) and, in `it.src`, the source entity each resolved component
+     * was read from (the visited entity for direct components, the relationship
+     * target for `up`-injected ones).
+     */
+    each<J extends FanInjectTuple>(cursor: typeof Iter, components: readonly [...J], callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): this;
     /**
      * Set the entity-membership predicate using a {@link QueryDSL} expression.
      *
@@ -190,19 +206,23 @@ export declare class System<R extends ComponentClass[] = []> extends Query<R> im
      *   entity (type hint only — not validated at runtime).
      * @returns This system, retyped with the guaranteed tuple as its `R`.
      */
-    query<T extends ComponentClass[] = []>(q: QueryDSL, _guaranteed?: readonly [...T]): System<T>;
+    query<T extends ComponentType[] = []>(q: QueryDSL, _guaranteed?: readonly [...T]): System<T>;
     /**
      * Shorthand for `query([...components])` — tracks entities that have **all**
      * of the listed component types.
      *
-     * Equivalent to `query({ HAS: components })`. The listed components are also
+     * Equivalent to `query(components)`. The listed components are also
      * recorded in the type parameter `R`, so {@link sort}, {@link each}, and
      * {@link update} callbacks treat them as non-nullable.
      *
      * @param components - Component classes to require.
      * @returns This system, retyped with the required tuple as its `R`.
      */
-    requires<T extends ComponentClass[]>(...components: [...T]): System<T>;
+    requires<T extends ComponentType[]>(...components: [...T]): System<T>;
+    /**
+     * Systems cannot use groupBy. Use `world.query(...).groupBy(...)` instead.
+     */
+    groupBy(..._args: any[]): never;
     /**
      * Disable this system.
      *
@@ -245,12 +265,6 @@ export declare class System<R extends ComponentClass[] = []> extends Query<R> im
      * @returns This system, for chaining.
      */
     enable(): this;
-    /**
-     * Not supported on `System`. Throws unconditionally.
-     *
-     * Systems are owned by the world for the duration of the session; if you
-     * need a temporary reactive set use a standalone {@link Query} via
-     * {@link World.query}.
-     */
-    destroy(): never;
+    /** Permanently remove this system from the world. */
+    destroy(): void;
 }

package/dist/system.js

@@ -1,4 +1,6 @@
-import { Query } from "./query.js";
+import { isCursorMarker, makeInjectedInvoker, wantsIter, } from "./inject.js";
+import { SOURCE_TRACKED_QUERY_ERROR, Query } from "./query/index.js";
+import { containsDownTerm } from "./dsl.js";
 import { Phase } from "./phase.js";
 import { ALWAYS_TICK_SOURCE, IntervalTickSource, RateTickSource, } from "./timer.js";
 /**
@@ -28,8 +30,7 @@ import { ALWAYS_TICK_SOURCE, IntervalTickSource, RateTickSource, } from "./timer
  *
  * `enter`, `exit`, `update`, `each`, and `sort` accept an array of component
  * classes resolved from the entity and passed as a typed tuple to the
- * callback. Use `{ parent: SomeComponent }` to resolve from the entity's
- * parent instead of the entity itself.
+ * callback.
  *
  * Components declared via {@link requires} (or the `_guaranteed` argument of
  * {@link query}) are tracked as the type parameter `R`. Inside `sort`,
@@ -47,12 +48,28 @@ export class System extends Query {
         this._enabled = true;
         /** @internal Cadence source for this system. Defaults to every frame. */
         this._tickSource = ALWAYS_TICK_SOURCE;
+        this.entity.attach(System, this);
+    }
+    /** @internal Reject non-reactive source/children terms before registering this system. */
+    _build() {
+        if (this._dsl !== undefined && containsDownTerm(this._dsl)) {
+            this.destroy();
+            throw new Error(SOURCE_TRACKED_QUERY_ERROR);
+        }
+        return super._build();
+    }
+    /** @internal Systems may be run-only processors without entity membership. */
+    _isBuildable() {
+        return true;
     }
     /**
      * @internal Routing entry: register query membership for `e`, push an
      * inbox `enter` event when an `enter` callback is registered, and bridge
      * watched components through {@link _notifyModified} to surface them as
      * inbox `update` events on entry.
+     *
+     * Target relationship reactivity is handled by `TargetTerm`; systems only
+     * translate root-term membership events into inbox commands here.
      */
     _enter(e) {
         this._entities?.add(e);
@@ -63,10 +80,12 @@ export class System extends Query {
         if (this._enterCallback !== undefined) {
             this._inbox.push({ kind: 0 /* InboxCommand.Enter */, entity: e });
         }
-        e.components.forEach((c, type) => {
-            const meta = this.world.getComponentMeta(type);
+        e.components.forEach((c, eid) => {
+            const meta = this.world.entity(eid).ownMeta;
             if (this._watchlistBitmask.hasBit(meta.bitPtr)) {
-                this._notifyModified(e, meta, c);
+                // Entry-time initialization bypasses the silence filter: an entity
+                // introduced by an ignored source must still initialize in this system.
+                this._pushUpdate(e, meta, c);
             }
         });
     }
@@ -86,10 +105,10 @@ export class System extends Query {
             let snapshot;
             if (this._exitSnapshotTypes && this._exitSnapshotTypes.length > 0) {
                 snapshot = new Map();
-                for (const type of this._exitSnapshotTypes) {
-                    const c = e._get(type);
+                for (const eid of this._exitSnapshotTypes) {
+                    const c = e._get(eid);
                     if (c) {
-                        snapshot.set(type, c);
+                        snapshot.set(eid, c);
                     }
                 }
             }
@@ -98,12 +117,22 @@ export class System extends Query {
     }
     /**
      * @internal Routing entry: push an inbox `update` event when the modified
-     * component matches the watchlist.
+     * component matches the watchlist and its source is not silenced.
      */
     _notifyModified(e, meta, c) {
-        if (!this._enabled || !this._watchlistBitmask.hasBit(meta.bitPtr)) {
+        if (!this._watchlistBitmask.hasBit(meta.bitPtr)) {
+            return;
+        }
+        if (!this._enabled) {
+            return;
+        }
+        if (this._isSourceSilenced()) {
             return;
         }
+        this._pushUpdate(e, meta, c);
+    }
+    /** @internal Append an `update` event to the inbox, bypassing the silence filter. */
+    _pushUpdate(e, meta, c) {
         this._inbox.push({ kind: 2 /* InboxCommand.Update */, entity: e, meta, component: c });
     }
     /**
@@ -121,6 +150,20 @@ export class System extends Query {
             return;
         }
         const tickDelta = this._tickSource.lastFireDelta;
+        const prevSource = this.world._currentSource;
+        this.world._currentSource = this.entity;
+        try {
+            this._runDeferred(now, tickDelta);
+        }
+        finally {
+            this.world._currentSource = prevSource;
+        }
+    }
+    /**
+     * @internal Drain the inbox and fire callbacks inside a deferred scope, with
+     * this system credited as the source of any mutations made by callbacks.
+     */
+    _runDeferred(now, tickDelta) {
         this.world.defer(() => {
             for (let i = 0; i < this._inbox.length; i++) {
                 const event = this._inbox[i];
@@ -132,7 +175,7 @@ export class System extends Query {
                         this._exitCallback(event.entity, event.snapshot);
                         break;
                     case 2 /* InboxCommand.Update */:
-                        const callback = this._componentUpdateCallbacks.get(event.meta.type);
+                        const callback = this._componentUpdateCallbacks.get(event.meta.eid);
                         if (callback) {
                             callback(event.entity, event.component);
                         }
@@ -144,8 +187,7 @@ export class System extends Query {
                 this._runCallback(now, tickDelta);
             }
             if (this._eachCallback) {
-                const cb = this._eachCallback;
-                this.forEach((e) => cb(e));
+                this.forEach(this._eachCallback);
             }
         });
     }
@@ -187,10 +229,12 @@ export class System extends Query {
      * ```
      */
     interval(seconds) {
+        this._assertConfigurable();
         this._setTickSource(new IntervalTickSource(seconds));
         return this;
     }
     rate(n, source) {
+        this._assertConfigurable();
         this._setTickSource(new RateTickSource(n, source ?? this._tickSource));
         return this;
     }
@@ -212,6 +256,7 @@ export class System extends Query {
      * ```
      */
     tickSource(source) {
+        this._assertConfigurable();
         this._setTickSource(source);
         return this;
     }
@@ -232,12 +277,13 @@ export class System extends Query {
      *   different world.
      */
     phase(p) {
+        this._assertConfigurable();
         if (typeof p !== "string") {
             if (!(p instanceof Phase)) {
-                throw "Invalid Phase object";
+                throw new Error("Invalid Phase object");
             }
             if (p.world !== this.world) {
-                throw "Phase does not belong to this system's world";
+                throw new Error("Phase does not belong to this system's world");
             }
         }
         this._phase = p;
@@ -257,51 +303,20 @@ export class System extends Query {
      * @returns This system, for chaining.
      */
     run(callback) {
+        this._assertConfigurable();
         this._runCallback = callback;
         return this;
     }
-    /**
-     * Register a callback fired **every tick** for **every tracked entity**,
-     * unconditionally, with the listed components resolved from each entity.
-     *
-     * Unlike {@link update} (which only fires when `entity.modified(C)` is
-     * called), `each` fires every tick the system runs, once per tracked entity.
-     * Components declared via {@link requires} are non-nullable in the resolved
-     * tuple; any other component class may be `undefined` if the entity lacks it.
-     *
-     * `each` does **not** modify the system's query — define membership with
-     * {@link requires} or {@link query} as usual. It does, however, implicitly
-     * enable {@link track}, so matched entities are exposed via {@link entities}.
-     *
-     * Only one `each` callback may be registered per system; calling `each` a
-     * second time throws.
-     *
-     * @param components - Component classes to resolve from each entity.
-     * @param callback - Receives the entity and a tuple of resolved component
-     *   instances (`undefined` for any not covered by {@link requires}).
-     * @returns This system, for chaining.
-     * @throws When `each` has already been registered on this system.
-     *
-     * @example
-     * ```ts
-     * world.system("Move")
-     *   .requires(Position, Velocity)
-     *   .each([Position, Velocity], (e, [pos, vel]) => {
-     *     pos.x += vel.vx;
-     *     pos.y += vel.vy;
-     *   });
-     * ```
-     */
-    each(components, callback) {
+    each(arg0, arg1, arg2) {
+        this._assertConfigurable();
         if (this._eachCallback) {
-            throw `each already registered for system '${this.name}'`;
+            throw new Error(`each already registered for system '${this.name}'`);
         }
         this.track();
-        const types = components.map((C) => this.world.getComponentType(C));
-        this._eachCallback = (e) => {
-            const resolved = types.map((t) => e.get(t));
-            callback(e, resolved);
-        };
+        const useIter = wantsIter(arg0);
+        const components = (isCursorMarker(arg0) ? arg1 : arg0);
+        const callback = (isCursorMarker(arg0) ? arg2 : arg1);
+        this._eachCallback = makeInjectedInvoker(this.world, components, useIter, callback);
         return this;
     }
     /**
@@ -327,7 +342,7 @@ export class System extends Query {
      * Shorthand for `query([...components])` — tracks entities that have **all**
      * of the listed component types.
      *
-     * Equivalent to `query({ HAS: components })`. The listed components are also
+     * Equivalent to `query(components)`. The listed components are also
      * recorded in the type parameter `R`, so {@link sort}, {@link each}, and
      * {@link update} callbacks treat them as non-nullable.
      *
@@ -338,6 +353,12 @@ export class System extends Query {
         super.requires(...components);
         return this;
     }
+    /**
+     * Systems cannot use groupBy. Use `world.query(...).groupBy(...)` instead.
+     */
+    groupBy(..._args) {
+        throw new Error("System does not support groupBy; use world.query(...).groupBy(...)");
+    }
     /**
      * Disable this system.
      *
@@ -387,15 +408,10 @@ export class System extends Query {
         this._enabled = true;
         return this;
     }
-    /**
-     * Not supported on `System`. Throws unconditionally.
-     *
-     * Systems are owned by the world for the duration of the session; if you
-     * need a temporary reactive set use a standalone {@link Query} via
-     * {@link World.query}.
-     */
+    /** Permanently remove this system from the world. */
     destroy() {
-        throw `destroy() is not supported on System '${this.name}'`;
+        this.disable();
+        super.destroy();
     }
 }
 //# sourceMappingURL=system.js.map