aether-engine 1.0.0

package/src/core/Input.ts

@@ -0,0 +1,94 @@
+// biome-ignore lint/complexity/noStaticOnlyClass: Engine architecture uses static manager classes
+export class Input {
+	private static _keys = new Set<string>();
+	private static _previousKeys = new Set<string>();
+	private static _actions = new Map<string, string[]>();
+	private static _mouseDown = false;
+	private static _previousMouseDown = false;
+	private static _mousePosition = { x: 0, y: 0 };
+	private static _initialized = false;
+
+	static initialize() {
+		if (Input._initialized) return;
+		Input._initialized = true;
+
+		window.addEventListener("keydown", (e) => Input._keys.add(e.code));
+		window.addEventListener("keyup", (e) => Input._keys.delete(e.code));
+		window.addEventListener("mousedown", () => {
+			Input._keys.add("Mouse0");
+			Input._mouseDown = true;
+		});
+		window.addEventListener("mouseup", () => {
+			Input._keys.delete("Mouse0");
+			Input._mouseDown = false;
+		});
+		window.addEventListener("mousemove", (e) => {
+			Input._mousePosition.x = e.clientX;
+			Input._mousePosition.y = e.clientY;
+		});
+	}
+
+	static update() {
+		Input._previousKeys.clear();
+		for (const key of Input._keys) {
+			Input._previousKeys.add(key);
+		}
+		Input._previousMouseDown = Input._mouseDown;
+	}
+
+	static bind(action: string, keycodes: string[]) {
+		Input._actions.set(action, keycodes);
+	}
+
+	static isKeyDown(code: string): boolean {
+		return Input._keys.has(code);
+	}
+
+	static isKeyJustPressed(code: string): boolean {
+		return Input._keys.has(code) && !Input._previousKeys.has(code);
+	}
+
+	static isKeyJustReleased(code: string): boolean {
+		return !Input._keys.has(code) && Input._previousKeys.has(code);
+	}
+
+	static isActionPressed(action: string): boolean {
+		const codes = Input._actions.get(action) || [];
+		for (const code of codes) {
+			if (Input.isKeyDown(code)) return true;
+		}
+		return false;
+	}
+
+	static isActionJustPressed(action: string): boolean {
+		const codes = Input._actions.get(action) || [];
+		for (const code of codes) {
+			if (Input.isKeyJustPressed(code)) return true;
+		}
+		return false;
+	}
+
+	static isActionJustReleased(action: string): boolean {
+		const codes = Input._actions.get(action) || [];
+		for (const code of codes) {
+			if (Input.isKeyJustReleased(code)) return true;
+		}
+		return false;
+	}
+
+	static isMouseDown(): boolean {
+		return Input._mouseDown;
+	}
+
+	static isMouseJustPressed(): boolean {
+		return Input._mouseDown && !Input._previousMouseDown;
+	}
+
+	static isMouseJustReleased(): boolean {
+		return !Input._mouseDown && Input._previousMouseDown;
+	}
+
+	static getMousePosition() {
+		return Input._mousePosition;
+	}
+}

package/src/core/Scene.ts

@@ -0,0 +1,24 @@
+import type { AetherEngine } from "../index";
+
+export abstract class Scene {
+	protected engine: AetherEngine;
+
+	constructor(engine: AetherEngine) {
+		this.engine = engine;
+	}
+
+	/**
+	 * Called before the scene starts. Ideal for loading assets.
+	 */
+	async load(): Promise<void> {}
+
+	/**
+	 * Called to instantiate entities and begin the scene.
+	 */
+	abstract start(): void;
+
+	/**
+	 * Called when transitioning away from the scene.
+	 */
+	stop(): void {}
+}

package/src/core/SceneManager.ts

