foundryvtt-mcp 0.11.0

package/dist/foundry/types.d.ts

@@ -0,0 +1,805 @@
+/**
+ * @fileoverview TypeScript type definitions for FoundryVTT data structures
+ *
+ * This module contains comprehensive type definitions for all FoundryVTT entities
+ * including actors, items, scenes, tokens, and other game objects. These types
+ * provide type safety and intellisense when working with FoundryVTT data.
+ *
+ * @version 0.1.0
+ * @author FoundryVTT MCP Team
+ * @see {@link https://foundryvtt.com/api/} FoundryVTT API Documentation
+ */
+/**
+ * Represents an actor (character, NPC, or creature) in FoundryVTT
+ *
+ * Actors are the primary entities that represent characters, NPCs, monsters,
+ * and other creatures in the game world. This interface covers the common
+ * properties shared across different game systems.
+ *
+ * @interface FoundryActor
+ * @example
+ * ```typescript
+ * const hero: FoundryActor = {
+ *   _id: 'actor-123',
+ *   name: 'Aragorn',
+ *   type: 'character',
+ *   hp: { value: 45, max: 45 },
+ *   ac: { value: 16 },
+ *   level: 5
+ * };
+ * ```
+ */
+export interface FoundryActor {
+    _id: string;
+    name: string;
+    type: string;
+    img?: string;
+    data?: Record<string, unknown>;
+    hp?: {
+        value: number;
+        max: number;
+        temp?: number;
+    };
+    ac?: {
+        value: number;
+    };
+    attributes?: Record<string, unknown>;
+    abilities?: Record<string, {
+        value: number;
+        mod: number;
+        save?: number;
+    }>;
+    skills?: Record<string, {
+        value: number;
+        mod: number;
+        proficient?: boolean;
+    }>;
+    level?: number;
+    experience?: {
+        value: number;
+        max: number;
+    };
+    currency?: Record<string, number>;
+    biography?: string;
+    notes?: string;
+}
+/**
+ * Represents an item (weapon, armor, spell, etc.) in FoundryVTT
+ *
+ * Items represent equipment, spells, features, and other objects that can be
+ * owned by actors or exist independently in the game world.
+ *
+ * @interface FoundryItem
+ * @example
+ * ```typescript
+ * const sword: FoundryItem = {
+ *   _id: 'item-456',
+ *   name: 'Longsword +1',
+ *   type: 'weapon',
+ *   rarity: 'uncommon',
+ *   damage: { parts: [['1d8+1', 'slashing']] },
+ *   price: { value: 315, denomination: 'gp' }
+ * };
+ * ```
+ */
+export interface FoundryItem {
+    _id: string;
+    name: string;
+    type: string;
+    img?: string;
+    data?: Record<string, unknown>;
+    description?: string;
+    rarity?: string;
+    price?: {
+        value: number;
+        denomination: string;
+    };
+    weight?: number;
+    quantity?: number;
+    equipped?: boolean;
+    identified?: boolean;
+    damage?: {
+        parts: Array<[string, string]>;
+        versatile?: string;
+    };
+    range?: {
+        value: number;
+        long?: number;
+        units: string;
+    };
+    armor?: {
+        value: number;
+        type: string;
+        dex?: number;
+    };
+    level?: number;
+    school?: string;
+    components?: {
+        vocal: boolean;
+        somatic: boolean;
+        material: boolean;
+        value?: string;
+    };
+    duration?: {
+        value: number;
+        units: string;
+    };
+    itemRange?: {
+        value: number;
+        units: string;
+    };
+}
+/**
+ * Represents a scene (map/battleground) in FoundryVTT
+ *
+ * Scenes are the visual environments where gameplay takes place, containing
+ * background images, tokens, lighting, walls, and other elements.
+ *
+ * @interface FoundryScene
+ * @example
+ * ```typescript
+ * const dungeon: FoundryScene = {
+ *   _id: 'scene-789',
+ *   name: 'Ancient Tomb',
+ *   active: true,
+ *   width: 4000,
+ *   height: 3000,
+ *   grid: { size: 100, type: 1 }
+ * };
+ * ```
+ */
+export interface FoundryScene {
+    _id: string;
+    name: string;
+    active: boolean;
+    navigation: boolean;
+    img?: string;
+    background?: string;
+    width: number;
+    height: number;
+    padding: number;
+    initial?: {
+        x: number;
+        y: number;
+        scale: number;
+    };
+    grid?: {
+        type: number;
+        size: number;
+        color: string;
+        alpha: number;
+        distance: number;
+        units: string;
+    };
+    shiftX: number;
+    shiftY: number;
+    description?: string;
+    notes?: string;
+    weather?: string;
+    environment?: string;
+    globalLight: boolean;
+    globalLightThreshold?: number;
+    darkness: number;
+    tokens?: FoundryToken[];
+    walls?: FoundryWall[];
+    lights?: FoundryLight[];
+    sounds?: FoundrySound[];
+    drawings?: FoundryDrawing[];
+}
+/**
+ * Represents a token on a scene in FoundryVTT
+ *
+ * Tokens are the visual representations of actors placed on scenes.
+ * They contain position, appearance, and gameplay-related information.
+ *
+ * @interface FoundryToken
+ * @example
+ * ```typescript
+ * const heroToken: FoundryToken = {
+ *   _id: 'token-123',
+ *   name: 'Aragorn',
+ *   x: 1000,
+ *   y: 1500,
+ *   actorId: 'actor-123',
+ *   disposition: 1 // friendly
+ * };
+ * ```
+ */
+export interface FoundryToken {
+    _id: string;
+    name: string;
+    img: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scale: number;
+    rotation: number;
+    actorId?: string;
+    actorLink: boolean;
+    disposition: number;
+    hidden: boolean;
+    vision: boolean;
+    dimSight: number;
+    brightSight: number;
+    bar1?: {
+        attribute: string;
+    };
+    bar2?: {
+        attribute: string;
+    };
+    effects?: string[];
+}
+/**
+ * Represents a wall segment in a FoundryVTT scene
+ *
+ * Walls control movement, vision, and sound propagation in scenes.
+ * They define the physical boundaries and obstacles in the environment.
+ *
+ * @interface FoundryWall
+ */
+export interface FoundryWall {
+    _id: string;
+    c: [number, number, number, number];
+    move: number;
+    sense: number;
+    sound: number;
+    door: number;
+    ds: number;
+}
+/**
+ * Represents a light source in a FoundryVTT scene
+ *
+ * Light sources provide illumination and create atmospheric effects
+ * in scenes, affecting token vision and creating ambiance.
+ *
+ * @interface FoundryLight
+ */
+export interface FoundryLight {
+    _id: string;
+    x: number;
+    y: number;
+    rotation: number;
+    config: {
+        bright: number;
+        dim: number;
+        angle: number;
+        color?: string;
+        alpha: number;
+        animation?: {
+            type: string;
+            speed: number;
+            intensity: number;
+        };
+    };
+    hidden: boolean;
+}
+/**
+ * Represents an ambient sound in a FoundryVTT scene
+ *
+ * Sound objects provide audio atmosphere and effects in scenes,
+ * with positional audio and volume controls.
+ *
+ * @interface FoundrySound
+ */
+export interface FoundrySound {
+    _id: string;
+    x: number;
+    y: number;
+    radius: number;
+    path: string;
+    repeat: boolean;
+    volume: number;
+    hidden: boolean;
+}
+/**
+ * Represents a drawing/annotation in a FoundryVTT scene
+ *
+ * Drawings allow GMs and players to add visual annotations,
+ * shapes, and text directly onto scenes.
+ *
+ * @interface FoundryDrawing
+ */
+export interface FoundryDrawing {
+    _id: string;
+    type: string;
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+    points?: number[];
+    shape?: {
+        type: string;
+        points?: number[];
+        radius?: number;
+        width?: number;
+        height?: number;
+    };
+    fillType: number;
+    fillColor?: string;
+    strokeWidth: number;
+    strokeColor?: string;
+    text?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    textColor?: string;
+    hidden: boolean;
+    locked: boolean;
+}
+/**
+ * Represents world information in FoundryVTT
+ *
+ * Contains metadata about the current game world including
+ * system information, modules, and world settings.
+ *
+ * @interface FoundryWorld
+ * @example
+ * ```typescript
+ * const world: FoundryWorld = {
+ *   id: 'my-campaign',
+ *   title: 'Adventures in Middle-earth',
+ *   system: 'dnd5e',
+ *   coreVersion: '11.315',
+ *   playtime: 144000 // in seconds
+ * };
+ * ```
+ */
+export interface FoundryWorld {
+    id: string;
+    title: string;
+    description: string;
+    system: string;
+    coreVersion: string;
+    systemVersion: string;
+    lastPlayed?: string;
+    playtime: number;
+    created: string;
+    modified: string;
+    background?: string;
+    nextSession?: string;
+    modules?: Array<{
+        id: string;
+        title: string;
+        active: boolean;
+    }>;
+}
+export interface FoundryJournal {
+    _id: string;
+    name: string;
+    content: string;
+    img?: string;
+    folder?: string;
+    permission: Record<string, number>;
+    pages?: Array<{
+        name: string;
+        type: string;
+        title: string;
+        content?: string;
+        src?: string;
+    }>;
+}
+export interface FoundryMacro {
+    _id: string;
+    name: string;
+    type: string;
+    scope: string;
+    command: string;
+    img?: string;
+    folder?: string;
+    author: string;
+    ownership: Record<string, number>;
+}
+export interface FoundryPlaylist {
+    _id: string;
+    name: string;
+    description?: string;
+    mode: number;
+    playing: boolean;
+    fade: number;
+    folder?: string;
+    sounds: Array<{
+        _id: string;
+        name: string;
+        path: string;
+        playing: boolean;
+        repeat: boolean;
+        volume: number;
+        fade: number;
+    }>;
+}
+export interface FoundryCombat {
+    _id: string;
+    scene?: string;
+    active: boolean;
+    round: number;
+    turn: number;
+    started: boolean;
+    combatants: Array<{
+        _id: string;
+        tokenId: string;
+        actorId?: string;
+        name: string;
+        img?: string;
+        initiative?: number;
+        hidden: boolean;
+        defeated: boolean;
+    }>;
+    settings: {
+        resource?: string;
+        skipDefeated: boolean;
+    };
+}
+/**
+ * Represents the result of a dice roll in FoundryVTT
+ *
+ * Contains all information about a completed dice roll including
+ * the formula used, total result, breakdown, and metadata.
+ *
+ * @interface DiceRoll
+ * @example
+ * ```typescript
+ * const attackRoll: DiceRoll = {
+ *   formula: '1d20+5',
+ *   total: 18,
+ *   breakdown: '13 + 5',
+ *   reason: 'Sword attack',
+ *   timestamp: '2024-01-15T10:30:00Z'
+ * };
+ * ```
+ */
+export interface DiceRoll {
+    formula: string;
+    total: number;
+    breakdown: string;
+    reason?: string;
+    timestamp: string;
+}
+export interface FoundryUser {
+    _id: string;
+    name: string;
+    role: number;
+    active: boolean;
+    color: string;
+    avatar?: string;
+    character?: string;
+    permissions: Record<string, boolean>;
+}
+/**
+ * Result structure for actor search operations
+ *
+ * Contains paginated search results for actor queries
+ * along with metadata about the search.
+ *
+ * @interface ActorSearchResult
+ * @example
+ * ```typescript
+ * const searchResult: ActorSearchResult = {
+ *   actors: [],
+ *   total: 25,
+ *   page: 1,
+ *   limit: 10
+ * };
+ * ```
+ */
+export interface ActorSearchResult {
+    actors: FoundryActor[];
+    total: number;
+    page: number;
+    limit: number;
+}
+/**
+ * Result structure for item search operations
+ *
+ * Contains paginated search results for item queries
+ * along with metadata about the search.
+ *
+ * @interface ItemSearchResult
+ * @example
+ * ```typescript
+ * const searchResult: ItemSearchResult = {
+ *   items: [],
+ *   total: 42,
+ *   page: 1,
+ *   limit: 20
+ * };
+ * ```
+ */
+export interface ItemSearchResult {
+    items: FoundryItem[];
+    total: number;
+    page: number;
+    limit: number;
+}
+/**
+ * Generic API response structure for FoundryVTT REST API
+ *
+ * Standardized response format for API calls including
+ * success status, data payload, and error information.
+ *
+ * @interface FoundryAPIResponse
+ * @template T - Type of the response data
+ * @example
+ * ```typescript
+ * const response: FoundryAPIResponse<FoundryActor[]> = {
+ *   success: true,
+ *   data: [],
+ *   message: 'Actors retrieved successfully'
+ * };
+ * ```
+ */
+export interface FoundryAPIResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+}
+/**
+ * Structure for WebSocket messages exchanged with FoundryVTT
+ *
+ * Defines the format for real-time communication messages
+ * between the MCP server and FoundryVTT.
+ *
+ * @interface FoundryWebSocketMessage
+ * @example
+ * ```typescript
+ * const message: FoundryWebSocketMessage = {
+ *   type: 'combatUpdate',
+ *   data: { round: 3, turn: 2 },
+ *   user: 'user-123',
+ *   timestamp: '2024-01-15T10:30:00Z'
+ * };
+ * ```
+ */
+export interface FoundryWebSocketMessage {
+    type: string;
+    data?: unknown;
+    user?: string;
+    timestamp: string;
+}
+/**
+ * Structure for AI-generated NPC data
+ *
+ * Contains all information needed to create a complete NPC
+ * including personality, appearance, and background details.
+ *
+ * @interface GeneratedNPC
+ * @example
+ * ```typescript
+ * const npc: GeneratedNPC = {
+ *   name: 'Thorin Ironforge',
+ *   race: 'Dwarf',
+ *   class: 'Fighter',
+ *   personality: ['Gruff but loyal', 'Speaks little but acts decisively'],
+ *   appearance: 'Short and stocky with a magnificent braided beard',
+ *   motivations: ['Protect the clan honor', 'Forge the perfect weapon']
+ * };
+ * ```
+ */
+export interface GeneratedNPC {
+    name: string;
+    race: string;
+    class?: string;
+    level?: number;
+    background?: string;
+    personality: string[];
+    appearance: string;
+    motivations: string[];
+    stats?: Record<string, number>;
+    equipment?: string[];
+}
+export interface GeneratedLocation {
+    name: string;
+    type: string;
+    description: string;
+    features: string[];
+    inhabitants?: string[];
+    hooks?: string[];
+    connections?: string[];
+}
+export interface GeneratedQuest {
+    title: string;
+    type: string;
+    giver: string;
+    description: string;
+    objectives: string[];
+    rewards: string[];
+    complications?: string[];
+    timeLimit?: string;
+}
+/**
+ * Raw actor document from worldData.
+ * The `system` field shape varies by game system (dnd5e, pf2e, etc.).
+ */
+export interface WorldActor {
+    _id: string;
+    name: string;
+    type: string;
+    img?: string;
+    system: Record<string, unknown>;
+    items?: WorldItem[];
+    effects?: WorldEffect[];
+    folder?: string | null;
+    sort?: number;
+    ownership?: Record<string, number>;
+    flags?: Record<string, unknown>;
+    prototypeToken?: Record<string, unknown>;
+}
+/**
+ * Raw item document from worldData.
+ */
+export interface WorldItem {
+    _id: string;
+    name: string;
+    type: string;
+    img?: string;
+    system: Record<string, unknown>;
+    effects?: WorldEffect[];
+    folder?: string | null;
+    sort?: number;
+    ownership?: Record<string, number>;
+    flags?: Record<string, unknown>;
+}
+/**
+ * Raw scene document from worldData.
+ */
+export interface WorldScene {
+    _id: string;
+    name: string;
+    active: boolean;
+    navigation: boolean;
+    img?: string;
+    background?: Record<string, unknown>;
+    width: number;
+    height: number;
+    padding: number;
+    grid?: Record<string, unknown>;
+    tokens?: Array<Record<string, unknown>>;
+    walls?: Array<Record<string, unknown>>;
+    lights?: Array<Record<string, unknown>>;
+    drawings?: Array<Record<string, unknown>>;
+    sounds?: Array<Record<string, unknown>>;
+    notes?: Array<Record<string, unknown>>;
+    tiles?: Array<Record<string, unknown>>;
+    darkness: number;
+    globalLight: boolean;
+    globalLightThreshold?: number;
+    folder?: string | null;
+    sort?: number;
+    ownership?: Record<string, number>;
+    flags?: Record<string, unknown>;
+}
+/**
+ * Raw journal entry from worldData.
+ */
+export interface WorldJournal {
+    _id: string;
+    name: string;
+    pages?: Array<{
+        _id: string;
+        name: string;
+        type: string;
+        title?: {
+            show: boolean;
+            level: number;
+        };
+        text?: {
+            content: string;
+            format: number;
+        };
+        image?: Record<string, unknown>;
+        video?: Record<string, unknown>;
+        src?: string;
+        sort?: number;
+    }>;
+    folder?: string | null;
+    sort?: number;
+    ownership?: Record<string, number>;
+    flags?: Record<string, unknown>;
+}
+/**
+ * Raw chat message from worldData.
+ */
+export interface WorldMessage {
+    _id: string;
+    type: number;
+    user: string;
+    timestamp: number;
+    flavor?: string;
+    content: string;
+    speaker?: {
+        scene?: string;
+        actor?: string;
+        token?: string;
+        alias?: string;
+    };
+    rolls?: string[];
+    sound?: string;
+    whisper?: string[];
+    blind?: boolean;
+    flags?: Record<string, unknown>;
+}
+/**
+ * Raw combat document from worldData.
+ */
+export interface WorldCombat {
+    _id: string;
+    scene?: string;
+    active: boolean;
+    round: number;
+    turn: number | null;
+    started: boolean;
+    combatants: Array<{
+        _id: string;
+        actorId?: string;
+        tokenId?: string;
+        sceneId?: string;
+        name: string;
+        img?: string;
+        initiative: number | null;
+        hidden: boolean;
+        defeated: boolean;
+        flags?: Record<string, unknown>;
+    }>;
+    flags?: Record<string, unknown>;
+}
+/**
+ * Raw user document from worldData.
+ */
+export interface WorldUser {
+    _id: string;
+    name: string;
+    role: number;
+    color: string;
+    avatar?: string;
+    character?: string;
+    password?: string;
+    pronouns?: string;
+    flags?: Record<string, unknown>;
+}
+/**
+ * Active effect on an actor or item.
+ */
+export interface WorldEffect {
+    _id: string;
+    name: string;
+    img?: string;
+    type?: string;
+    system?: Record<string, unknown>;
+    changes?: Array<{
+        key: string;
+        mode: number;
+        value: string;
+        priority?: number;
+    }>;
+    disabled?: boolean;
+    duration?: Record<string, unknown>;
+    flags?: Record<string, unknown>;
+}
+/**
+ * Complete world data returned by the Socket.IO 'world' event.
+ */
+export interface WorldData {
+    userId: string;
+    release: Record<string, unknown>;
+    world: Record<string, unknown>;
+    system: Record<string, unknown>;
+    modules: Array<Record<string, unknown>>;
+    demoMode: boolean;
+    actors: WorldActor[];
+    scenes: WorldScene[];
+    items: WorldItem[];
+    journal: WorldJournal[];
+    messages: WorldMessage[];
+    combats: WorldCombat[];
+    users: WorldUser[];
+    activeUsers: string[];
+    settings: unknown[];
+    folders: Array<Record<string, unknown>>;
+    macros: Array<Record<string, unknown>>;
+    playlists: Array<Record<string, unknown>>;
+    tables: Array<Record<string, unknown>>;
+    cards: Array<Record<string, unknown>>;
+    packs: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map