@arcade2d/world - npm Package Compare versions

Comparing version 0.1.3 to 0.2.0

lib/geom/vector.d.ts

@@ -1,11 +0,90 @@
-export interface VectorLike {
+export declare type VectorTuple = [number, number];
+export declare type ImmutableVectorPrimitive = {
+    readonly x: number;
+    readonly y: number;
+};
+export interface VectorPrimitive {
+    /**
+     * The horizontal value of this vector.
+     */
     x: number;
+    /**
+     * The vertical value of this vector.
+     */
     y: number;
 }
-export declare class Vector implements VectorLike {
-    x: number;
-    y: number;
+/**
+ * Normalize input arguments typically seen for an overloaded method into a
+ * tuple `[x, y]`. This helps write function overloads like the following:
+ *
+ * ```
+ * function example(x: number, y: number): void;
+ * function example(tuple: [number, number]): void;
+ * function example(vector: Vector): void;
+ *
+ * function example(a: number | [number, number] | Vector, b?: number): void {
+ *   const [x, y] = normalizeVectorArgs(a, b);
+ *
+ *   // your code
+ * }
+ * ```
+ *
+ * @param a The x value, vector primitive or vector tuple.
+ * @param b The optional y value.
+ */
+export declare function normalizeVectorArgs(a: VectorPrimitive | VectorTuple | number, b?: number): VectorTuple;
+export declare class Vector implements VectorPrimitive {
+    /**
+     * Creates a new vector from separate `x` and `y` arguments.
+     *
+     * @param x The initial `x` value.
+     * @param y The initial `y` value.
+     */
+    static from(x: number, y: number): Vector;
+    /**
+     * Creates a new vector based on the target vector.
+     *
+     * @param primitive The target vector.
+     */
+    static from(primitive: VectorPrimitive): Vector;
+    /**
+     * Creates a new vector based on the input tuple of `[x, y]`.
+     *
+     * @param tuple The input tuple.
+     */
+    static from(tuple: VectorTuple): Vector;
+    /**
+     * Creates a new vector of `0,-1`, representing an "upward facing" magnitude.
+     */
+    static up(): Vector;
+    /**
+     * Creates a new vector of `0,1`, representing a "downward facing" magnitude.
+     */
+    static down(): Vector;
+    /**
+     * Creates a new vector of `-1,0`, representing a "left facing" magnitude.
+     */
+    static left(): Vector;
+    /**
+     * Creates a new vector of `1,0`, representing a "right facing" magnitude.
+     */
+    static right(): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` values indicate a direction
+     * specified by input radians, starting from `1,0`.
+     *
+     * @param radians The angle in radians.
+     */
+    static diagonal(radians: number): Vector;
+    private _x;
+    private _y;
     constructor(x?: number, y?: number);
+    toString(): string;
     /**
-     * Update the x and y values of this vector.
+     * Creates and returns a new vector where `x` and `y` are equivalent to this
+     * origin vector.
+     */
+    clone(): Vector;
+    /**
+     * Update this vector to the input `x` and `y` values.
      *
@@ -17,8 +96,215 @@ * @param x The new x value.
     /**
-     * Update the x and y values of this vector.
+     * Update this vector to match the input tuple.
      *
-     * @param value The target vector to update to.
+     * @param tuple The target tuple.
      */
-    set(value: Vector): this;
-    private normalizeArgs;
+    set(tuple: VectorTuple): this;
+    /**
+     * Update this vector to match the target vector.
+     *
+     * @param primitive The target vector to update to.
+     */
+    set(primitive: VectorPrimitive): this;
+    /**
+     * Determine the distance between this vector and a set of separate `x` and
+     * `y` values.
+     *
+     * @param x The x value to measure distance to.
+     * @param y The y value to measure distance to.
+     */
+    distanceTo(x: number, y: number): number;
+    /**
+     * Determine the distance between this vector and a tuple `[x, y]`.
+     *
+     * @param tuple The target tuple.
+     */
+    distanceTo(tuple: VectorTuple): number;
+    /**
+     * Determine the distance between this vector and a target vector.
+     *
+     * @param primitive The target vector.
+     */
+    distanceTo(primitive: VectorPrimitive): number;
+    /**
+     * Determine the angle between this vector and a set of separate `x` and `y`
+     * values.
+     *
+     * @param x The x value.
+     * @param y The y value.
+     */
+    angleTo(x: number, y: number): number;
+    /**
+     * Determine the angle between this vector and a tuple `[x, y]`.
+     *
+     * @param tuple The target tuple.
+     */
+    angleTo(tuple: VectorTuple): number;
+    /**
+     * Determine the angle between this vector and a target vector.
+     *
+     * @param primitive The target vector.
+     */
+    angleTo(primitive: VectorPrimitive): number;
+    /**
+     * Returns a representation of this vector as a tuple of `[x, y]`.
+     */
+    toTuple(): VectorTuple;
+    /**
+     * Returns a representation of this vector as a primitive object of
+     * `{ x, y }`.
+     */
+    toPrimitive(): VectorPrimitive;
+    /**
+     * Returns a readonly representation of this vector as a primitive object of
+     * `{ x, y }`;
+     */
+    toImmutablePrimitive(): ImmutableVectorPrimitive;
+    /**
+     * Determine whether this vector matches the input `x` and `y` values.
+     *
+     * @param x The x value.
+     * @param y The y value.
+     */
+    equals(x: number, y: number): boolean;
+    /**
+     * Determine whether this vector matches the input tuple `[x, y]`.
+     *
+     * @param tuple The target tuple.
+     */
+    equals(tuple: VectorTuple): boolean;
+    /**
+     * Determine whether this vector matches the target vector.
+     *
+     * @param primitive The target vector.
+     */
+    equals(primitive: VectorPrimitive): boolean;
+    /**
+     * Creates a new vector where the x and y values are a product of the input
+     * value.
+     *
+     * @param value The value to multiply x and y by.
+     */
+    multiply(value: number): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` values are divided by the input
+     * value.
+     *
+     * @param value The amount to divide by.
+     */
+    divide(value: number): Vector;
+    /**
+     * Creates a new vector where `x` and `y` are increased by the input values.
+     *
+     * @param x The input x value.
+     * @param y The input y value.
+     */
+    add(x: number, y: number): Vector;
+    /**
+     * Creates a new vector where `x` and `y` are increased by the respective
+     * values in the input tuple.
+     *
+     * @param tuple The input tuple.
+     */
+    add(tuple: VectorTuple): Vector;
+    /**
+     * Creates a new vector where `x` and `y` are increased by the respective
+     * values in the input vector.
+     *
+     * @param primitive The input vector.
+     */
+    add(primitive: VectorPrimitive): Vector;
+    /**
+     * Creates a new vector where `x` and `y` are decreased by the input values.
+     *
+     * @param x The x value.
+     * @param y The y value.
+     */
+    subtract(x: number, y: number): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` are decreased by the respective
+     * values in the input tuple.
+     *
+     * @param tuple The input tuple.
+     */
+    subtract(tuple: VectorTuple): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` are decreased by the respective
+     * values in the input vector.
+     *
+     * @param primitive The input vector.
+     */
+    subtract(primitive: VectorPrimitive): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` are interpolated by `fraction`
+     * between this vector and the target `x` and `y` values.
+     *
+     * @param x The target x value.
+     * @param y The target y value.
+     * @param fraction The fraction of distance that should be interpolated. For
+     * example, 0.5 would yield a new vector that is half way between this vector
+     * and the target.
+     */
+    interpolate(x: number, y: number, fraction: number): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` are interpolated by `fraction`
+     * between this vector and the respective values in the target tuple.
+     *
+     * @param tuple The target tuple.
+     * @param fraction The fraction of distance that should be interpolated. For
+     * example, 0.5 would yield a new vector that is half way between this vector
+     * and the target.
+     */
+    interpolate(tuple: VectorTuple, fraction: number): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` are interpolated by `fraction`
+     * between this vector and the respective values in the target vector.
+     *
+     * @param primitive The target vector.
+     * @param fraction The fraction of distance that should be interpolated. For
+     * example, 0.5 would yield a new vector that is half way between this vector
+     * and the target.
+     */
+    interpolate(primitive: VectorPrimitive, fraction: number): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` values are altered by `distance`
+     * along the angle between this vector and the target `x` and `y` values.
+     *
+     * @param x The target x value.
+     * @param y The target y value.
+     * @param distance The distance to move along the line between this vector
+     * and the target.
+     */
+    moveToward(x: number, y: number, distance: number): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` values are altered by `distance`
+     * along the angle between this vector and the respective values within the
+     * target tuple.
+     *
+     * @param tuple The target tuple.
+     * @param distance The distance to move along the line between this vector
+     * and the target.
+     */
+    moveToward(tuple: VectorTuple, distance: number): Vector;
+    /**
+     * Creates a new vector where the `x` and `y` values are altered by `distance`
+     * along the angle between this vector and the respective values within the
+     * target vector.
+     *
+     * @param primitive The target vector.
+     * @param distance The distance to move along the line between this vector
+     * and the target.
+     */
+    moveToward(primitive: VectorPrimitive, distance: number): Vector;
+    /**
+     * Determine the magnitude or length of this vector.
+     */
+    get magnitude(): number;
+    /**
+     * Determine the angle of this vector in radians.
+     */
+    get angle(): number;
+    get x(): number;
+    set x(value: number);
+    get y(): number;
+    set y(value: number);
 }

lib/geom/vector.js

@@ -0,18 +1,199 @@
+/**
+ * Normalize input arguments typically seen for an overloaded method into a
+ * tuple `[x, y]`. This helps write function overloads like the following:
+ *
+ * ```
+ * function example(x: number, y: number): void;
+ * function example(tuple: [number, number]): void;
+ * function example(vector: Vector): void;
+ *
+ * function example(a: number | [number, number] | Vector, b?: number): void {
+ *   const [x, y] = normalizeVectorArgs(a, b);
+ *
+ *   // your code
+ * }
+ * ```
+ *
+ * @param a The x value, vector primitive or vector tuple.
+ * @param b The optional y value.
+ */
+export function normalizeVectorArgs(a, b) {
+    if (typeof a === 'number') {
+        return [a, b !== null && b !== void 0 ? b : 0];
+    }
+    if (Array.isArray(a)) {
+        return a;
+    }
+    return [a.x, a.y];
+}
 export class Vector {
     constructor(x = 0, y = 0) {
+        this._x = 0;
+        this._y = 0;
         this.x = x;
         this.y = y;
     }
+    static from(a, b) {
+        const [x, y] = normalizeVectorArgs(a, b);
+        return new Vector(x, y);
+    }
+    /**
+     * Creates a new vector of `0,-1`, representing an "upward facing" magnitude.
+     */
+    static up() {
+        return new Vector(0, -1);
+    }
+    /**
+     * Creates a new vector of `0,1`, representing a "downward facing" magnitude.
+     */
+    static down() {
+        return new Vector(0, 1);
+    }
+    /**
+     * Creates a new vector of `-1,0`, representing a "left facing" magnitude.
+     */
+    static left() {
+        return new Vector(-1, 0);
+    }
+    /**
+     * Creates a new vector of `1,0`, representing a "right facing" magnitude.
+     */
+    static right() {
+        return new Vector(1, 0);
+    }
+    /**
+     * Creates a new vector where the `x` and `y` values indicate a direction
+     * specified by input radians, starting from `1,0`.
+     *
+     * @param radians The angle in radians.
+     */
+    static diagonal(radians) {
+        return new Vector(Math.cos(radians), Math.sin(radians));
+    }
+    toString() {
+        return `Vector(${this._x}, ${this._y})`;
+    }
+    /**
+     * Creates and returns a new vector where `x` and `y` are equivalent to this
+     * origin vector.
+     */
+    clone() {
+        return new Vector(this._x, this._y);
+    }
     set(a, b) {
-        const value = this.normalizeArgs(a, b);
-        this.x = value.x;
-        this.y = value.y;
+        const [x, y] = normalizeVectorArgs(a, b);
+        this.x = x;
+        this.y = y;
         return this;
     }
-    normalizeArgs(a, b) {
-        if (typeof a === 'number') {
-            return { x: a, y: b !== null && b !== void 0 ? b : 0 };
-        }
-        return a;
+    distanceTo(a, b) {
+        const [x, y] = normalizeVectorArgs(a, b);
+        const dx = x - this._x;
+        const dy = y - this._y;
+        return Math.sqrt(Math.pow(dx, 2) + Math.pow(dy, 2));
     }
+    angleTo(a, b) {
+        const [x, y] = normalizeVectorArgs(a, b);
+        const dx = x - this._x;
+        const dy = y - this._y;
+        return Math.atan2(dy, dx);
+    }
+    /**
+     * Returns a representation of this vector as a tuple of `[x, y]`.
+     */
+    toTuple() {
+        return [this._x, this._y];
+    }
+    /**
+     * Returns a representation of this vector as a primitive object of
+     * `{ x, y }`.
+     */
+    toPrimitive() {
+        return { x: this._x, y: this._y };
+    }
+    /**
+     * Returns a readonly representation of this vector as a primitive object of
+     * `{ x, y }`;
+     */
+    toImmutablePrimitive() {
+        const value = {};
+        Object.defineProperties(value, {
+            x: {
+                value: this._x,
+                writable: false,
+            },
+            y: {
+                value: this._y,
+                writable: false,
+            },
+        });
+        return value;
+    }
+    equals(a, b) {
+        const [x, y] = normalizeVectorArgs(a, b);
+        return x === this._x && y === this._y;
+    }
+    /**
+     * Creates a new vector where the x and y values are a product of the input
+     * value.
+     *
+     * @param value The value to multiply x and y by.
+     */
+    multiply(value) {
+        return new Vector(this._x * value, this._y * value);
+    }
+    /**
+     * Creates a new vector where the `x` and `y` values are divided by the input
+     * value.
+     *
+     * @param value The amount to divide by.
+     */
+    divide(value) {
+        return new Vector(this._x / value, this._y / value);
+    }
+    add(a, b) {
+        const [x, y] = normalizeVectorArgs(a, b);
+        return new Vector(this._x + x, this._y + y);
+    }
+    subtract(a, b) {
+        const [x, y] = normalizeVectorArgs(a, b);
+        return new Vector(this._x - x, this._y - y);
+    }
+    interpolate(a, b, c) {
+        const [x, y] = normalizeVectorArgs(a, b);
+        const fraction = c !== null && c !== void 0 ? c : b;
+        const angle = this.angleTo(x, y);
+        const distance = this.distanceTo(x, y) * fraction;
+        return new Vector(this._x + Math.cos(angle) * distance, this._y + Math.sin(angle) * distance);
+    }
+    moveToward(a, b, c) {
+        const [x, y] = normalizeVectorArgs(a, b);
+        const distance = c !== null && c !== void 0 ? c : b;
+        const angle = this.angleTo(x, y);
+        return new Vector(this._x + Math.cos(angle) * distance, this._y + Math.sin(angle));
+    }
+    /**
+     * Determine the magnitude or length of this vector.
+     */
+    get magnitude() {
+        return Math.sqrt(Math.pow(this._x, 2) + Math.pow(this._y, 2));
+    }
+    /**
+     * Determine the angle of this vector in radians.
+     */
+    get angle() {
+        return Math.atan2(this._y, this._x);
+    }
+    get x() {
+        return this._x;
+    }
+    set x(value) {
+        this._x = Number.isFinite(value) ? value : this._x;
+    }
+    get y() {
+        return this._y;
+    }
+    set y(value) {
+        this._y = Number.isFinite(value) ? value : this._y;
+    }
 }

lib/index.d.ts

@@ -0,4 +1,10 @@
+export * from './decorators/worldObjectDecorator';
 export * from './geom/vector';
 export * from './types';
-export * from './world';
-export * from './worldObject';
+export * from './world/query/constraints/tagConstraint';
+export * from './world/query/constraints/typeConstraint';
+export * from './world/query/worldQuery';
+export * from './world/world';
+export * from './world/worldCamera';
+export * from './world/worldObject';
+export * from './world/worldObjectRef';

lib/index.js

@@ -0,4 +1,10 @@
+export * from './decorators/worldObjectDecorator';
 export * from './geom/vector';
 export * from './types';
-export * from './world';
-export * from './worldObject';
+export * from './world/query/constraints/tagConstraint';
+export * from './world/query/constraints/typeConstraint';
+export * from './world/query/worldQuery';
+export * from './world/world';
+export * from './world/worldCamera';
+export * from './world/worldObject';
+export * from './world/worldObjectRef';

package.json

 {
   "name": "@arcade2d/world",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Provides components for composing and running a game world.",
@@ -44,3 +44,6 @@ "license": "MIT",
     "typescript": "^4.5.5"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.1.13"
   }
 }

README.md

@@ -1,3 +0,17 @@
-# World
+# @arcade2d/world
 
+![Coverage](https://gitlab.com/arcade2d/world/badges/master/coverage.svg?key_text=Coverage) ![Latest Release](https://gitlab.com/arcade2d/world/-/badges/release.svg)
+
+[Repository](https://gitlab.com/arcade2d/world) · [Website](https://arcade2d.com)
+
+The aim of this library is to construct and simulate a game world in an abstract sense. It does not provide any functionality or features outside of this such as rendering capabilities (graphics), sound or other game related components. It purely focuses on a game world and how objects within that world can be interacted with and interact with each other.
+
+It covers things like:
+
+- A base class to build your own world objects from.
+- Adding and removing objects from a world.
+- Simulating a step within the world, which cascades down to objects within that world.
+- Mathematical concepts for objects within the world such as 2D vector positions.
+- Querying the world for certain objects.
+
 ## Installation
@@ -8,1 +22,35 @@
 ```
+
+## Usage Example
+
+```typescript
+import {
+  World,
+  AbstractWorldObject,
+  WorldObject,
+  Vector,
+} from '@arcade2d/world';
+
+// Create a new type of WorldObject.
+@WorldObject({
+  tags: ['example'],
+  queryable: true,
+})
+class MyObject extends AbstractWorldObject {}
+
+// Create the World.
+const world = new World();
+
+// Add some objects.
+const objectA = world.add(new MyObject(), Vector.from(100, 100));
+const objectB = world.add(new MyObject(), Vector.from(200, 250));
+
+// Example of measuring distance between two objects within the world.
+console.log(objectA.position.distanceTo(objectB.position));
+
+// Query for objects.
+console.log(world.query().types(MyObject).first());
+
+// Call step() on the world every 16ms.
+setInterval(() => world.step(), 16);
+```

tsconfig.json

@@ -15,3 +15,6 @@ {
     "skipLibCheck": false,
-    "strict": true
+    "strict": true,
+    "stripInternal": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true
   },
@@ -18,0 +21,0 @@ "include": [

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

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

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

38066

increased by230.81%

Number of package files

27

increased by80%

Lines of code

1056

increased by233.12%

Number of lines in readme file

56

increased by600%

Worsened metrics

Dependency count

1

increased byInfinity%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedreflect-metadata@^0.1.13

• + Addedreflect-metadata@0.1.14(transitive)