kippy 0.2.1 → 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
 ```
 
@@ -99,7 +100,7 @@ entity.sprite = sprite;
 
 ### Add controls
 
-Game controls like mouse presses, key presses, and mouse cursor traking (in the game canvas, not the web window) can be done by using the input handler from your `game` instance:
+Game controls like mouse presses, key presses, touch, and cursor traking (in the game canvas, not the web window) can be done by using the input handler from your `game` instance:
 ```js
 const input = game.input;
 ```
@@ -110,12 +111,50 @@ Then in a scene's `update` method, you can use these utilities to check for key
 input.isKeyDown(/* Character/key here */); // true if key is held, false otherwise
 input.isKeyPressed(/* Character/key here */); // true if key is pressed, false otherwise
 input.isKeyReleased(/* Character/key here */); // true if key is released, false otherwise
-// Mouse
-input.isMouseDown(/* 0 for left, 1 for right */); // true if mouse is held, false otherwise
-input.isMousePressed(/* 0 for left, 1 for right */); // true if mouse is pressed, false otherwise
-input.isMouseReleased(/* 0 for left, 1 for right */); // true if mouse is released, false otherwise
-input.mouseX; // Current X position of mouse
-input.mouseY; // Current Y position of mouse
+// Mouse/touch
+input.isPointerDown(/* 0 for left, 1 for right, 2 for touch */); // true if held, false otherwise
+input.isPointerPressed(/* 0 for left, 1 for right, 2 for touch */); // true if pressed, false otherwise
+input.isPointerReleased(/* 0 for left, 1 for right, 2 for touch */); // true if released, false otherwise
+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
@@ -124,13 +163,11 @@ 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/input.d.ts

@@ -6,17 +6,17 @@ export declare class Input {
     keys: Set<string>;
     keysPressed: Set<string>;
     keysReleased: Set<string>;
-    mouseX: number;
-    mouseY: number;
-    mouseButtons: Set<number>;
-    mousePressed: Set<number>;
-    mouseReleased: Set<number>;
+    pointerX: number;
+    pointerY: number;
+    pointers: Set<number>;
+    pointersPressed: Set<number>;
+    pointersReleased: Set<number>;
     constructor(options: InputOptions);
     update(): void;
     isKeyDown(key: string): boolean;
     isKeyPressed(key: string): boolean;
     isKeyReleased(key: string): boolean;
-    isMouseDown(button?: number): boolean;
-    isMousePressed(button?: number): boolean;
-    isMouseReleased(button?: number): boolean;
+    isPointerDown(button?: number): boolean;
+    isPointerPressed(button?: number): boolean;
+    isPointerReleased(button?: number): boolean;
 }

package/dist/input.js

@@ -3,11 +3,11 @@ export class Input {
     keys = new Set(); // Key on hold
     keysPressed = new Set(); // Key pressed
     keysReleased = new Set(); // Key released
-    mouseX = 0; // Mouse coord x in canvas
-    mouseY = 0; // Mouse coord y in canvas
-    mouseButtons = new Set(); // Mouse button on hold
-    mousePressed = new Set(); // Mouse button pressed 
-    mouseReleased = new Set(); // Mouse button released
+    pointerX = 0; // Mouse/touch coord x in canvas
+    pointerY = 0; // Mouse/touch coord y in canvas
+    pointers = new Set(); // Mouse/touch on hold
+    pointersPressed = new Set(); // Mouse/touch pressed 
+    pointersReleased = new Set(); // Mouse/touch released
     constructor(options) {
         this.canvas = options.canvas;
         // Keyboard
@@ -21,21 +21,40 @@ export class Input {
             this.keys.delete(e.key);
             this.keysReleased.add(e.key);
         });
-        // Mouse
+        // Mouse and touch
         this.canvas.addEventListener("mousemove", (e) => {
             const rect = this.canvas.getBoundingClientRect();
-            this.mouseX = e.clientX - rect.left;
-            this.mouseY = e.clientY - rect.top;
+            this.pointerX = e.clientX - rect.left;
+            this.pointerY = e.clientY - rect.top;
         });
         this.canvas.addEventListener("mousedown", (e) => {
-            if (!this.mouseButtons.has(e.button)) {
-                this.mousePressed.add(e.button);
+            if (!this.pointers.has(e.button)) {
+                this.pointersPressed.add(e.button);
             }
-            this.mouseButtons.add(e.button);
+            this.pointers.add(e.button);
         });
         this.canvas.addEventListener("mouseup", (e) => {
-            this.mouseButtons.delete(e.button);
-            this.mouseReleased.add(e.button);
+            this.pointers.delete(e.button);
+            this.pointersReleased.add(e.button);
+        });
+        this.canvas.addEventListener("touchmove", (e) => {
+            e.preventDefault();
+            const rect = this.canvas.getBoundingClientRect();
+            const touch = e.touches[0];
+            this.pointerX = touch.clientX - rect.left;
+            this.pointerY = touch.clientY - rect.top;
+        });
+        this.canvas.addEventListener("touchstart", (e) => {
+            e.preventDefault();
+            if (!this.pointers.has(2)) {
+                this.pointersPressed.add(2);
+            }
+            this.pointers.add(2);
+        });
+        this.canvas.addEventListener("touchend", (e) => {
+            e.preventDefault();
+            this.pointers.delete(2);
+            this.pointersReleased.add(2);
         });
         // Prevent right-click menu
         this.canvas.addEventListener("contextmenu", (e) => {
@@ -46,7 +65,8 @@ export class Input {
     update() {
         this.keysPressed.clear();
         this.keysReleased.clear();
-        this.mousePressed.clear();
+        this.pointersPressed.clear();
+        this.pointersReleased.clear();
     }
     // Helper methods
     isKeyDown(key) {
@@ -58,13 +78,13 @@ export class Input {
     isKeyReleased(key) {
         return this.keysReleased.has(key);
     }
-    isMouseDown(button = 0) {
-        return this.mouseButtons.has(button);
+    isPointerDown(button = 0) {
+        return this.pointers.has(button);
     }
-    isMousePressed(button = 0) {
-        return this.mousePressed.has(button);
+    isPointerPressed(button = 0) {
+        return this.pointersPressed.has(button);
     }
-    isMouseReleased(button = 0) {
-        return this.mouseReleased.has(button);
+    isPointerReleased(button = 0) {
+        return this.pointersReleased.has(button);
     }
 }

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.1",
+  "version": "0.3.0",
   "description": "Kippy 2D web game engine for JS",
   "keywords": [
     "kippy",