@mafiahub/types 0.1.4 → 0.1.6

package/core/color.d.ts

@@ -4,31 +4,52 @@ declare namespace Core {
      * Use `Color.fromRGB()` to construct from 0-255 values.
      */
     class Color {
+        /** Create a color from normalized components; alpha defaults to 1. */
         constructor(r: number, g: number, b: number, a?: number);
 
+        /** Mutable normalized red component. */
         r: number;
+        /** Mutable normalized green component. */
         g: number;
+        /** Mutable normalized blue component. */
         b: number;
+        /** Mutable normalized alpha component. */
         a: number;
 
+        /** Interpolate every component toward `target`, mutating this color. */
         lerp(target: Color, t: number): this;
+        /** Replace normalized components; alpha defaults to 1 when omitted. */
         set(r: number, g: number, b: number, a?: number): this;
+        /** Create an independent copy. */
         clone(): Color;
+        /** Return uppercase `#RRGGBB`, or `#RRGGBBAA` when alpha is requested. */
         toHex(includeAlpha?: boolean): string;
+        /** Format as `Color(r, g, b, a)` for logging. */
         toString(): string;
+        /** Convert to a plain normalized component object for `JSON.stringify`. */
         toJSON(): { r: number; g: number; b: number; a: number };
 
+        /** Parse `#RGB`, `#RGBA`, `#RRGGBB`, or `#RRGGBBAA`; invalid input returns opaque white. */
         static fromHex(hex: string): Color;
-        /** Construct from 0-255 component values. */
+        /** Construct from 0-255 component values; alpha defaults to 255. */
         static fromRGB(r: number, g: number, b: number, a?: number): Color;
+        /** Create opaque white. */
         static white(): Color;
+        /** Create opaque black. */
         static black(): Color;
+        /** Create opaque red. */
         static red(): Color;
+        /** Create opaque green. */
         static green(): Color;
+        /** Create opaque blue. */
         static blue(): Color;
+        /** Create opaque yellow. */
         static yellow(): Color;
+        /** Create opaque cyan. */
         static cyan(): Color;
+        /** Create opaque magenta. */
         static magenta(): Color;
+        /** Create fully transparent black. */
         static transparent(): Color;
     }
 }

package/core/events.d.ts

@@ -9,34 +9,62 @@ declare namespace Core {
      */
     const Events: {
         /**
-         * Register a listener for an event.
+         * Register a persistent listener owned by the calling resource.
+         * @param eventName Case-sensitive shared event name.
+         * @param handler Callback invoked with the emitted arguments; asynchronous results are awaited by emitters.
          * @returns An unsubscribe function.
          */
         on(eventName: string, handler: (...args: any[]) => void): () => void;
 
-        /** Register a one-time listener. */
+        /**
+         * Register a listener removed before its first invocation.
+         * @param eventName Case-sensitive shared event name.
+         * @param handler Resource-owned callback invoked once.
+         */
         once(eventName: string, handler: (...args: any[]) => void): void;
 
-        /** Remove a specific listener. */
+        /**
+         * Remove a matching listener owned by the calling resource.
+         * @param eventName Case-sensitive shared event name.
+         * @param handler Exact function passed to `on` or `once`.
+         */
         off(eventName: string, handler: (...args: any[]) => void): void;
 
         /**
          * Emit an event globally. Reserved events cannot be emitted.
          * Resolves when all handlers complete; rejects with
          * `AggregateError` if any handler fails.
+         * @param eventName Shared event name; framework-reserved names cannot be emitted by scripts.
+         * @param args Arguments delivered to every matching handler.
          */
         emit(eventName: string, ...args: any[]): Promise<void>;
 
-        /** Emit an event targeting a specific resource's listeners. */
+        /**
+         * Emit an event targeting listeners owned by one resource.
+         * @param resourceName Destination running resource.
+         * @param eventName Shared event name.
+         * @param args Arguments delivered to matching destination handlers.
+         */
         emitTo(resourceName: string, eventName: string, ...args: any[]): Promise<void>;
 
-        /** Register a resource-local listener. */
+        /**
+         * Register a listener in the calling resource's private event namespace.
+         * @param eventName Private event name.
+         * @param handler Callback invoked only by the same resource's `emitLocal` calls.
+         */
         onLocal(eventName: string, handler: (...args: any[]) => void): void;
 
-        /** Emit a resource-local event. */
+        /**
+         * Emit within the calling resource's private event namespace.
+         * @param eventName Private event name.
+         * @param args Arguments delivered to local handlers.
+         */
         emitLocal(eventName: string, ...args: any[]): Promise<void>;
 
-        /** Get the number of global listeners for an event. */
+        /**
+         * Count persistent and one-shot listeners across resources.
+         * @param eventName Shared event name to inspect.
+         */
         listenerCount(eventName: string): number;
     };
 }

