@whatever-engine/api 0.1.1 → 0.2.1

package/README.md

@@ -5,14 +5,14 @@ TypeScript scripting API for Whatever Engine mods. Abstracts the NDJSON IPC prot
 ## Usage
 
 ```ts
-import { Engine, Window, Scene, Assets, File, Mods, Message, Console } from "@whatever-engine/api";
+import { Engine, Window, File, Scene, Entity, Mods, Message, Console } from "@whatever-engine/api";
 
 Engine.on("init", ({ mod_id }) => {
   Engine.log("info", `loaded as ${mod_id}`);
 });
 
-Engine.on("frame", ({ delta_seconds }) => {
-  // per-frame logic
+Engine.on("tick", async ({ delta_seconds }) => {
+  // game logic — engine waits for this Promise before advancing
 });
 ```
 
@@ -22,22 +22,17 @@ No install step needed — Bun resolves the package automatically for any script
 
 ### `Engine`
 
-- `Engine.on(event, handler)` — subscribe to an engine event (`init`, `exit`, `frame`, `input`, `asset_response`, `mod_message`)
+- `Engine.on(event, handler)` — subscribe to an engine event (`init`, `exit`, `tick`, `mod_message`)
 - `Engine.log(level, message)` — log through the engine logger (`"info"`, `"warn"`, `"error"`)
+- `Engine.setTickRate(ticks_per_second)` — override the game tick rate at runtime
+- `Engine.setFpsCap(fps | null)` — set FPS cap; `null` = uncapped
+- `Engine.setVsync(enabled)` — enable or disable vertical sync
 
 ### `Window`
 
 - `Window.setTitle(title)` — change the window title
-
-### `Scene`
-
-- `Scene.spawnSprite(entity_id, texture, position, scale?)` — spawn a textured sprite
-- `Scene.moveEntity(entity_id, position)` — move an entity to a new world-space position
-- `Scene.destroyEntity(entity_id)` — remove an entity from the scene
-
-### `Assets`
-
-- `Assets.request(request_id, path)` — request raw asset bytes from the VFS; result arrives as an `asset_response` event
+- `Window.setSize(width, height)` — request a new inner size in physical pixels (no-op in fullscreen modes)
+- `Window.setMode(mode)` — set display mode: `"windowed"`, `"borderless"`, or `"fullscreen"`
 
 ### `File`
 
@@ -47,6 +42,52 @@ Sandboxed per-mod file I/O. Paths must not contain `..`.
 - `File.read(path)` → `Promise<string>`
 - `File.delete(path)` → `Promise<void>`
 
