kippy 0.1.0

package/README.md

@@ -0,0 +1,137 @@
+## Kippy
+
+Kippy is a 2D JS game engine written purely for fun and simplicity. It currently utilizes the Canvas 2D context for rendering and aims to have a small set of APIs viable for game dev, but do expect a lot of components to change in the future.
+
+## Setup
+
+Install through npm:
+```
+npm install kippy
+```
+
+## Tutorial
+
+Here is a vaguely-written tutorial for now:
+
+### Initialize game
+
+First, prepare a canvas tag in your html file:
+```html
+<canvas></canvas>
+```
+
+Then mount your game there:
+```js
+import { Game } from "kippy";
+
+const canvas = document.querySelector("canvas");
+const game = new Game({
+    canvas
+});
+
+// Start the game loop
+game.start();
+```
+
+### Create a scene
+
+Here is how you can create a scene and load that scene into your game object:
+```js
+import { Scene } from "kippy";
+
+class Main extends Scene {
+    // Runs when this scene gets loaded into a game
+    init() {}
+    // Runs on every frame, dt is the time between each frame
+    update(dt) {}
+    // Runs when another scene replaces this scene in a game
+    exit() {}
+}
+
+// Create scene and load into game
+const main = new Main();
+game.setScene(main);
+```
+
+### Create an entity
+
+A scene can have multiple entities like players, mobs, obstacles, etc in it. This is how you can create an entity:
+```js
+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
+    rotation // Entity's rotation in radians, type number
+});
+
+// Add it to a scene
+scene.addEntity(entity);
+// Remove it from a scene
+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.rotation; // Initialized from the "rotation" param above, 0 if not specified
+```
+
+### Create a sprite
+
+A sprite represents what an entity looks like, the "graphics part", you can create a sprite like this:
+```js
+const sprite = new Sprite({
+    texture, // Sprite's texture, can be HTMLImageElement, HTMLCanvasElement, OffscreenCanvas, ImageBitmap
+    width, // Sprite's width, type number
+    height // Sprite's height, type number
+});
+
+// Set sprite for an entity
+entity.setSprite(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 with the `Input` class:
+```js
+const input = new Input({
+    canvas
+});
+
+// You can assign it into a game during initialization
+const game = new Game({
+    // other stuff
+    input
+})
+// or after
+game.setInput(input);
+```
+
+Then in a scene's `update` method, you can use these utilities to check for key presses:
+```js
+// Keyboard
+input.isKeyDown(/* Character/key here */); // Key hold
+input.isKeyPressed(/* Character/key here */); // Key press
+input.isKeyReleased(/* Character/key here */); // Key released
+// Mouse
+input.isMouseDown(/* 0 for left, 1 for right */); // Mouse hold
+input.isMousePressed(/* 0 for left, 1 for right */); // Mouse press
+input.isMouseReleased(/* 0 for left, 1 for right */); // Mouse released
+input.mouseX; // Current X position of mouse
+input.mouseY; // Current Y position of mouse
+```
+
+### Physics
+
+To be added, will have rigidBody for entities with collision and movement-related stuff.
+
+### Audio
+
+To be added, for now use web's built-in `Audio` class.
+
+## Copyrights and License
+
+Copyrights © 2026 Nguyen Phu Minh.
+
+This project is licensed under the Apache 2.0 license.

package/dist/entity.d.ts

@@ -0,0 +1,16 @@
+import { Sprite } from "./sprite.js";
+export interface EntityOptions {
+    sprite?: Sprite;
+    x?: number;
+    y?: number;
+    rotation?: number;
+}
+export declare class Entity {
+    sprite?: Sprite;
+    x: number;
+    y: number;
+    rotation: number;
+    constructor(options: EntityOptions);
+    setSprite(sprite: Sprite): void;
+    render(ctx: CanvasRenderingContext2D): void;
+}

package/dist/entity.js

@@ -0,0 +1,24 @@
+export class Entity {
+    sprite;
+    x;
+    y;
+    rotation;
+    constructor(options) {
+        this.sprite = options.sprite;
+        this.x = options.x || 0;
+        this.y = options.y || 0;
+        this.rotation = options.rotation || 0;
+    }
+    setSprite(sprite) {
+        this.sprite = sprite;
+    }
+    render(ctx) {
+        if (this.sprite) {
+            ctx.save();
+            ctx.translate(this.x, this.y);
+            ctx.rotate(this.rotation);
+            ctx.drawImage(this.sprite.texture, -this.sprite.width / 2, -this.sprite.height / 2);
+            ctx.restore();
+        }
+    }
+}

package/dist/game.d.ts

@@ -0,0 +1,18 @@
+import { Input } from "./input.js";
+import { Scene } from "./scene.js";
+export interface GameOptions {
+    canvas: HTMLCanvasElement;
+    input?: Input;
+}
+export declare class Game {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+    scene?: Scene;
+    lastTime: number;
+    input?: Input;
+    constructor(options: GameOptions);
+    setScene(scene: Scene): void;
+    setInput(input: Input): void;
+    start(): void;
+    loop(timestamp: number): void;
+}

package/dist/game.js

@@ -0,0 +1,35 @@
+export class Game {
+    canvas;
+    ctx;
+    scene;
+    lastTime = 0;
+    input;
+    constructor(options) {
+        this.canvas = options.canvas;
+        this.ctx = this.canvas.getContext("2d");
+        this.input = options.input;
+    }
+    setScene(scene) {
+        this.scene?.exit();
+        this.scene = scene;
+        this.scene.init();
+    }
+    setInput(input) {
+        this.input = input;
+    }
+    start() {
+        requestAnimationFrame(this.loop.bind(this));
+    }
+    // Game loop
+    loop(timestamp) {
+        const dt = (timestamp - this.lastTime) / 1000;
+        this.lastTime = timestamp;
+        // Update state, clear canvas, re-render
+        this.scene?.update(dt);
+        this.ctx.clearRect(0, 0, this.ctx.canvas.width, this.ctx.canvas.height);
+        this.scene?.render(this.ctx);
+        // Update input info
+        this.input?.update();
+        requestAnimationFrame(this.loop.bind(this));
+    }
+}

package/dist/input.d.ts

@@ -0,0 +1,22 @@
+export interface InputOptions {
+    canvas: HTMLCanvasElement;
+}
+export declare class Input {
+    canvas: HTMLCanvasElement;
+    keys: Set<string>;
+    keysPressed: Set<string>;
+    keysReleased: Set<string>;
+    mouseX: number;
+    mouseY: number;
+    mouseButtons: Set<number>;
+    mousePressed: Set<number>;
+    mouseReleased: 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;
+}

package/dist/input.js

@@ -0,0 +1,70 @@
+export class Input {
+    canvas;
+    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
+    constructor(options) {
+        this.canvas = options.canvas;
+        // Keyboard
+        window.addEventListener("keydown", (e) => {
+            if (!this.keys.has(e.key)) {
+                this.keysPressed.add(e.key);
+            }
+            this.keys.add(e.key);
+        });
+        window.addEventListener("keyup", (e) => {
+            this.keys.delete(e.key);
+            this.keysReleased.add(e.key);
+        });
+        // Mouse
+        this.canvas.addEventListener("mousemove", (e) => {
+            const rect = this.canvas.getBoundingClientRect();
+            this.mouseX = e.clientX - rect.left;
+            this.mouseY = e.clientY - rect.top;
+        });
+        this.canvas.addEventListener("mousedown", (e) => {
+            if (!this.mouseButtons.has(e.button)) {
+                this.mousePressed.add(e.button);
+            }
+            this.mouseButtons.add(e.button);
+        });
+        this.canvas.addEventListener("mouseup", (e) => {
+            this.mouseButtons.delete(e.button);
+            this.mouseReleased.add(e.button);
+        });
+        // Prevent right-click menu
+        this.canvas.addEventListener("contextmenu", (e) => {
+            e.preventDefault();
+        });
+    }
+    // Called every frames
+    update() {
+        this.keysPressed.clear();
+        this.keysReleased.clear();
+        this.mousePressed.clear();
+    }
+    // Helper methods
+    isKeyDown(key) {
+        return this.keys.has(key);
+    }
+    isKeyPressed(key) {
+        return this.keysPressed.has(key);
+    }
+    isKeyReleased(key) {
+        return this.keysReleased.has(key);
+    }
+    isMouseDown(button = 0) {
+        return this.mouseButtons.has(button);
+    }
+    isMousePressed(button = 0) {
+        return this.mousePressed.has(button);
+    }
+    isMouseReleased(button = 0) {
+        return this.mouseReleased.has(button);
+    }
+}

package/dist/scene.d.ts

@@ -0,0 +1,10 @@
+import { Entity } from "./entity.js";
+export declare abstract class Scene {
+    entities: Entity[];
+    init(): void;
+    update(deltaTime: number): void;
+    exit(): void;
+    addEntity(entity: Entity): void;
+    removeEntity(entity: Entity): void;
+    render(ctx: CanvasRenderingContext2D): void;
+}

package/dist/scene.js

@@ -0,0 +1,17 @@
+export class Scene {
+    entities = [];
+    init() { }
+    update(deltaTime) { }
+    exit() { }
+    addEntity(entity) {
+        this.entities.push(entity);
+    }
+    removeEntity(entity) {
+        this.entities = this.entities.filter(childEntities => childEntities !== entity);
+    }
+    render(ctx) {
+        for (const entity of this.entities) {
+            entity.render(ctx);
+        }
+    }
+}

package/dist/sprite.d.ts

@@ -0,0 +1,12 @@
+export type Texture = HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap;
+export interface SpriteOptions {
+    texture: Texture;
+    width?: number;
+    height?: number;
+}
+export declare class Sprite {
+    texture: Texture;
+    width: number;
+    height: number;
+    constructor(options: SpriteOptions);
+}

package/dist/sprite.js

@@ -0,0 +1,10 @@
+export class Sprite {
+    texture;
+    width;
+    height;
+    constructor(options) {
+        this.texture = options.texture;
+        this.width = options.width || this.texture.width;
+        this.height = options.height || this.texture.height;
+    }
+}

package/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./dist/game.js";
+export * from "./dist/scene.js";
+export * from "./dist/entity.js";
+export * from "./dist/sprite.js";
+export * from "./dist/input.js";

package/index.js

@@ -0,0 +1,5 @@
+export * from "./dist/game.js";
+export * from "./dist/scene.js";
+export * from "./dist/entity.js";
+export * from "./dist/sprite.js";
+export * from "./dist/input.js";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "kippy",
+  "version": "0.1.0",
+  "description": "Kippy 2D web game engine for JS",
+  "keywords": [
+    "kippy",
+    "game-engine",
+    "game",
+    "2d",
+    "renderer",
+    "graphics",
+    "physics",
+    "library",
+    "framework",
+    "engine"
+  ],
+  "homepage": "https://github.com/nguyenphuminh/kippy#readme",
+  "bugs": {
+    "url": "https://github.com/nguyenphuminh/kippy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nguyenphuminh/kippy.git"
+  },
+  "license": "Apache-2.0",
+  "author": "nguyenphuminh",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  },
+  "files": [
+    "dist/",
+    "index.d.ts",
+    "index.js",
+    "LICENSE",
+    "README.md"
+  ]
+}