package/core/quaternion.d.ts

@@ -1,29 +1,48 @@
 declare namespace Core {
+    /** Mutable quaternion used to compose and apply three-dimensional rotations. */
     class Quaternion {
+        /** Create a quaternion in scalar-first `(w, x, y, z)` order. */
         constructor(w: number, x: number, y: number, z: number);
 
+        /** Mutable scalar component. */
         w: number;
+        /** Mutable X imaginary component. */
         x: number;
+        /** Mutable Y imaginary component. */
         y: number;
+        /** Mutable Z imaginary component. */
         z: number;
 
+        /** Compose this rotation with `other`, mutating this quaternion. */
         multiply(other: Quaternion): this;
+        /** Normalize this quaternion in place. */
         normalize(): this;
+        /** Spherically interpolate toward `target`; `t=0` keeps this rotation and `t=1` reaches it. */
         slerp(target: Quaternion, t: number): this;
+        /** Return a new conjugated quaternion without modifying this one. */
         conjugate(): Quaternion;
+        /** Return a new inverse rotation without modifying this quaternion. */
         inverse(): Quaternion;
+        /** Compute the scalar quaternion dot product. */
         dot(other: Quaternion): number;
+        /** Apply this rotation and return a new rotated vector. */
         rotateVector(v: Vector3): Vector3;
         /** Euler angles in radians (x=pitch, y=yaw, z=roll). */
         toEuler(): Vector3;
+        /** Replace every component and return this quaternion for chaining. */
         set(w: number, x: number, y: number, z: number): this;
+        /** Create an independent copy. */
         clone(): Quaternion;
+        /** Format as `Quaternion(w, x, y, z)` for logging. */
         toString(): string;
+        /** Convert to a plain component object for `JSON.stringify`. */
         toJSON(): { w: number; x: number; y: number; z: number };
 
+        /** Create the identity rotation `Quaternion(1, 0, 0, 0)`. */
         static identity(): Quaternion;
         /** From euler angles in radians. */
         static fromEuler(pitch: number, yaw: number, roll: number): Quaternion;
+        /** Create a rotation of `angle` radians around an axis normalized internally. */
         static fromAxisAngle(axis: Vector3, angle: number): Quaternion;
     }
 }

package/core/vector2.d.ts

@@ -1,26 +1,45 @@
 declare namespace Core {
     class Vector2 {
+        /** Create a vector from its X and Y components. */
         constructor(x: number, y: number);
 
+        /** Mutable X component. */
         x: number;
+        /** Mutable Y component. */
         y: number;
+        /** Euclidean magnitude of this vector. */
         readonly length: number;
+        /** Squared magnitude, avoiding a square-root calculation. */
         readonly lengthSquared: number;
 
+        /** Add another vector component-wise, mutating this vector. */
         add(other: Vector2): this;
+        /** Subtract another vector component-wise, mutating this vector. */
         sub(other: Vector2): this;
+        /** Multiply both components by a scalar, mutating this vector. */
         mul(scalar: number): this;
+        /** Divide both components by a non-zero scalar, mutating this vector. */
         div(scalar: number): this;
+        /** Normalize this vector in place; a zero vector remains unchanged. */
         normalize(): this;
+        /** Compute the scalar dot product without changing either vector. */
         dot(other: Vector2): number;
+        /** Compute Euclidean distance to another vector. */
         distance(other: Vector2): number;
+        /** Interpolate toward `target`; `t=0` keeps this value and `t=1` reaches the target. */
         lerp(target: Vector2, t: number): this;
+        /** Replace both components and return this vector for chaining. */
         set(x: number, y: number): this;
+        /** Create an independent copy. */
         clone(): Vector2;
+        /** Format as `Vector2(x, y)` for logging. */
         toString(): string;
+        /** Convert to a plain component object for `JSON.stringify`. */
         toJSON(): { x: number; y: number };
 
+        /** Create `Vector2(0, 0)`. */
         static zero(): Vector2;
+        /** Create `Vector2(1, 1)`. */
         static one(): Vector2;
     }
 }

package/core/vector3.d.ts

