@bloopjs/toodle 0.0.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 bloop games
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# toodle
+
+A portmanteau of "2d" and "doodle", toodle is a simple 2d graphics engine focused on using WebGPU to render textured quads and text.
+
+Full documentation is available at [toodle.gg](https://toodle.gg).
+
+```ts
+import { Toodle, Limits } from "@bloop.gg/toodle";
+
+// attach to an html canvas element
+const canvas = document.createElement("canvas");
+await Toodle.attach(canvas);
+
+// load textures into a webgpu texture atlas
+await toodle.assets.loadTexture(
+  "test",
+  new URL(
+    "https://upload.wikimedia.org/wikipedia/commons/thumb/b/bc/Juvenile_Ragdoll.jpg/440px-Juvenile_Ragdoll.jpg"
+  )
+);
+
+// reference assets by id and render up to 2048 quads with a single draw call
+const quad = toodle.Quad("test", { size: [200, 200] });
+
+toodle.startFrame();
+toodle.draw(world);
+toodle.endFrame();
+```
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run dev
+```
+
+---
+
+This project was created using `bun init` in bun v1.1.34. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/dist/Toodle.d.ts

@@ -0,0 +1,304 @@
+import type { Color } from "./coreTypes/Color";
+import type { Point } from "./coreTypes/Point";
+import type { Limits, LimitsOptions } from "./limits";
+import { Batcher } from "./scene/Batcher";
+import { Camera } from "./scene/Camera";
+import { JumboQuadNode, type JumboQuadOptions } from "./scene/JumboQuadNode";
+import { QuadNode, type QuadOptions } from "./scene/QuadNode";
+import { type NodeOptions, SceneNode } from "./scene/SceneNode";
+import type { Resolution } from "./screen/resolution";
+import type { IShader } from "./shaders/IShader";
+import type { PostProcess } from "./shaders/postprocess/mod";
+import { QuadShader, type QuadShaderOpts } from "./shaders/QuadShader";
+import { TextNode, type TextOptions } from "./text/TextNode";
+import { AssetManager, type TextureId } from "./textures/AssetManager";
+export declare class Toodle {
+    #private;
+    /**
+     * Asset manager. Use toodle.assets.loadTexture to load texture assets.
+     */
+    assets: AssetManager;
+    /**
+     * diagnostics can be used as a rough gauge for performance.
+     * besides frames, these stats are reset at the beginning of each frame.
+     */
+    diagnostics: {
+        /** number of instanced draw calls issued last frame. lower is better */
+        drawCalls: number;
+        /** number of pipeline switches last frame. lower is better. to reduce pipeline switches, use fewer z-indexes or fewer custom shaders */
+        pipelineSwitches: number;
+        /** number of frames rendered */
+        frames: number;
+        /** number of instances enqueued last frame */
+        instancesEnqueued: number;
+    };
+    /** sometimes for debugging you might want to access the GPU device, this should not be necessary in normal operation */
+    debug: {
+        device: GPUDevice;
+        presentationFormat: GPUTextureFormat;
+    };
+    /**
+     * Camera. This applies a 2d perspective projection matrix to any nodes drawn with toodle.draw
+     */
+    camera: Camera;
+    /**
+     * clearColor is the color that will be used to clear the screen at the beginning of each frame
+     * you can also think of this as the background color of the canvas
+     */
+    clearColor: Color;
+    /**
+     * it's unlikely that you want to use the constructor directly.
+     * see {@link Toodle.attach} for creating a Toodle instance that draws to a canvas.
+     */
+    constructor(device: GPUDevice, context: GPUCanvasContext, presentationFormat: GPUTextureFormat, canvas: HTMLCanvasElement, resolution: Resolution, options: ToodleOptions);
+    /**
+     * Screen shader is an optional slot for post-processing effects.
+     * Note that this will do the main render pass to an offscreen texture, which may impact performance.
+     */
+    get postprocess(): PostProcess | null;
+    set postprocess(value: PostProcess | null);
+    /**
+     * call resize when the canvas is resized.
+     * this will update the projection matrix and the resolution.
+     *
+     * @param resolution - the resolution of the canvas in logical pixels.
+     * this should be `canvas.clientWidth x canvas.clientHeight` and NOT `canvas.width * canvas.height`
+     *
+     * @example
+     *
+     *  const canvas = document.querySelector("canvas")!
+     *
+     *  const observer = new ResizeObserver((entries) => {
+     *   if (entries.length === 0) return
+     *   toodle.resize({ width: canvas.clientWidth, height: canvas.clientHeight })
+     *  })
+     *
+     *  observer.observe(canvas)
+     */
+    resize(resolution: Resolution): void;
+    /**
+     * The resolution of the canvas in css or logical pixels.
+     *
+     * @example
+     *
+     * // devicePixelRatio is 1, resolution is 200x200
+     * <canvas width="200" height="200" style="width: 200px; height: 200px;"></canvas>
+     * // devicePixelRatio is 2, resolution is 100x100
+     * <canvas width="200" height="200" style="width: 100px; height: 100px;"></canvas>
+     */
+    get resolution(): Resolution;
+    /**
+     * Returns the currently configured Toodle engine limits
+     *
+     * See: https://toodle.gg/f849595b3ed13fc956fc1459a5cb5f0228f9d259/limits.html
+     *
+     * @example
+     *
+     * const instanceLimit: number = toodle.limits.instanceCount;
+     */
+    get limits(): Limits;
+    get batcher(): Batcher;
+    /**
+     * The maximum number of pixels that can be loaded into texture atlases for this toodle instance.
+     */
+    get maxPixels(): number;
+    /**
+     * The maximum amount of GPU memory that will be used by the Toodle instance.
+     * This is a rough estimate and may not be exact. This will be allocated up front when calling Toodle.attach, and freed when calling toodle.destroy.
+     */
+    get maxGpuMemory(): number;
+    /**
+     * call startFrame before drawing anything.
+     * this will create a new encoder and render pass.
+     *
+     * @example
+     *
+     * toodle.startFrame();
+     * // draw stuff
+     * toodle.endFrame();
+     */
+    startFrame(options?: StartFrameOptions): void;
+    /**
+     * call draw in between start frame and end frame to enqueue an instanced draw call.
+     *
+     * @example
+     *
+     * toodle.assets.loadTexture("myImage", "assets/image.png");
+     * const quad = toodle.Quad("myImage");
+     *
+     * toodle.startFrame();
+     * toodle.draw(quad);
+     * toodle.endFrame();
+     */
+    draw(node: SceneNode): void;
+    /**
+     * call end frame to run through enqueued draw calls and submit them to the GPU.
+     *
+     * @example
+     *
+     * toodle.startFrame();
+     * // draw stuff
+     * toodle.endFrame();
+     */
+    endFrame(): void;
+    /**
+     * Convert a point from one coordinate space to another.
+     *
+     * @param point - The point to convert.
+     * @param options - The options for the conversion.
+     * @returns The converted point.
+     */
+    convertSpace(point: Point, options: {
+        from: "screen" | "world";
+        to: "world" | "screen";
+    }): Point;
+    /**
+     * The number of frames rendered since this Toodle instance was created.
+     */
+    get frameCount(): number;
+    /**
+     * Create a custom shader for quad instances. In some engines, this might be called a material.
+     *
+     * @param label Debug name of the shader
+     * @param instanceCount - The maximum number of instances that will be processed by the shader. Note that a worst-case buffer of this many instances will be immediately allocated.
+     * @param userCode - The WGSL code to be used for the shader.
+     * @param blendMode - The blend mode to be used for the shader.
+     *
+     * @example
+     *
+     *
+     */
+    QuadShader(label: string, instanceCount: number, userCode: string, shaderOpts?: QuadShaderOpts): QuadShader;
+    /**
+     * Create a new quad node.
+     *
+     * @param assetId - The ID of the asset to use for the quad. This must have been loaded with toodle.assets.loadBundle.
+     *
+     * @param options - QuadOptions for Quad creation
+     * @param options
+     * @example
+     *
+     * await toodle.assets.loadTextures({
+     *   "myImage": new URL("assets/image.png"),
+     * });
+     * const quad = toodle.Quad("myImage");
+     *
+     * toodle.startFrame();
+     * toodle.draw(quad);
+     * toodle.endFrame();
+     */
+    Quad(assetId: TextureId, options?: QuadOptions): QuadNode;
+    /**
+     * Create a jumbo quad node. This contains multiple tiles for a single texture.
+     *
+     * @param assetId - The ID of the asset to use for the jumbo quad. This must have been loaded with toodle.assets.loadTextures.
+     *
+     * @param options - QuadOptions for Quad creation
+     *
+     */
+    JumboQuad(assetId: TextureId, options: JumboQuadOptions): JumboQuadNode;
+    /**
+     * Create a new container node.
+     *
+     * @example
+     *
+     * const node = toodle.Node();
+     * const child = node.add(toodle.Node());
+     * node.position = [100, 100];
+     * console.log(child.matrix);
+     */
+    Node(nodeOpts?: NodeOptions): SceneNode;
+    Text(fontId: string, text: string, textOpts?: TextOptions): TextNode;
+    shapes: {
+        Rect: (options?: QuadOptions) => QuadNode;
+        Circle: (options?: QuadOptions) => QuadNode;
+        Line: (options: LineOptions) => QuadNode;
+    };
+    /**
+     * Attach toodle to a canvas.
+     *
+     * @param canvas - The canvas to attach toodle to.
+     * @param options - ToodleOptions for the creation of the toodle instance
+     * @returns A promise that resolves to a Toodle instance.
+     *
+     * @example
+     *
+     *   const canvas = document.createElement("canvas");
+     *
+     *   const toodle = await Toodle.attach(canvas);
+     */
+    static attach(canvas: HTMLCanvasElement, options?: ToodleOptions): Promise<Toodle>;
+    /**
+     * Destroy the toodle instance and release its gpu and cpu resources.
+     *
+     * Note that calling any methods on the instance after this result in undefined behavior.
+     */
+    destroy(): void;
+    /**
+     * Advanced and niche features
+     */
+    extra: {
+        /**
+         * Get the GPU device used by this Toodle instance.
+         */
+        device: () => GPUDevice;
+    };
+}
+export type StartFrameOptions = {
+    /**
+     * The load operation to use for the render pass.
+     *
+     * **clear**: clear the current texture to the clear color. necessary if you're using toodle without another renderer.
+     *
+     * **load**: blend the render pass with the current canvas contents. useful if you're using toodle alongside another renderer like painter or pixi.js
+     *
+     * @default "clear"
+     *
+     */
+    loadOp?: "load" | "clear";
+};
+export type ToodleOptions = {
+    /**
+     * The filter mode to use for the default quad shader.
+     * see: https://webgpufundamentals.org/webgpu/lessons/webgpu-textures.html#a-mag-filter
+     *
+     * **nearest**: nearest neighbor sampling. makes pixel art look sharp and vector art look jaggy.
+     *
+     * **linear**: linear sampling. makes vector art look smooth and pixel art look blurry.
+     *
+     * @default "linear"
+     */
+    filter?: "nearest" | "linear";
+    limits?: LimitsOptions;
+};
+export type LineOptions = {
+    /**
+     * The start position of the line.
+     */
+    start: Point;
+    /**
+     * The end position of the line.
+     */
+    end: Point;
+    /**
+     * The color of the line.
+     */
+    color: Color;
+    /**
+     * The thickness of the line.
+     */
+    thickness?: number;
+    /**
+     * The shader to use for the line.
+     */
+    shader?: IShader;
+    /**
+     * The layer to draw the line on.
+     */
+    layer?: number;
+    /**
+     * A unique identifier for the line.
+     */
+    key?: string;
+};
+//# sourceMappingURL=Toodle.d.ts.map

package/dist/Toodle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Toodle.d.ts","sourceRoot":"","sources":["../src/Toodle.ts"],"names":[],"mappings":"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"}