@@ -0,0 +1,57 @@
+import { AudioSource } from "../components/AudioSource";
+import type { AetherEngine } from "../index";
+import type { Scene } from "./Scene";
+
+export type SceneFactory = (engine: AetherEngine) => Scene;
+
+export class SceneManager {
+	private engine: AetherEngine;
+	private scenes = new Map<string, SceneFactory>();
+	public currentScene: Scene | null = null;
+	public currentSceneName: string | null = null;
+
+	constructor(engine: AetherEngine) {
+		this.engine = engine;
+	}
+
+	public register(name: string, factory: SceneFactory) {
+		this.scenes.set(name, factory);
+	}
+
+	public get registeredScenes(): string[] {
+		return Array.from(this.scenes.keys());
+	}
+
+	public async changeScene(name: string): Promise<void> {
+		if (this.currentScene) {
+			this.currentScene.stop();
+
+			// Stop any looping/playing background audio to prevent layer bleeding across scenes
+			const audioSources = this.engine.world.query(AudioSource);
+			for (const e of audioSources) {
+				const source = this.engine.world.getComponent(e, AudioSource);
+				if (source?._sourceNode) {
+					try {
+						source._sourceNode.stop();
+					} catch (_e) {
+						// Ignored if already stopped naturally
+					}
+				}
+			}
+
+			this.engine.world.clearEntities();
+		}
+
+		const factory = this.scenes.get(name);
+		if (!factory) {
+			throw new Error(`Scene '${name}' not found.`);
+		}
+
+		const scene = factory(this.engine);
+		this.currentScene = scene;
+		this.currentSceneName = name;
+
+		await scene.load();
+		scene.start();
+	}
+}

package/src/core/Storage.ts