@@ -1,31 +1,55 @@
 declare namespace Core {
     class Vector3 {
+        /** Create a vector from its X, Y, and Z components. */
         constructor(x: number, y: number, z: number);
 
+        /** Mutable X component. */
         x: number;
+        /** Mutable Y component. */
         y: number;
+        /** Mutable Z component. */
         z: number;
+        /** Euclidean magnitude of this vector. */
         readonly length: number;
+        /** Squared magnitude, avoiding a square-root calculation. */
         readonly lengthSquared: number;
 
+        /** Add another vector component-wise, mutating this vector. */
         add(other: Vector3): this;
+        /** Subtract another vector component-wise, mutating this vector. */
         sub(other: Vector3): this;
+        /** Multiply every component by a scalar, mutating this vector. */
         mul(scalar: number): this;
+        /** Divide every component by a non-zero scalar, mutating this vector. */
         div(scalar: number): this;
+        /** Normalize this vector in place; a zero vector remains unchanged. */
         normalize(): this;
+        /** Compute the scalar dot product without changing either vector. */
         dot(other: Vector3): number;
+        /** Replace this vector with its cross product against `other`. */
         cross(other: Vector3): this;
+        /** Compute Euclidean distance to another vector. */
         distance(other: Vector3): number;
+        /** Interpolate toward `target`; `t=0` keeps this value and `t=1` reaches the target. */
         lerp(target: Vector3, t: number): this;
+        /** Replace all components and return this vector for chaining. */
         set(x: number, y: number, z: number): this;
+        /** Create an independent copy. */
         clone(): Vector3;
+        /** Format as `Vector3(x, y, z)` for logging. */
         toString(): string;
+        /** Convert to a plain component object for `JSON.stringify`. */
         toJSON(): { x: number; y: number; z: number };
 
+        /** Create `Vector3(0, 0, 0)`. */
         static zero(): Vector3;
+        /** Create `Vector3(1, 1, 1)`. */
         static one(): Vector3;
+        /** Create the framework's positive-Y unit direction. */
         static up(): Vector3;
+        /** Create the framework's positive-Z unit direction. */
         static forward(): Vector3;
+        /** Create the framework's positive-X unit direction. */
         static right(): Vector3;
     }
 }

package/core/vector4.d.ts

@@ -1,28 +1,49 @@
 declare namespace Core {
     class Vector4 {
+        /** Create a vector from its X, Y, Z, and W components. */
         constructor(x: number, y: number, z: number, w: number);
 
+        /** Mutable X component. */
         x: number;
+        /** Mutable Y component. */
         y: number;
+        /** Mutable Z component. */
         z: number;
+        /** Mutable W component. */
         w: number;
+        /** Euclidean magnitude of this vector. */
         readonly length: number;
+        /** Squared magnitude, avoiding a square-root calculation. */
         readonly lengthSquared: number;
 
+        /** Add another vector component-wise, mutating this vector. */
         add(other: Vector4): this;
+        /** Subtract another vector component-wise, mutating this vector. */
         sub(other: Vector4): this;
+        /** Multiply every component by a scalar, mutating this vector. */
         mul(scalar: number): this;
+        /** Divide every component by a non-zero scalar, mutating this vector. */
         div(scalar: number): this;
+        /** Normalize this vector in place; a zero vector remains unchanged. */
         normalize(): this;
+        /** Compute the scalar dot product without changing either vector. */
         dot(other: Vector4): number;
+        /** Compute Euclidean distance to another vector. */
         distance(other: Vector4): number;
+        /** Interpolate toward `target`; `t=0` keeps this value and `t=1` reaches the target. */
         lerp(target: Vector4, t: number): this;
+        /** Replace all components and return this vector for chaining. */
         set(x: number, y: number, z: number, w: number): this;
+        /** Create an independent copy. */
         clone(): Vector4;
+        /** Format as `Vector4(x, y, z, w)` for logging. */
         toString(): string;
+        /** Convert to a plain component object for `JSON.stringify`. */
         toJSON(): { x: number; y: number; z: number; w: number };
 
+        /** Create `Vector4(0, 0, 0, 0)`. */
         static zero(): Vector4;
+        /** Create `Vector4(1, 1, 1, 1)`. */
         static one(): Vector4;
     }
 }

package/framework/discord.d.ts

