From 47a6f396fa66d933fc65f6ba39c33086477d0a70 Mon Sep 17 00:00:00 2001 From: Dominic Masters Date: Sat, 6 Jun 2026 19:06:52 -0500 Subject: [PATCH] Fix typedefs --- types/engine/globals.d.ts | 24 +++++++++++++++++ types/entity/component/renderable.d.ts | 27 ++----------------- types/index.d.ts | 1 + types/require.d.ts | 36 +++++--------------------- types/scene/scene.d.ts | 31 ++++++++++++---------- 5 files changed, 51 insertions(+), 68 deletions(-) create mode 100644 types/engine/globals.d.ts diff --git a/types/engine/globals.d.ts b/types/engine/globals.d.ts new file mode 100644 index 00000000..3fc31def --- /dev/null +++ b/types/engine/globals.d.ts @@ -0,0 +1,24 @@ +/** + * Copyright (c) 2026 Dominic Masters + * + * This software is released under the MIT License. + * https://opensource.org/licenses/MIT + */ + +/** + * Returns a Promise that resolves on the next engine frame. + * + * @example + * await frame(); + * Console.print('one frame later'); + */ +declare function frame(): Promise; + +/** + * Returns a Promise that resolves after `ms` milliseconds of engine time. + * + * @example + * await timeout(500); + * Console.print('half a second later'); + */ +declare function timeout(ms: number): Promise; diff --git a/types/entity/component/renderable.d.ts b/types/entity/component/renderable.d.ts index d39196cf..11a0d77a 100644 --- a/types/entity/component/renderable.d.ts +++ b/types/entity/component/renderable.d.ts @@ -5,20 +5,12 @@ * https://opensource.org/licenses/MIT */ -/** Fields shared by every renderable type. */ +/** A Renderable component. Returned by `entity.add(Component.RENDERABLE)`. */ interface Renderable extends Component { /** Current render type — one of the `Renderable.*` type constants. */ type: number; /** Render priority. 0 = auto. Higher = drawn later. */ priority: number; - toString(): string; -} - -/** - * Renderable in `SHADER_MATERIAL` mode (default after `entity.add`). - * Renders a mesh with the unlit shader. - */ -interface RenderableMaterial extends Renderable { /** * Unlit material color. Reading returns a fresh `Color` copy; assigning * a `Color` instance writes through to the C material. @@ -28,22 +20,12 @@ interface RenderableMaterial extends Renderable { * r.color = new Color(255, 128, 0); */ color: Color; -} - -/** - * Renderable in `SPRITEBATCH` mode. - * - * Set `texture` to activate spritebatch rendering (also switches `type` - * to `Renderable.SPRITEBATCH` automatically). - */ -interface RenderableSpritebatch extends Renderable { /** * The bound texture. Assigning a `Texture` switches the renderable to * `SPRITEBATCH` mode and pins the object against GC. Reading returns the * same `Texture` instance that was assigned, or `undefined` if none. */ texture: Texture | undefined; - /** * Sprite list. Reading returns a JS array of 10-element sub-arrays * `[x1,y1,z1, x2,y2,z2, u1,v1, u2,v2]` — one per sprite. @@ -57,14 +39,9 @@ interface RenderableSpritebatch extends Renderable { * r.sprites = []; // clear */ sprites: number[][]; + toString(): string; } -/** - * Renderable in `CUSTOM` mode. - * Draw logic is provided by a C callback set via `entityRenderableSetDraw`. - */ -interface RenderableCustom extends Renderable {} - interface RenderableConstructor { readonly SHADER_MATERIAL: number; readonly SPRITEBATCH: number; diff --git a/types/index.d.ts b/types/index.d.ts index 9f50f77b..e185886b 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -33,6 +33,7 @@ // engine systems /// /// +/// /// /// /// diff --git a/types/require.d.ts b/types/require.d.ts index d278f291..d61878f6 100644 --- a/types/require.d.ts +++ b/types/require.d.ts @@ -6,10 +6,7 @@ */ /** - * CommonJS-style module loader. Accepts a single path or an array of paths. - * - * - Single string → returns that module's `exports`. - * - Array of strings → returns an array of `exports` in the same order. + * CommonJS-style module loader. * * Modules are cached after their first load. Subsequent calls with the same * resolved path return the cached exports without re-executing the file. @@ -20,41 +17,22 @@ * * @example * const NPC = require('./entities/NPC'); - * const [NPC, Item] = require(['./entities/NPC', './entities/Item']); */ declare function require(path: string): any; -declare function require(paths: string[]): any[]; /** - * Asynchronous module loader. Accepts a single path or an array of paths. - * The asset file(s) are read in the background; once all are loaded and - * evaluated, `callback` is invoked. + * Asynchronous module loader. Loads the module at `path` in the background + * and returns a Promise that resolves to the module's `exports`. * - * - Single string → `callback(exports)` — first argument is the module's - * `exports`, or `null` on load failure. - * - Array of strings → `callback(exportsArray)` — first argument is an array - * of `exports` values in the same order; failed entries are `null`. + * If the module is already cached it resolves immediately. On load failure + * the Promise is rejected. * - * Cached modules resolve synchronously (callback fires on the same call). * Path rules are identical to `require`. * * @example - * requireAsync('./entities/NPC', function(NPC) { - * if(NPC) NPC.init(); - * }); - * - * requireAsync(['./entities/NPC', './entities/Item'], function(mods) { - * const [NPC, Item] = mods; - * }); + * const NPC = await requireAsync('./entities/NPC'); */ -declare function requireAsync( - path: string, - callback: (exports: any) => void -): void; -declare function requireAsync( - paths: string[], - callback: (exports: any[]) => void -): void; +declare function requireAsync(path: string): Promise; /** * The module object for the currently executing script. diff --git a/types/scene/scene.d.ts b/types/scene/scene.d.ts index 5a82f691..b64e77ed 100644 --- a/types/scene/scene.d.ts +++ b/types/scene/scene.d.ts @@ -12,18 +12,14 @@ * @example * // assets/scenes/game.js * var scene = {}; - * var batch = AssetBatch([{ path: 'tex/bg.png', type: Asset.TYPE_TEXTURE }]); * - * scene.load = function() { return batch; }; * scene.init = function() { Console.print('scene started'); }; * scene.update = function() { /* per-frame logic *\/ }; - * scene.dispose = function() { batch.unlock(); }; + * scene.dispose = function() { }; * * module.exports = scene; */ interface SceneObject { - /** Return an AssetBatch to preload before init is called. Optional. */ - load?(): AssetBatch | undefined; /** Called when this scene becomes active. Optional. */ init?(): void; /** Called every frame while this scene is active. Optional. */ @@ -34,20 +30,27 @@ interface SceneObject { /** Scene management. */ interface SceneNamespace { - /** `true` while a JS script scene is running. */ - readonly active: boolean; + /** The currently active scene object, or `null` if none. */ + current: SceneObject | null; /** - * Loads the JS module at `path`, waits for any `AssetBatch` returned by - * `scene.load()`, then activates the scene (calling `scene.init()`). - * The previous scene's `dispose()` is called just before `init()`. - * - * Returns immediately — the transition is asynchronous. + * Replaces the active scene. Calls `dispose()` on the previous scene (if + * any), then calls `init()` on the new one. Pass `null` to clear. * * @example - * Scene.set('assets/scenes/game.js'); + * const myScene = require('./scenes/game'); + * Scene.set(myScene); */ - set(path: string): void; + set(newScene: SceneObject | null): void; + + /** Called each frame by the engine — drives `current.update()`. */ + update(): void; + + /** Called each frame by the engine for dynamic/physics updates. */ + dynamicUpdate(): void; + + /** Disposes the current scene and sets `current` to `null`. */ + dispose(): void; } declare var Scene: SceneNamespace;