@@ -0,0 +1,161 @@
+export class GameStorage {
+	private dbName: string;
+	private dbVersion: number;
+	private stores: string[];
+	private db: IDBDatabase | null = null;
+	private initPromise: Promise<void> | null = null;
+
+	constructor(
+		dbName = "aether_storage",
+		stores = ["saves", "settings", "global"],
+		dbVersion = 1,
+	) {
+		this.dbName = dbName;
+		this.stores = stores;
+		this.dbVersion = dbVersion;
+	}
+
+	/**
+	 * Initializes the IndexedDB connection and provisions stores.
+	 * This is called automatically by operations, but can be invoked manually to preload the DB.
+	 */
+	public async connect(): Promise<void> {
+		if (this.db) return;
+		if (this.initPromise) return this.initPromise;
+
+		this.initPromise = new Promise((resolve, reject) => {
+			if (typeof window === "undefined" || !window.indexedDB) {
+				console.warn("IndexedDB is not supported in this environment.");
+				reject(new Error("IndexedDB not supported"));
+				return;
+			}
+
+			const request = window.indexedDB.open(this.dbName, this.dbVersion);
+
+			request.onupgradeneeded = (event) => {
+				const db = (event.target as IDBOpenDBRequest).result;
+				for (const store of this.stores) {
+					if (!db.objectStoreNames.contains(store)) {
+						db.createObjectStore(store);
+					}
+				}
+			};
+
+			request.onsuccess = (event) => {
+				this.db = (event.target as IDBOpenDBRequest).result;
+
+				// Handle db errors globally
+				this.db.onerror = (e) => {
+					console.error(
+						"GameStorage Database error: ",
+						(e.target as IDBRequest).error,
+					);
+				};
+
+				resolve();
+			};
+
+			request.onerror = (event) => {
+				reject((event.target as IDBOpenDBRequest).error);
+			};
+		});
+
+		return this.initPromise;
+	}
+
+	private async getStore(
+		storeName: string,
+		mode: IDBTransactionMode = "readonly",
+	): Promise<IDBObjectStore> {
+		await this.connect();
+		if (!this.db) throw new Error("GameStorage: Database not connected.");
+
+		// If they query a generic store without creating it initially, we should inform them.
+		if (!this.db.objectStoreNames.contains(storeName)) {
+			throw new Error(`GameStorage: Store '${storeName}' does not exist.`);
+		}
+
+		const transaction = this.db.transaction(storeName, mode);
+		return transaction.objectStore(storeName);
+	}
+
+	/**
+	 * Save a value to a specific store instance.
+	 */
+	public async set<T>(storeName: string, key: string, value: T): Promise<void> {
+		const store = await this.getStore(storeName, "readwrite");
+
+		return new Promise((resolve, reject) => {
+			const request = store.put(value, key);
+			request.onsuccess = () => resolve();
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	/**
+	 * Retrieve a value from a specific store instance.
+	 */
+	public async get<T>(storeName: string, key: string): Promise<T | null> {
+		const store = await this.getStore(storeName, "readonly");
+
+		return new Promise((resolve, reject) => {
+			const request = store.get(key);
+			request.onsuccess = () => {
+				resolve(request.result !== undefined ? request.result : null);
+			};
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	/**
+	 * Delete a specific key from a store.
+	 */
+	public async delete(storeName: string, key: string): Promise<void> {
+		const store = await this.getStore(storeName, "readwrite");
+
+		return new Promise((resolve, reject) => {
+			const request = store.delete(key);
+			request.onsuccess = () => resolve();
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	/**
+	 * Clear all entries from a specific store.
+	 */
+	public async clear(storeName: string): Promise<void> {
+		const store = await this.getStore(storeName, "readwrite");
+
+		return new Promise((resolve, reject) => {
+			const request = store.clear();
+			request.onsuccess = () => resolve();
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	/**
+	 * Get all values within a specific store.
+	 */
+	public async getAll<T>(storeName: string): Promise<T[]> {
+		const store = await this.getStore(storeName, "readonly");
+
+		return new Promise((resolve, reject) => {
+			const request = store.getAll();
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => reject(request.error);
+		});
+	}
+
+	/**
+	 * Get all keys present in a specific store.
+	 */
+	public async getAllKeys(storeName: string): Promise<string[]> {
+		const store = await this.getStore(storeName, "readonly");
+
+		return new Promise((resolve, reject) => {
+			const request = store.getAllKeys();
+			request.onsuccess = () => resolve(request.result as string[]);
+			request.onerror = () => reject(request.error);
+		});
+	}
+}

package/src/desktop/SteamClient.ts

@@ -0,0 +1,52 @@
+import { invoke } from "@tauri-apps/api/core";
+
+/**
+ * A safe facade for interacting with Steam through Tauri's IPC.
+ * It degrades gracefully into no-ops if not running within a Tauri context,
+ * ensuring web builds do completely crash.
+ */
+export class SteamClient {
+    private static isTauri = Boolean(
+        typeof window !== "undefined" && (window as any).__TAURI_INTERNALS__
+    );
+
+    /**
+     * Initializes the Steam API. Should be called early in the game lifecycle.
+     */
+    static async init(): Promise<boolean> {
+        if (!this.isTauri) return false;
+        try {
+            return await invoke<boolean>("steam_init");
+        } catch (error) {
+            console.error("SteamClient: Failed to init Steam", error);
+            return false;
+        }
+    }
+
+    /**
+     * Unlocks a specific Steam achievement by name/ID.
+     * @param achievementId The identifier for the achievement.
+     */
+    static async unlockAchievement(achievementId: string): Promise<boolean> {
+        if (!this.isTauri) return false;
+        try {
+            return await invoke<boolean>("steam_unlock_achievement", { id: achievementId });
+        } catch (error) {
+            console.error(`SteamClient: Failed to unlock achievement ${achievementId}`, error);
+            return false;
+        }
+    }
+
+    /**
+     * Retrieves the current user's local Steam ID.
+     */
+    static async getSteamId(): Promise<string | null> {
+        if (!this.isTauri) return null;
+        try {
+            return await invoke<string>("steam_get_user");
+        } catch (error) {
+            console.error("SteamClient: Failed to get Steam User ID", error);
+            return null;
+        }
+    }
+}

package/src/ecs/System.ts

@@ -0,0 +1,11 @@
+import type { World } from "./World";
+
+export abstract class System {
+	constructor(public world: World) {}
+
+	/**
+	 * Called every frame
+	 * @param dt Delta time in seconds
+	 */
+	abstract update(dt: number): void;
+}

package/src/ecs/World.test.ts

@@ -0,0 +1,29 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { Transform } from "../components/Transform";
+import { World } from "./World";
+
+describe("ECS World Fundamentals", () => {
+	let world: World;
+
+	beforeEach(() => {
+		world = new World();
+	});
+
+	test("Entity creation and destruction", () => {
+		const e1 = world.createEntity();
+		expect(world.getEntityCount()).toBe(1);
+
+		world.destroyEntity(e1);
+		expect(world.getEntityCount()).toBe(0);
+	});
+
+	test("Component removal", () => {
+		const e1 = world.createEntity();
+		world.addComponent(e1, Transform);
+
+		expect(world.getComponent(e1, Transform)).toBeDefined();
+
+		world.removeComponent(e1, Transform);
+		expect(world.getComponent(e1, Transform)).toBeUndefined();
+	});
+});

package/src/ecs/World.ts

@@ -0,0 +1,149 @@
+export type Entity = number;
+export type ComponentClass<T = any> = { new (...args: any[]): T };
+
+export class World {
+	private nextEntityId: Entity = 1;
+	private entityPool: Entity[] = [];
+	private entities = new Set<Entity>();
+	private componentsByEntity = new Map<Entity, Map<ComponentClass, any>>();
+	private queries = new Map<
+		string,
+		{ componentClasses: ComponentClass[]; entities: Set<Entity>; cachedArray: Entity[] | null }
+	>();
+
+	createEntity(): Entity {
+		const id =
+			this.entityPool.length > 0 ? this.entityPool.pop()! : this.nextEntityId++;
+		this.entities.add(id);
+		const compMap = this.componentsByEntity.get(id);
+		if (!compMap) {
+			this.componentsByEntity.set(id, new Map());
+		} else {
+			compMap.clear();
+		}
+		return id;
+	}
+
+	clearEntities() {
+		this.entities.clear();
+		this.componentsByEntity.clear();
+		// We purposefully do not reset nextEntityId to avoid any potential dangling references grabbing a resurrected entity ID
+		this.entityPool = [];
+		for (const q of this.queries.values()) {
+			if (q.entities.size > 0) {
+				q.entities.clear();
+				q.cachedArray = null;
+			}
+		}
+	}
+
+	destroyEntity(entity: Entity) {
+		if (this.entities.has(entity)) {
+			this.entities.delete(entity);
+			this.componentsByEntity.get(entity)?.clear();
+
+			for (const q of this.queries.values()) {
+				if (q.entities.has(entity)) {
+					q.entities.delete(entity);
+					q.cachedArray = null;
+				}
+			}
+
+			this.entityPool.push(entity);
+		}
+	}
+
+	addComponent<T>(
+		entity: Entity,
+		componentClass: ComponentClass<T>,
+		...args: any[]
+	): T {
+		const map = this.componentsByEntity.get(entity);
+		if (!map) throw new Error(`Entity ${entity} does not exist`);
+		const component = new componentClass(...args);
+		map.set(componentClass, component);
+
+		for (const q of this.queries.values()) {
+			if (this.hasAllComponents(entity, q.componentClasses)) {
+				if (!q.entities.has(entity)) {
+					q.entities.add(entity);
+					q.cachedArray = null;
+				}
+			}
+		}
+
+		return component;
+	}
+
+	removeComponent<T>(entity: Entity, componentClass: ComponentClass<T>) {
+		const map = this.componentsByEntity.get(entity);
+		if (map?.has(componentClass)) {
+			map.delete(componentClass);
+
+			for (const q of this.queries.values()) {
+				if (!this.hasAllComponents(entity, q.componentClasses)) {
+					if (q.entities.has(entity)) {
+						q.entities.delete(entity);
+						q.cachedArray = null;
+					}
+				}
+			}
+		}
+	}
+
+	getComponent<T>(
+		entity: Entity,
+		componentClass: ComponentClass<T>,
+	): T | undefined {
+		return this.componentsByEntity.get(entity)?.get(componentClass);
+	}
+
+	private hasAllComponents(
+		entity: Entity,
+		componentClasses: ComponentClass[],
+	): boolean {
+		const map = this.componentsByEntity.get(entity);
+		if (!map) return false;
+		for (let i = 0; i < componentClasses.length; i++) {
+			if (!map.has(componentClasses[i])) return false;
+		}
+		return true;
+	}
+
+	query(...componentClasses: ComponentClass[]): Entity[] {
+		const key = componentClasses
+			.map((c) => c.name)
+			.sort()
+			.join("|");
+
+		let q = this.queries.get(key);
+		if (!q) {
+			const set = new Set<Entity>();
+			for (const entity of this.entities) {
+				if (this.hasAllComponents(entity, componentClasses)) {
+					set.add(entity);
+				}
+			}
+			q = { componentClasses, entities: set, cachedArray: Array.from(set) };
+			this.queries.set(key, q);
+		}
+
+		if (q.cachedArray === null) {
+			q.cachedArray = Array.from(q.entities);
+		}
+
+		return q.cachedArray;
+	}
+
+	getEntityCount() {
+		return this.entities.size;
+	}
+
+	getAllEntities(): Entity[] {
+		return Array.from(this.entities);
+	}
+
+	getComponentsForEntity(entity: Entity): Map<ComponentClass, any> | undefined {
+		return this.componentsByEntity.get(entity);
+	}
+}

package/src/index.ts

@@ -0,0 +1,115 @@
+import { GlobalAssets } from "./core/AssetManager";
+import { Input } from "./core/Input";
+import { SceneManager } from "./core/SceneManager";
+import { GameStorage } from "./core/Storage";
+import type { System } from "./ecs/System";
+import { World } from "./ecs/World";
+
+export interface EngineConfig {
+	storage?: {
+		dbName?: string;
+		stores?: string[];
+		dbVersion?: number;
+	};
+}
+
+export class AetherEngine {
+	public world: World;
+	public canvas: HTMLCanvasElement;
+	public stats = { fps: 0 };
+	public assets = GlobalAssets;
+	public sceneManager: SceneManager;
+	public storage: GameStorage;
+
+	private lastTime = 0;
+	private running = false;
+	private frameId = 0;
+	private systems: System[] = [];
+
+	constructor(canvas: HTMLCanvasElement, config?: EngineConfig) {
+		this.canvas = canvas;
+		this.world = new World();
+		this.sceneManager = new SceneManager(this);
+		this.storage = new GameStorage(
+			config?.storage?.dbName,
+			config?.storage?.stores,
+			config?.storage?.dbVersion,
+		);
+		Input.initialize();
+	}
+
+	public addSystem(system: System) {
+		this.systems.push(system);
+	}
+
+	public getSystems() {
+		return this.systems;
+	}
+
+	start() {
+		if (this.running) return;
+		this.running = true;
+		this.lastTime = performance.now();
+		this.loop(this.lastTime);
+	}
+
+	stop() {
+		this.running = false;
+		cancelAnimationFrame(this.frameId);
+	}
+
+	private loop = (time: number) => {
+		if (!this.running) return;
+
+		// Safety cap on dt to prevent physics/logic explosions during lag
+		let dt = (time - this.lastTime) / 1000;
+		if (dt > 0.1) dt = 0.1;
+
+		this.lastTime = time;
+
+		// Moving average for fps
+		this.stats.fps = this.stats.fps * 0.9 + (1 / dt) * 0.1;
+
+		for (const system of this.systems) {
+			system.update(dt);
+		}
+
+		Input.update();
+
+		this.frameId = requestAnimationFrame(this.loop);
+	};
+}
+
+export { AudioEngine } from "./audio/AudioEngine";
+export { Animator3D } from "./components/Animator3D";
+export { AudioSource } from "./components/AudioSource";
+export { BitmapText } from "./components/BitmapText";
+export { Camera } from "./components/Camera";
+export { CameraFollow } from "./components/CameraFollow";
+export { Collider } from "./components/Collider";
+export { Light } from "./components/Light";
+export { MeshRenderer } from "./components/MeshRenderer";
+export { ParticleEmitter } from "./components/ParticleEmitter";
+export { RigidBody } from "./components/RigidBody";
+export { ShadowCaster } from "./components/ShadowCaster";
+export { SkinnedMeshRenderer } from "./components/SkinnedMeshRenderer";
+export { SpriteAnimator } from "./components/SpriteAnimator";
+export { SpriteRenderer } from "./components/SpriteRenderer";
+export { Transform } from "./components/Transform";
+export { Input } from "./core/Input";
+export { Scene } from "./core/Scene";
+export { SceneManager } from "./core/SceneManager";
+export { GameStorage } from "./core/Storage";
+export { System } from "./ecs/System";
+export { World } from "./ecs/World";
+export { WebGLRenderer } from "./renderer/WebGLRenderer";
+export { Animation3DSystem } from "./systems/Animation3DSystem";
+export { AnimationSystem } from "./systems/AnimationSystem";
+export { AudioSystem } from "./systems/AudioSystem";
+export { LightingSystem } from "./systems/LightingSystem";
+export { ParticleSystem } from "./systems/ParticleSystem";
+export { PhysicsSystem } from "./systems/PhysicsSystem";
+export { TextSystem } from "./systems/TextSystem";
+export { GLTFLoader } from "./utils/GLTFLoader";
+export { ObjLoader } from "./utils/ObjLoader";
+export { SteamClient } from "./desktop/SteamClient";