+### `Entity`
+
+A live entity in the scene. Returned by `Scene.createEntity`, `Scene.listEntities`, `Scene.query`, and `Scene.spawnSprite`. For built-in component types the data parameter/return is automatically typed; for custom component types a generic `T` can be supplied.
+
+- `entity.id` — opaque entity ID string
+- `entity.destroy()` — fire-and-forget
+- `entity.setComponent(component_type, data)` — fire-and-forget; typed for built-in components
+- `entity.removeComponent(component_type)` — fire-and-forget
+- `entity.getComponent(component_type)` → `Promise<T | null>` — typed for built-in components
+- `entity.move(position)` → `Promise<void>` — update `core:transform` position, preserve rotation/scale
+
+### `Scene`
+
+Entity and component management. Methods that accept a raw `entity_id` string are provided for cases where only an ID is available; prefer `Entity` methods when possible.
+
+- `Scene.createEntity()` → `Promise<Entity>`
+- `Scene.destroyEntity(entity_id)` — fire-and-forget
+- `Scene.listEntities()` → `Promise<Entity[]>`
+- `Scene.setComponent(entity_id, component_type, data)` — fire-and-forget; typed for built-in components
+- `Scene.removeComponent(entity_id, component_type)` — fire-and-forget
+- `Scene.getComponent(entity_id, component_type)` → `Promise<T | null>` — typed for built-in components
+- `Scene.query(component_types)` → `Promise<QueryResult[]>` — each row has `entity: Entity` and `components`
+- `Scene.spawnSprite(texture, position, scale?)` → `Promise<Entity>` — convenience
+- `Scene.moveEntity(entity_id, position)` → `Promise<void>` — convenience
+
+Built-in component types: `core:transform`, `core:sprite_renderer`. `getComponent` for built-in types returns a **live class instance** with methods — not a plain object.
+
+### `BuiltInComponents.Transform`
+
+Methods (all setters chainable, return `this`):
+
+- `getX/Y/Z()`, `setX/Y/Z(v)` — individual position components
+- `getPosition()` → `[x, y, z]`, `setPosition(x, y, z)` — full position
+- `getScaleX/Y/Z()`, `setScaleX/Y/Z(v)` — individual scale components
+- `getScale()` → `[x, y, z]`, `setScale(x, y, z)`, `setScaleUniform(s)` — full scale
+- `getRotation()` → `[x, y, z, w]`, `setRotation(x, y, z, w)` — raw quaternion
+- `getEulerRadians/Degrees()` → `[rx, ry, rz]` — intrinsic XYZ decomposition
+- `setEulerRadians/Degrees(rx, ry, rz)` — set from intrinsic XYZ Euler angles
+- `rotateX/Y/Z(degrees)` — incremental world-space rotation around axis
+- `distance(other)` → `number` — Euclidean distance between positions
+
+### `BuiltInComponents.SpriteRenderer`
+
+- `getTexture()`, `setTexture(path)` — VFS texture path
+- `getZIndex()`, `setZIndex(z)` — draw order
+
 ### `Mods`
 
 - `Mods.list()` → `Promise<ModManifest[]>` — all loaded mods in load order

package/dist/index.d.ts