@@ -0,0 +1,153 @@
+declare namespace Framework {
+    /** Activity verb shown before the app name. Name or the numeric Discord enum. */
+    type DiscordActivityType = "playing" | "streaming" | "listening" | "watching" | number;
+
+    /** Party join privacy. Name or the numeric Discord enum. */
+    type DiscordPartyPrivacy = "private" | "public" | number;
+
+    /** Options accepted by {@link Discord.setPresence}. Every field is optional. */
+    interface DiscordPresenceOptions {
+        /** Activity verb; defaults to `"playing"`. */
+        type?: DiscordActivityType;
+        /** Activity name. */
+        name?: string;
+        /** Top line of the presence. */
+        details?: string;
+        /** Bottom line of the presence. */
+        state?: string;
+        /** Elapsed-time anchor, unix seconds. `0` clears it. */
+        startTimestamp?: number;
+        /** Countdown anchor, unix seconds. `0` clears it. */
+        endTimestamp?: number;
+        /** Asset key of the large image. */
+        largeImage?: string;
+        /** Tooltip for the large image. */
+        largeText?: string;
+        /** Asset key of the small image (overlaps the large one). */
+        smallImage?: string;
+        /** Tooltip for the small image. */
+        smallText?: string;
+        /** Party grouping — enables Discord "X of Y" and, with a join secret, invites. */
+        party?: {
+            id?: string;
+            /** `[current, max]` party size. */
+            size?: [number, number];
+            privacy?: DiscordPartyPrivacy;
+        };
+        /** Invite/spectate secrets (opaque strings your game round-trips). */
+        secrets?: {
+            match?: string;
+            join?: string;
+            spectate?: string;
+        };
+        /** Whether this is an instanced (session) activity. */
+        instance?: boolean;
+        /** Supported-platform bitmask (Desktop = 1, Android = 2, iOS = 4). */
+        supportedPlatforms?: number;
+    }
+
+    /**
+     * Client-side Discord rich presence API. **Client only** — not available on
+     * the server.
+     *
+     * Field setters *stage* changes onto a pending activity; nothing is shown
+     * until {@link Discord.update} (or the batch {@link Discord.setPresence}) is
+     * called. This mirrors Discord's model — an activity is published as one whole
+     * object and updates are rate-limited — so compose, then commit once. All
+     * calls no-op (setters silently, commits return `false`) when Discord presence
+     * is disabled or unavailable.
+     *
+     * @example
+     * // Batch form — apply several fields and publish in one call:
+     * Framework.Discord.setPresence({
+     *     details: "In the city",
+     *     state: "Freeroam",
+     *     largeImage: "map-city",
+     *     startTimestamp: Math.floor(Date.now() / 1000),
+     *     party: { size: [4, 32] },
+     * });
+     *
+     * @example
+     * // Granular form — stage, then commit:
+     * Framework.Discord.setDetails("Racing");
+     * Framework.Discord.setPartySize(2, 8);
+     * Framework.Discord.update();
+     */
+    const Discord: {
+        /** Stage the activity {@link DiscordActivityType type}. */
+        setType(type: DiscordActivityType): void;
+        /** Stage the activity name. */
+        setName(name: string): void;
+        /** Stage the top line. */
+        setDetails(details: string): void;
+        /** Stage the bottom line. */
+        setState(state: string): void;
+
+        /** Stage the elapsed-time anchor (unix seconds; `0` clears). */
+        setStartTimestamp(seconds: number): void;
+        /** Stage the countdown anchor (unix seconds; `0` clears). */
+        setEndTimestamp(seconds: number): void;
+
+        /** Stage the large image asset key. */
+        setLargeImage(assetKey: string): void;
+        /** Stage the large image tooltip. */
+        setLargeText(text: string): void;
+        /** Stage the small image asset key. */
+        setSmallImage(assetKey: string): void;
+        /** Stage the small image tooltip. */
+        setSmallText(text: string): void;
+        /** Stage several asset fields at once. */
+        setAssets(assets: { largeImage?: string; largeText?: string; smallImage?: string; smallText?: string }): void;
+
+        /** Stage the party id. */
+        setPartyId(id: string): void;
+        /** Stage the party size (current of max). */
+        setPartySize(current: number, max: number): void;
+        /** Stage the party join privacy. */
+        setPartyPrivacy(privacy: DiscordPartyPrivacy): void;
+        /** Stage several party fields at once. */
+        setParty(party: { id?: string; size?: [number, number]; privacy?: DiscordPartyPrivacy }): void;
+
+        /** Stage the match secret. */
+        setMatchSecret(secret: string): void;
+        /** Stage the join secret (enables Ask to Join). */
+        setJoinSecret(secret: string): void;
+        /** Stage the spectate secret. */
+        setSpectateSecret(secret: string): void;
+        /** Stage several secret fields at once. */
+        setSecrets(secrets: { match?: string; join?: string; spectate?: string }): void;
+
+        /** Stage the instanced flag. */
+        setInstance(instance: boolean): void;
+        /** Stage the supported-platform bitmask (Desktop = 1, Android = 2, iOS = 4). */
+        setSupportedPlatforms(flags: number): void;
+
+        /**
+         * Apply a batch of fields and publish immediately (a merge of the matching
+         * setters followed by {@link Discord.update}).
+         * @returns `true` if the update was dispatched, `false` if unavailable.
+         */
+        setPresence(options: DiscordPresenceOptions): boolean;
+
+        /**
+         * Publish the currently staged activity.
+         * @returns `true` if dispatched, `false` if unavailable.
+         */
+        update(): boolean;
+
+        /**
+         * Clear the activity on Discord and reset the staged state.
+         * @returns `true` if dispatched, `false` if unavailable.
+         */
+        clear(): boolean;
+
+        /** Reset the staged state without publishing. */
+        reset(): void;
+
+        /** Snowflake of the signed-in Discord user, or `""` until known. */
+        getUserId(): string;
+
+        /** Whether the Discord client is connected and presence can be published. */
+        isAvailable(): boolean;
+    };
+}

