kippy 0.2.2 → 0.3.0

package/README.md

@@ -64,8 +64,7 @@ import { Entity } from "kippy";
 
 const entity = new Entity({
     sprite, // Entity's sprite to be rendered, type Sprite
-    x, // Entity's x position (centered), type number
-    y, // Entity's y position (centered), type number
+    position, // Entity's position (centered), type Vector2
     rotation, // Entity's rotation in radians, type number
     body, // Entity's physical body, type EntityBody
 });
@@ -76,8 +75,10 @@ scene.addEntity(entity);
 scene.removeEntity(entity);
 
 // These props contain movement info and you can mutate them to edit its position
-entity.x; // Initialized from the "x" param above, 0 if not specified
-entity.y; // Initialized from the "y" param above, 0 if not specified
+entity.position; // Initialized from the "position" param above, Vector2(0, 0) if not specified
+// You can mutate these directly:
+entity.position.x;
+entity.position.y;
 entity.rotation; // Initialized from the "rotation" param above, 0 if not specified
 ```
 
@@ -118,19 +119,55 @@ input.pointerX; // Current X position of mouse/touch
 input.pointerY; // Current Y position of mouse/touch
 ```
 
+### Vectors
+
+To work with positions and movements in Kippy, it is best to know about `Vector2` first. Positions, velocities, forces, etc are all represented as vectors in Kippy. And here is how you can create a 2D vector and some vector math utilities that comes along with it:
+```js
+import { Vector2 } from "kippy";
+
+const vect = new Vector2(/* x coordinate, number */, /*y coordinate, number */);
+
+// Props
+vect.x; // X coordinate
+vect.y; // Y coordinate
+
+// Utilities
+vect.add(otherVect); // Add another vector and return the result vector
+vect.sub(otherVect); // Subtract another vector and return the result vector
+vect.scale(scale); // Multiply with scale and return the result vector
+vect.magnitude(); // Return the magnitude/length of vector
+vect.normalize(); // Return the normalized vector by magnitude
+vect.dot(otherVect); // Return dot product with another vector
+vect.distance(otherVect); // Return distance to another vector
+vect.copy(); // Return a copy (same coordinates, different reference)
+vect.lerp(otherVect, scale); // Apply linear interpolation and return
+vect.clamp(maxLength); // Clamp vector to have length below maxLength
+vect.rotate(angle); // Return rotated vector by provided angle
+vect.angle(); // Return angle of vector.
+vect.angleTo(otherVec); // Return angle between this and another vector
+vect.reflect(otherVect); // Return reflection/bounce back vector
+vect.equals(otherVect); // Check if two vectors are equal
+
+// Useful constants
+Vector2.ZERO; // Vector2(0, 0)
+Vector2.ONE; // Vector2(1, 1);
+Vector2.UP; // Vector2(0, -1);
+Vector2.DOWN; // Vector2(0, 1);
+Vector2.LEFT; // Vector2(-1, 0);
+Vector2.RIGHT; // Vector2(1, 0);
+```
+
 ### Physics
 
 For movements, currently you can create a `RigidBody`:
 ```js
 // Create a rigid body
 const rigidBody = new RigidBody({
-    velocityX, // X velocity, type number
-    velocityY, // Y velocity, type number
-    rotationVelocity, // Angular/rotation velocity, type number
+    velocity, // Entity's velocity vector, type Vector2
+    rotationVelocity, // Entity's ngular/rotation velocity, type number
     mass, // Entity's mass, type number
     inertia, // Entity's inertia, type number
-    forceX, // Entity's force on X axis, type number
-    forceY, // Entity's force on Y axis, type number
+    force, // Entity's force vector, type Vector2
     torque, // Entity's torque/rotational force, type number
 });
 
@@ -138,13 +175,12 @@ const rigidBody = new RigidBody({
 entity.body = rigidBody;
 
 // And you can mutate these props to update movement every frame
-entity.body.velocityX; // Set with the matching parameter above, default is 0
-entity.body.velocityY; // Set with the matching parameter above, default is 0
+entity.body.velocity; // Set with the matching parameter above, default is Vector2(0, 0)
 entity.body.rotationVelocity; // Set with the matching parameter above, default is 0
 entity.body.mass; // Set with the matching parameter above, default is 1
 entity.body.inertia; // Set with the matching parameter above, default is 1
-entity.body.forceX; // Set with the matching parameter above, default is 0
-entity.body.forceY; // Set with the matching parameter above, default is 0
+// Note that forces are reset after every frame
+entity.body.force; // Set with the matching parameter above, default is Vector2(0, 0)
 entity.body.torque; // Set with the matching parameter above, default is 0
 ```
 
