import type { GameModelAPI } from '../domains/gameModel.js';
import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
import type { EngineDetector } from './engine.js';
import type { EnginePose } from './wire.js';
/** Options for {@link NpcsKit}. Must match the deployed NPC blueprint. */
export interface NpcsKitOptions {
    /** The `typeName` the NPC blueprint was deployed with. Defaults to `'Npc'`. */
    typeName?: string;
    /**
     * The compute module driving NPC movement when the app runs an engine
     * (smooth FLAG_NPC actor emits instead of property nudges). Defaults to
     * `'npc-engine'`.
     */
    moduleName?: string;
}
/**
 * The minimal shape of a live actor entry {@link overlayLivePoses} reads —
 * matches the world-session `RemoteActor<EnginePose>` without importing it.
 */
export interface LiveNpcPose {
    uuid: string;
    state: Pick<EnginePose, 'x' | 'y' | 'z'>;
    receivedAt: number;
}
/** A parsed view of one live NPC. */
export interface KitNpc {
    containerId: string;
    displayName: string;
    role: string;
    x: number;
    y: number;
    z: number;
    behaviorState: string;
    health: number;
    /** All visible properties, including any extras your blueprint added. */
    properties: Record<string, unknown>;
}
/**
 * Runtime helpers for the {@link npcBlueprint} conventions: spawn NPC
 * instances, read their server-driven state, and manage/monitor the
 * automations behind them. Behaviors run in the API server — clients only
 * re-read state (or listen for model-driven notifications) and render.
 *
 * Spawning and the automation management/monitoring calls are studio/admin
 * operations (`manage_apps`); reads are player-safe.
 *
 * Obtained via `client.kit(appId).npcs`.
 */
export declare class NpcsKit {
    private readonly appId;
    private readonly gameModel;
    private readonly engines?;
    private readonly typeName;
    private readonly moduleName;
    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: NpcsKitOptions, engines?: EngineDetector | undefined);
    /**
     * Is an NPC compute engine deployed + enabled (cached per session)? When
     * true, NPCs stream smooth FLAG_NPC actor poses — overlay them with
     * {@link overlayLivePoses}. When false (model-only deployment), the polled
     * container positions are all there is, exactly as before.
     */
    engineAvailable(): Promise<boolean>;
    /**
     * Overlay live engine-driven poses onto a polled NPC snapshot (the
     * generalized BWF `NpcService.withLivePoses` pattern): each NPC whose
     * `actor_uuid` has a fresh pose in the npcs actor lane gets its position
     * replaced; the rest keep their durable container position, so NPCs stand
     * at their last synced spot instead of disappearing.
     *
     * @param npcs - The polled snapshot (from {@link list}).
     * @param lane - The live actors, e.g. `session.actors.lane('npcs').list()`.
     */
    overlayLivePoses(npcs: KitNpc[], lane: LiveNpcPose[]): KitNpc[];
    /** Spawn a live NPC instance (admin — the type is admin-instantiable). */
    spawn(input: {
        displayName: string;
        role?: string;
        position?: {
            x: number;
            y: number;
            z: number;
        };
        properties?: SeedPropertyInput[];
        sessionId?: string;
    }): Promise<{
        __typename?: "GmContainer";
        containerId: string;
        appId: string;
        sessionId: string | null;
        typeName: string;
        displayName: string;
        description: string | null;
        ownerUserId: string | null;
        metadataJson: string;
    }>;
    /**
     * List live NPCs with parsed state, optionally filtered by `role`. Fetches
     * each NPC's visible properties in parallel — fine for the bounded NPC
     * populations automations are designed around.
     */
    list(options?: {
        role?: string;
        sessionId?: string;
    }): Promise<KitNpc[]>;
    /** Read one NPC's current server-side state. */
    state(npcId: string): Promise<KitNpc>;
    /** Run one of the NPC automations immediately (admin; useful for testing). */
    runNow(automationName: string): Promise<{
        __typename?: "GmAutomationRun";
        runId: string;
        appId: string;
        flowId: string | null;
        automationId: string | null;
        automationName: string;
        triggerSource: string;
        triggerId: string | null;
        parentRunId: string | null;
        cascadeDepth: number;
        startedAt: string;
        finishedAt: string | null;
        durationUs: number;
        targets: number;
        invocations: number;
        mutations: number;
        fnCalls: number;
        gasUsed: number;
        success: boolean;
        errorMessage: string | null;
        circuitAction: string | null;
        computeUnits: number;
    }>;
    /**
     * Pause or resume an NPC automation (admin). Re-enabling also resets a
     * tripped failure circuit.
     */
    setEnabled(automationName: string, enabled: boolean): Promise<{
        __typename?: "GmAutomation";
        automationId: string;
        appId: string;
        name: string;
        description: string | null;
        enabled: boolean;
        actionKind: string;
        functionName: string | null;
        computeModuleName: string | null;
        computeExport: string | null;
        targetMode: string;
        selfContainerId: string | null;
        targetTypeName: string | null;
        sessionId: string | null;
        paramsJson: string;
        selectorJson: string | null;
        runAsUserId: string | null;
        triggerType: string;
        scheduleKind: string | null;
        intervalMs: number | null;
        cronExpr: string | null;
        maxTargets: number;
        maxFnDepth: number | null;
        gasLimit: number | null;
        runTimeoutMs: number | null;
        maxRunsPerMinute: number;
        failureThreshold: number;
        cooldownMs: number;
        circuitState: string;
        consecutiveFailures: number;
        pausedUntil: string | null;
        lastError: string | null;
        lastRunAt: string | null;
        nextRunAt: string | null;
    }>;
    /** Aggregate "what are my NPCs doing" stats over a recent window (admin). */
    stats(windowMinutes?: number): Promise<{
        __typename?: "GmAutomationStats";
        windowMinutes: number;
        totalRuns: number;
        failedRuns: number;
        failureRatePct: number;
        runsPerMinute: number;
        totalInvocations: number;
        totalMutations: number;
        totalComputeUnits: number;
        avgDurationUs: number;
        byAutomation: Array<{
            __typename?: "GmAutomationStat";
            automationName: string;
            runs: number;
            failures: number;
            invocations: number;
            computeUnits: number;
            avgDurationUs: number;
            circuitState: string;
        }>;
    }>;
    /** Recent automation run history, newest first (admin). */
    runs(options?: {
        automationName?: string;
        success?: boolean;
        limit?: number;
    }): Promise<{
        __typename?: "GmAutomationRun";
        runId: string;
        appId: string;
        flowId: string | null;
        automationId: string | null;
        automationName: string;
        triggerSource: string;
        triggerId: string | null;
        parentRunId: string | null;
        cascadeDepth: number;
        startedAt: string;
        finishedAt: string | null;
        durationUs: number;
        targets: number;
        invocations: number;
        mutations: number;
        fnCalls: number;
        gasUsed: number;
        success: boolean;
        errorMessage: string | null;
        circuitAction: string | null;
        computeUnits: number;
    }[]>;
    private toNpc;
}
//# sourceMappingURL=npcs.d.ts.map