@arancini/systems - npm Package Compare versions

Comparing version 6.3.2 to 6.4.0

dist/executor.d.ts

@@ -1,2 +0,2 @@
-import { AnyEntity, Query, QueryDescription, World } from '@arancini/core';
+import { AnyEntity, Query, QueryFn, World } from '@arancini/core';
 import { System, SystemAttributes, SystemClass, SystemQueryOptions } from './system';
@@ -49,2 +49,2 @@ export declare class Executor<E extends AnyEntity> {
 }
-export declare const createSystemQuery: <Entity extends AnyEntity, ResultEntity extends Entity>(world: World<Entity>, system: System<Entity>, queryDescription: QueryDescription<Entity, ResultEntity>, options?: SystemQueryOptions) => Query<ResultEntity>;
+export declare const createSystemQuery: <Entity extends AnyEntity, ResultEntity extends Entity>(world: World<Entity>, system: System<Entity>, queryFn: QueryFn<Entity, ResultEntity>, options?: SystemQueryOptions) => Query<ResultEntity>;

dist/system.d.ts

@@ -1,2 +0,2 @@
-import type { AnyEntity, Query, QueryDescription, World } from '@arancini/core';
+import type { AnyEntity, Query, QueryFn, World } from '@arancini/core';
 import { Executor } from './executor';
@@ -103,7 +103,7 @@ export type SystemQueryOptions = {
      * Creates and returns a query that gets updated every update.
-     * @param queryDescription the query description
+     * @param queryFn the query function
      * @param options optional options for the system query
      * @returns the query
      */
-    protected query<ResultEntity extends E>(queryDescription: QueryDescription<E, ResultEntity>, options?: SystemQueryOptions): Query<ResultEntity>;
+    protected query<ResultEntity extends E>(queryFn: QueryFn<E, ResultEntity>, options?: SystemQueryOptions): Query<ResultEntity>;
     /**
@@ -110,0 +110,0 @@ * Shortcut for creating a query for a singleton component.

package.json

@@ -12,3 +12,3 @@ {
   "license": "MIT",
-  "version": "6.3.2",
+  "version": "6.4.0",
   "homepage": "https://github.com/isaac-mason/arancini",
@@ -26,3 +26,3 @@ "bugs": {
   "dependencies": {
-    "@arancini/core": "6.3.2"
+    "@arancini/core": "6.4.0"
   },
@@ -29,0 +29,0 @@ "devDependencies": {

README.md

 # @arancini/systems
 
-Systems for arancini.
+Systems helpers for arancini.
 
-See the [**arancini** README](https://github.com/isaac-mason/arancini/tree/main/packages/arancini) for more information.
+## Installation
+
+@arancini/systems can either be used via the umbrella package `arancini`, or installed separately.
+
+```bash
+> npm install @arancini/systems
+```
+
+## Introduction
+
+In `arancini/systems`, systems are classes that extend `System`. Systems are added to an `Executor`, and are updated when calling `executor.update()`.
+
+```ts
+import { World } from "arancini";
+import { Executor, System } from "arancini/systems";
+
+type Entity = {
+  position?: { x: number; y: number };
+  velocity?: { x: number; y: number };
+};
+
+// Create a World
+const world = new World<Entity>();
+
+// Create an Executor
+const executor = new Executor(world);
+
+// Define a System
+class MovementSystem extends System<Entity> {
+  moving = this.query((e) => e.has("position", "velocity"));
+
+  onUpdate(delta: number, time: number) {
+    for (const entity of this.moving) {
+      const position = entity.get("position");
+      const velocity = entity.get("velocity");
+
+      position.x += velocity.x;
+      position.y += velocity.y;
+    }
+  }
+
+  onInit() {
+    // Called when the Executor is initialised, or when the system is added to an already initialised Executor
+  }
+
+  onDestroy() {
+    // Called when the Executor is destroyed, or the system is removed
+  }
+}
+
+// Add the system to the executor
+executor.add(MovementSystem);
+
+// Initialise the executor
+executor.init();
+
+// Update all systems, optionally passing a delta time
+executor.update(1 / 60);
+
+// Destroy the executor
+executor.destroy();
+```
+
+#### System priority
+
+Systems can be added with a priority. The order systems run in is first determined by priority, then by the order systems were added.
+
+```ts
+executor.add(MovementSystem, { priority: 10 });
+```
+
+#### Required system queries
+
+If a system should only run when a query has results, you can mark the query as required. Then, `onUpdate` will only be called if the query has at least one result.
+
+> **Note:** `onInit` and `onDestroy` will be called regardless of whether required queries have results.
+
+```ts
+class ExampleSystem extends System<Entity> {
+  requiredQuery = this.query((e) => e.has("position"), { required: true });
+
+  onUpdate() {
+    // we can safely assume that the query has at least one result
+    const { x, y } = this.requiredQuery.first;
+  }
+}
+```
+
+#### Singleton Queries
+
+The `this.singleton` utility method creates a query for a single component, and sets the property to the given component on the first matching entity.
+
+```ts
+class CameraRigSystem extends System<Entity> {
+  camera = this.singleton("camera", { required: true });
+
+  onUpdate() {
+    console.log(camera);
+  }
+}
+```
+
+> **Note:** Singleton components must be defined on a top-level property of the system. The property must not be a ES2022 private field (prefixed with `#`).
+
+#### Attaching systems to other systems
+
+Systems can be attached to other systems with `this.attach`. This is useful for sharing logic or system state that doesn't belong in a component.
+
+```ts
+class ExampleSystem extends System<Entity> {
+  otherSystem = this.attach(OtherSystem);
+
+  onInit() {
+    this.otherSystem.foo();
+  }
+}
+```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

31241

increased by9.83%

Number of lines in readme file

121

increased by2320%

Dependency changes

• + Added@arancini/core@6.4.0(transitive)

• + Added@arancini/events@6.4.0(transitive)

• - Removed@arancini/core@6.3.2(transitive)

• - Removed@arancini/events@6.3.2(transitive)

• Updated@arancini/core@6.4.0