@@ -0,0 +1,390 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/** Base interface for all components. */
+export interface Component {
+	id: string;
+}
+/** Arbitrary JSON-serializable value used for inter-mod messages and components. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+	[key: string]: JsonValue;
+};
+/** Metadata about a loaded mod, mirroring mod.toml. */
+export type ModManifest = {
+	id: string;
+	name: string;
+	version: string;
+	description: string;
+	authors: string[];
+	license: string;
+	dependencies: Record<string, string>;
+	load_order: {
+		after: string[];
+		before: string[];
+	};
+	script?: {
+		entry: string;
+		runtime: string;
+	};
+};
+/** Payload types for each public event name. */
+export type EventPayloads = {
+	/** Fired once after the engine has initialised and the window is ready. */
+	init: {
+		mod_id: string;
+		engine_version: string;
+	};
+	/** Fired when the game is shutting down. The process exits after all handlers return. */
+	exit: {
+		exit_code: number;
+	};
+	/**
+	 * Fired every game tick. All async handlers are awaited before the engine advances.
+	 * Subscribe by calling `Engine.on("tick", handler)`.
+	 */
+	tick: {
+		tick_number: number;
+		delta_seconds: number;
+		keys_pressed: string[];
+		mouse_delta: [
+			number,
+			number
+		];
+	};
+	/**
+	 * Fired when another mod sends this mod a message via `Message.send`.
+	 * If `request_id` is present the sender is awaiting a reply — call `Message.reply(request_id, data)`.
+	 * Not fired for replies that arrive via the `Message.send(id, msg, timeout)` overload.
+	 */
+	mod_message: {
+		source_mod_id: string;
+		message: JsonValue;
+		request_id?: string;
+	};
+};
+export type EventName = keyof EventPayloads;
+/** One row returned by `Scene.query`. */
+export type QueryResult<E> = {
+	entity: E;
+	components: Record<string, JsonValue>;
+};
+/** Core engine events and logging. */
+export declare const Engine: {
+	/**
+	 * Subscribe to an engine event. The handler is called each time the event fires.
+	 * For `tick`, async handlers are awaited before the engine advances the simulation.
+	 * Registering a handler also sends a `Subscribe` message to the engine automatically
+	 * (except `mod_message`, which the engine routes unconditionally).
+	 */
+	on<E extends EventName>(event: E, handler: (payload: EventPayloads[E]) => void | Promise<void>): void;
+	/** Log a message via the engine logger. Output includes timestamp and mod ID. */
+	log(level: "info" | "warn" | "error", message: string): void;
+	/** Override the game tick rate. Takes effect immediately. */
+	setTickRate(ticks_per_second: number): void;
+	/** Set the FPS cap. Pass `null` to remove the cap (uncapped). */
+	setFpsCap(fps: number | null): void;
+	/** Enable or disable vertical sync. Takes effect immediately. */
+	setVsync(enabled: boolean): void;
+};
+export type WindowMode = "windowed" | "borderless" | "fullscreen";
+/** Window management. */
+export declare const Window: {
+	/** Set the title of the active window. */
+	setTitle(title: string): void;
+	/** Request a new inner window size in physical pixels. Has no effect in fullscreen modes. */
+	setSize(width: number, height: number): void;
+	/**
+	 * Set the window display mode.
+	 * - `"windowed"` — normal window
+	 * - `"borderless"` — borderless fullscreen (windowed fullscreen)
+	 * - `"fullscreen"` — exclusive fullscreen using the monitor's preferred video mode;
+	 *   falls back to borderless if no exclusive mode is available
+	 */
+	setMode(mode: WindowMode): void;
+};
+/** Sandboxed per-mod file I/O. Paths must not contain `..`. */
+declare const File$1: {
+	/** Write a UTF-8 string to a sandboxed file for this mod. */
+	write(path: string, data: string): Promise<void>;
+	/** Read a sandboxed file for this mod and return its contents as a UTF-8 string. */
+	read(path: string): Promise<string>;
+	/** Delete a sandboxed file for this mod. */
+	delete(path: string): Promise<void>;
+};
+export declare namespace BuiltInComponents {
+	const TRANSFORM_ID = "core:transform";
+	const SPRITE_RENDERER_ID = "core:sprite_renderer";
+	/** Transform component. Returned by `getComponent("core:transform")` as a live class instance. */
+	class Transform implements Component {
+		readonly id = "core:transform";
+		position: [
+			number,
+			number,
+			number
+		];
+		rotation: [
+			number,
+			number,
+			number,
+			number
+		];
+		scale: [
+			number,
+			number,
+			number
+		];
+		constructor(init?: {
+			position?: [
+				number,
+				number,
+				number
+			];
+			rotation?: [
+				number,
+				number,
+				number,
+				number
+			];
+			scale?: [
+				number,
+				number,
+				number
+			];
+		});
+		getX(): number;
+		setX(x: number): this;
+		addX(x: number): this;
+		getY(): number;
+		setY(y: number): this;
+		addY(y: number): this;
+		getZ(): number;
+		setZ(z: number): this;
+		addZ(z: number): this;
+		/** Returns a copy of the position as [x, y, z]. */
+		getPosition(): [
+			number,
+			number,
+			number
+		];
+		/** Set all three position components at once. Chainable. */
+		setPosition(x: number, y: number, z: number): this;
+		getScaleX(): number;
+		setScaleX(x: number): this;
+		getScaleY(): number;
+		setScaleY(y: number): this;
+		getScaleZ(): number;
+		setScaleZ(z: number): this;
+		/** Returns a copy of the scale tuple. */
+		getScale(): [
+			number,
+			number,
+			number
+		];
+		/** Set all three scale components. Chainable. */
+		setScale(x: number, y: number, z: number): this;
+		/** Set all three scale components to the same value. Chainable. */
+		setScaleUniform(s: number): this;
+		/** Euclidean distance between this transform's position and another's. */
+		distance(other: Transform): number;
+		/** Returns a copy of the raw quaternion as [x, y, z, w]. */
+		getRotation(): [
+			number,
+			number,
+			number,
+			number
+		];
+		/** Set the raw quaternion directly. Chainable. */
+		setRotation(x: number, y: number, z: number, w: number): this;
+		/**
+		 * Decompose the current quaternion into intrinsic XYZ Euler angles in radians.
+		 * Returns [rx, ry, rz] — pitch around X, then yaw around Y, then roll around Z.
+		 * Near gimbal-lock (ry ≈ ±90°) rx and rz may be unstable.
+		 */
+		getEulerRadians(): [
+			number,
+			number,
+			number
+		];
+		/**
+		 * Set rotation from intrinsic XYZ Euler angles in radians (equivalent to extrinsic ZYX,
+		 * i.e. q = Qz·Qy·Qx). Consistent with `getEulerRadians`. Chainable.
+		 */
+		setEulerRadians(rx: number, ry: number, rz: number): this;
+		/** Decompose the current quaternion into intrinsic XYZ Euler angles in degrees. */
+		getEulerDegrees(): [
+			number,
+			number,
+			number
+		];
+		/** Set rotation from intrinsic XYZ Euler angles in degrees. Chainable. */
+		setEulerDegrees(x: number, y: number, z: number): this;
+		/** Rotate by `degrees` around the world X axis. Chainable. */
+		rotateX(degrees: number): this;
+		/** Rotate by `degrees` around the world Y axis. Chainable. */
+		rotateY(degrees: number): this;
+		/** Rotate by `degrees` around the world Z axis. Chainable. */
+		rotateZ(degrees: number): this;
+		private _leftMultiply;
+	}
+	/** SpriteRenderer component. Returned by `getComponent("core:sprite_renderer")` as a live class instance. */
+	class SpriteRenderer implements Component {
+		readonly id = "core:sprite_renderer";
+		texture: string;
+		z_index: number;
+		constructor(init?: {
+			texture?: string;
+			z_index?: number;
+		});
+		getTexture(): string;
+		setTexture(texture: string): this;
+		getZIndex(): number;
+		setZIndex(z: number): this;
+	}
+}
+export interface _ComponentRegistry {
+	[BuiltInComponents.TRANSFORM_ID]: BuiltInComponents.Transform;
+	[BuiltInComponents.SPRITE_RENDERER_ID]: BuiltInComponents.SpriteRenderer;
+}
+export interface _ComponentSetRegistry {
+	[BuiltInComponents.TRANSFORM_ID]: {
+		position: [
+			number,
+			number,
+			number
+		];
+		rotation: [
+			number,
+			number,
+			number,
+			number
+		];
+		scale: [
+			number,
+			number,
+			number
+		];
+	};
+	[BuiltInComponents.SPRITE_RENDERER_ID]: {
+		texture: string;
+		z_index: number;
+	};
+}
+declare function _setComponentImpl<K extends keyof _ComponentSetRegistry>(entity_id: string, component_type: K, data: _ComponentSetRegistry[K]): void;
+declare function _setComponentImpl(entity_id: string, component_type: string, data: JsonValue): void;
+declare function _getComponentImpl<K extends keyof _ComponentRegistry>(entity_id: string, component_type: K): Promise<_ComponentRegistry[K] | null>;
+declare function _getComponentImpl<T extends Component = Component>(entity_id: string, component_type: string): Promise<T | null>;
+/** A live entity in the scene. Wraps an entity ID and provides component access. */
+export declare class Entity {
+	readonly id: string;
+	constructor(id: string);
+	/** Destroy this entity and all its components. Fire-and-forget. */
+	destroy(): void;
+	/** Set a component on this entity. Fire-and-forget. */
+	setComponent<K extends keyof _ComponentSetRegistry>(component_type: K, data: _ComponentSetRegistry[K]): void;
+	setComponent(component_type: string, data: JsonValue): void;
+	/** Remove a component from this entity. Fire-and-forget. */
+	removeComponent(component_type: string): void;
+	/** Get a component's data. Returns `null` if the component is not set. */
+	getComponent<K extends keyof _ComponentRegistry>(component_type: K): Promise<_ComponentRegistry[K] | null>;
+	getComponent<T extends Component = Component>(component_type: string): Promise<T | null>;
+	/**
+	 * Convenience: update the `position` field of this entity's `core:transform`
+	 * while preserving existing rotation and scale.
+	 */
+	move(position: [
+		number,
+		number,
+		number
+	]): Promise<void>;
+}
+/** Entity and component management. */
+export declare const Scene: {
+	/** Create a new entity and return it. */
+	createEntity(): Promise<Entity>;
+	/** Destroy an entity and all its components. Fire-and-forget. */
+	destroyEntity(entity_id: string): void;
+	/** Return all living entities. */
+	listEntities(): Promise<Entity[]>;
+	/** Set a component on an entity by ID. Fire-and-forget. */
+	setComponent: typeof _setComponentImpl;
+	/** Remove a component from an entity. Fire-and-forget. */
+	removeComponent(entity_id: string, component_type: string): void;
+	/** Get a component's data by entity ID. Returns `null` if the component is not set. */
+	getComponent: typeof _getComponentImpl;
+	/** Query all entities that have every listed component type. */
+	query(component_types: string[]): Promise<QueryResult<Entity>[]>;
+	/**
+	 * Convenience: create an entity and attach `core:transform` + `core:sprite_renderer`.
+	 * The sprite becomes visible as soon as both components are set.
+	 */
+	spawnSprite(texture: string, position: [
+		number,
+		number,
+		number
+	], scale?: [
+		number,
+		number,
+		number
+	]): Promise<Entity>;
+	/**
+	 * Convenience: move an entity by updating the `position` field of its `core:transform`
+	 * while preserving existing rotation and scale.
+	 */
+	moveEntity(entity_id: string, position: [
+		number,
+		number,
+		number
+	]): Promise<void>;
+};
+/** Query information about loaded mods. */
+export declare const Mods: {
+	/** Returns the manifests of all currently loaded mods in load order. */
+	list(): Promise<ModManifest[]>;
+	/** Returns the manifest for a specific mod by ID. Rejects if the mod is not loaded. */
+	get(id: string): Promise<ModManifest>;
+};
+export interface _MessageNamespace {
+	/** Send a fire-and-forget message to another mod. */
+	sendAndForget<T extends JsonValue>(id: string, message: T): void;
+	/**
+	 * Send a message to another mod and wait for a reply.
+	 * The receiving mod's handler must return a non-null value within `timeout` ms.
+	 * Rejects with a timeout error if no reply arrives in time.
+	 */
+	send<T extends JsonValue, U extends JsonValue>(id: string, message: T, timeout: number): Promise<U>;
+	/**
+	 * Register a handler for incoming mod messages.
+	 * Return a `JsonValue` to reply (only meaningful when the sender used `send`); return `null` to ignore.
+	 * The `request_id` in the payload is an opaque engine token — do not inspect or store it.
+	 */
+	registerMessageHandler(handler: (payload: EventPayloads["mod_message"]) => JsonValue | null): void;
+}
+/** Inter-mod communication. */
+export declare const Message: _MessageNamespace;
+/** Public arg type for Console.register(). */
+export type ArgType = "string" | "int" | "float" | "bool";
+/** Argument specification for a command. */
+export type ArgSpec = {
+	name: string;
+	type: ArgType;
+	required?: boolean;
+	description?: string;
+};
+/** A command or subcommand specification. */
+export type CommandSpec = {
+	name: string;
+	description?: string;
+	subcommands?: CommandSpec[];
+	args?: ArgSpec[];
+	handler?: (args: Record<string, string | number | boolean>) => string | string[] | Promise<string | string[]>;
+};
+/** Register a command that users can invoke from the developer console. */
+declare const Console$1: {
+	register(spec: CommandSpec): void;
+};
+
+export {
+	Console$1 as Console,
+	File$1 as File,
+};
+
+export {};