package/framework/exports.d.ts

@@ -1,12 +1,20 @@
 declare namespace Framework {
     const Exports: {
-        /** Register a named export from the current resource. */
+        /**
+         * Register a value or function from the calling resource.
+         * @param name Export name, preferably declared in the resource manifest.
+         * @param value JavaScript value retained for dependent resources.
+         * @returns `true` when registration succeeds.
+         */
         register(name: string, value: any): boolean;
 
         /**
          * Get a specific export from another resource.
          * Throws if the resource is not found, not running, or the export
          * does not exist.
+         * @param resourceName Name of the running resource that owns the export.
+         * @param exportName Registered export name.
+         * @returns The exported value with its original JavaScript identity.
          */
         get(resourceName: string, exportName: string): any;
     };

package/framework/imports.d.ts

@@ -3,6 +3,9 @@ declare namespace Framework {
         /**
          * Get the exports object from another resource.
          * Throws if the resource is not found or not running.
+         * Importing without a declared dependency produces a warning.
+         * @param resourceName Name of the running resource whose exports should be read.
+         * @returns An object keyed by export name, or an empty object when none are registered.
          */
         get(resourceName: string): Record<string, any>;
     };

package/framework/messages.d.ts

@@ -1,9 +1,10 @@
 declare namespace Framework {
     const messages: {
         /**
-         * Register a handler for incoming messages of a given type.
+         * Register or replace a handler owned by the calling resource.
+         * @param messageType Message type unique within the receiving resource.
          * @param handler Receives `(payload, reply)`. Call `reply(value)`
-         *   to send a response back to the requester.
+         *   once to resolve a request; replies are ignored for fire-and-forget messages.
          */
         handle(
             messageType: string,
@@ -13,10 +14,19 @@ declare namespace Framework {
         /**
          * Send a request to another resource and await a reply.
          * Rejects if the target resource has no handler or the handler throws.
+         * @param resourceName Destination running resource.
+         * @param messageType Handler type registered by the destination.
+         * @param payload Optional value delivered to the handler.
+         * @returns A promise resolved with the value passed to `reply`.
          */
         request(resourceName: string, messageType: string, payload?: any): Promise<any>;
 
-        /** Fire-and-forget message to another resource. */
+        /**
+         * Send a fire-and-forget message to another local resource.
+         * @param resourceName Destination running resource.
+         * @param messageType Handler type registered by the destination.
+         * @param payload Optional value delivered to the handler.
+         */
         send(resourceName: string, messageType: string, payload?: any): void;
     };
 }

package/index.d.ts

@@ -8,3 +8,4 @@
 /// <reference path="framework/imports.d.ts" />
 /// <reference path="framework/exports.d.ts" />
 /// <reference path="framework/key.d.ts" />
+/// <reference path="framework/discord.d.ts" />

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mafiahub/types",
-    "version": "0.1.4",
+    "version": "0.1.6",
     "description": "TypeScript type definitions for the MafiaHub Framework scripting API",
     "types": "index.d.ts",
     "files": [