@@ -158,6 +194,10 @@ To be added, for now mutate `entity.sprite` to swap sprites and create animation
 
 To be added, for now use web's built-in `Audio` class.
 
+### Asset management
+
+To be added.
+
 ## Copyrights and License
 
 Copyrights © 2026 Nguyen Phu Minh.

package/dist/entity.d.ts

@@ -1,16 +1,15 @@
 import { EntityBody } from "./physics.js";
 import { Sprite } from "./sprite.js";
+import { Vector2 } from "./vector.js";
 export interface EntityOptions {
     sprite?: Sprite;
-    x?: number;
-    y?: number;
+    position?: Vector2;
     rotation?: number;
     body?: EntityBody;
 }
 export declare class Entity {
     sprite?: Sprite;
-    x: number;
-    y: number;
+    position: Vector2;
     rotation: number;
     body?: EntityBody;
     constructor(options?: EntityOptions);

package/dist/entity.js

@@ -1,20 +1,19 @@
+import { Vector2 } from "./vector.js";
 export class Entity {
     sprite;
-    x;
-    y;
+    position;
     rotation;
     body;
     constructor(options = {}) {
         this.sprite = options.sprite;
-        this.x = options.x ?? 0;
-        this.y = options.y ?? 0;
+        this.position = options.position ?? new Vector2(0, 0);
         this.rotation = options.rotation ?? 0;
         this.body = options.body;
     }
     render(ctx) {
         if (this.sprite) {
             ctx.save();
-            ctx.translate(this.x, this.y);
+            ctx.translate(this.position.x, this.position.y);
             ctx.rotate(this.rotation);
             ctx.drawImage(this.sprite.texture, -this.sprite.width / 2, -this.sprite.height / 2);
             ctx.restore();

package/dist/physics.d.ts

@@ -1,22 +1,19 @@
 import { Entity } from "./entity";
+import { Vector2 } from "./vector";
 export interface RigidBodyOptions {
-    velocityX?: number;
-    velocityY?: number;
+    velocity?: Vector2;
     rotationVelocity?: number;
     mass?: number;
     inertia?: number;
-    forceX?: number;
-    forceY?: number;
+    force?: Vector2;
     torque?: number;
 }
 export declare class RigidBody {
-    velocityX: number;
-    velocityY: number;
+    velocity: Vector2;
     rotationVelocity: number;
     mass: number;
     inertia: number;
-    forceX: number;
-    forceY: number;
+    force: Vector2;
     torque: number;
     constructor(options?: RigidBodyOptions);
 }

package/dist/physics.js

@@ -1,20 +1,17 @@
+import { Vector2 } from "./vector";
 export class RigidBody {
-    velocityX;
-    velocityY;
+    velocity;
     rotationVelocity;
     mass;
     inertia;
-    forceX;
-    forceY;
+    force;
     torque;
     constructor(options = {}) {
-        this.velocityX = options.velocityX ?? 0;
-        this.velocityY = options.velocityY ?? 0;
+        this.velocity = options.velocity ?? new Vector2(0, 0);
         this.rotationVelocity = options.rotationVelocity ?? 0;
         this.mass = options.mass ?? 1;
         this.inertia = options.inertia ?? 1;
-        this.forceX = options.forceX ?? 0;
-        this.forceY = options.forceY ?? 0;
+        this.force = options.force ?? new Vector2(0, 0);
         this.torque = options.torque ?? 0;
     }
 }
@@ -23,13 +20,17 @@ export class Physics {
         for (const entity of entities) {
             if (entity.body instanceof RigidBody) {
                 // Acceleration/apply force
-                entity.body.velocityX += entity.body.forceX / entity.body.mass;
-                entity.body.velocityY += entity.body.forceY / entity.body.mass;
+                entity.body.velocity.x += entity.body.force.x / entity.body.mass;
+                entity.body.velocity.y += entity.body.force.y / entity.body.mass;
                 entity.body.rotationVelocity += entity.body.torque / entity.body.inertia;
                 // Positional update
-                entity.x += entity.body.velocityX;
-                entity.y += entity.body.velocityY;
+                entity.position.x += entity.body.velocity.x;
+                entity.position.y += entity.body.velocity.y;
                 entity.rotation += entity.body.rotationVelocity;
+                // Clear force
+                entity.body.force.x = 0;
+                entity.body.force.y = 0;
+                entity.body.torque = 0;
             }
         }
     }

package/dist/vector.d.ts

@@ -0,0 +1,26 @@
+export declare class Vector2 {
+    x: number;
+    y: number;
+    static ZERO: Vector2;
+    static ONE: Vector2;
+    static UP: Vector2;
+    static DOWN: Vector2;
+    static LEFT: Vector2;
+    static RIGHT: Vector2;
+    constructor(x: number, y: number);
+    add(other: Vector2): Vector2;
+    sub(other: Vector2): Vector2;
+    scale(scale: number): Vector2;
+    magnitude(): number;
+    normalize(): Vector2;
+    dot(other: Vector2): number;
+    distance(other: Vector2): number;
+    copy(): Vector2;
+    lerp(other: Vector2, scale: number): Vector2;
+    clamp(maxLength: number): Vector2;
+    rotate(angle: number): Vector2;
+    angle(): number;
+    angleTo(other: Vector2): number;
+    reflect(normal: Vector2): Vector2;
+    equals(other: Vector2): boolean;
+}

package/dist/vector.js

@@ -0,0 +1,64 @@
+export class Vector2 {
+    x;
+    y;
+    static ZERO = new Vector2(0, 0);
+    static ONE = new Vector2(1, 1);
+    static UP = new Vector2(0, -1);
+    static DOWN = new Vector2(0, 1);
+    static LEFT = new Vector2(-1, 0);
+    static RIGHT = new Vector2(1, 0);
+    constructor(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    add(other) {
+        return new Vector2(this.x + other.x, this.y + other.y);
+    }
+    sub(other) {
+        return new Vector2(this.x - other.x, this.y - other.y);
+    }
+    scale(scale) {
+        return new Vector2(this.x * scale, this.y * scale);
+    }
+    magnitude() {
+        return Math.sqrt(this.x * this.x + this.y * this.y);
+    }
+    normalize() {
+        const mag = this.magnitude();
+        return mag > 0 ? new Vector2(this.x / mag, this.y / mag) : new Vector2(0, 0);
+    }
+    dot(other) {
+        return this.x * other.x + this.y * other.y;
+    }
+    distance(other) {
+        return Math.sqrt((this.x - other.x) ** 2 + (this.y - other.y) ** 2);
+    }
+    copy() {
+        return new Vector2(this.x, this.y);
+    }
+    lerp(other, scale) {
+        return this.add(other.sub(this).scale(scale));
+    }
+    clamp(maxLength) {
+        const mag = this.magnitude();
+        return mag > maxLength ? this.scale(maxLength / mag) : this.copy();
+    }
+    rotate(angle) {
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+        return new Vector2(this.x * cos - this.y * sin, this.x * sin + this.y * cos);
+    }
+    angle() {
+        return Math.atan2(this.y, this.x);
+    }
+    angleTo(other) {
+        return Math.atan2(other.y - this.y, other.x - this.x);
+    }
+    reflect(normal) {
+        const d = this.dot(normal);
+        return this.sub(normal.scale(2 * d));
+    }
+    equals(other) {
+        return this.x === other.x && this.y === other.y;
+    }
+}

package/index.d.ts

@@ -3,4 +3,5 @@ export * from "./dist/scene.js";
 export * from "./dist/entity.js";
 export * from "./dist/sprite.js";
 export * from "./dist/input.js";
-export * from "./dist/physics.js";
+export * from "./dist/physics.js";
+export * from "./dist/vector.js";

package/index.js

@@ -4,3 +4,4 @@ export * from "./dist/entity.js";
 export * from "./dist/sprite.js";
 export * from "./dist/input.js";
 export * from "./dist/physics.js";
+export * from "./dist/vector.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kippy",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Kippy 2D web game engine for JS",
   "keywords": [
     "kippy",