@nice2dev/game-engine 0.1.0 → 1.0.3

package/dist/types/devtools/GameplayAnalytics.d.ts

@@ -0,0 +1,279 @@
+import { EventBus } from '../core/EventBus';
+import React from 'react';
+export type TelemetryEventCategory = 'gameplay' | 'combat' | 'navigation' | 'interaction' | 'economy' | 'social' | 'progression' | 'performance' | 'ui' | 'error' | 'custom';
+export type HeatmapType = 'death' | 'traversal' | 'interaction' | 'combat' | 'loot' | 'custom';
+export type SessionEventType = 'position' | 'action' | 'input' | 'state-change' | 'camera' | 'dialogue' | 'inventory' | 'quest';
+export interface TelemetryEvent {
+    id: string;
+    category: TelemetryEventCategory;
+    name: string;
+    timestamp: number;
+    sessionId: string;
+    userId?: string;
+    data: Record<string, unknown>;
+    position?: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    sceneId?: string;
+    /** Build/version where this event occurred */
+    buildVersion?: string;
+}
+export interface TelemetryConfig {
+    enabled: boolean;
+    /** Batch size before flush */
+    batchSize: number;
+    /** Flush interval (ms) */
+    flushIntervalMs: number;
+    /** Max events to keep in memory */
+    maxBufferSize: number;
+    /** Filter: only collect these categories (empty = all) */
+    categories: TelemetryEventCategory[];
+    /** Sample rate (0–1): fraction of events to keep */
+    sampleRate: number;
+    /** Custom endpoint for sending events */
+    endpoint?: string;
+}
+export declare const DEFAULT_TELEMETRY_CONFIG: TelemetryConfig;
+export interface HeatmapConfig {
+    type: HeatmapType;
+    /** Grid cell size in world units */
+    cellSize: number;
+    /** World bounds */
+    bounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+    /** Color gradient (value 0→1 mapped to colors) */
+    colorStops: {
+        value: number;
+        color: string;
+    }[];
+    /** Max value for normalization (0 = auto) */
+    maxValue: number;
+    /** Gaussian blur radius (cells) */
+    blurRadius: number;
+}
+export interface HeatmapCell {
+    x: number;
+    y: number;
+    value: number;
+    events: number;
+}
+export declare const DEFAULT_HEATMAP_CONFIG: HeatmapConfig;
+export interface SessionFrame {
+    timestamp: number;
+    delta: number;
+    events: SessionRecordedEvent[];
+}
+export interface SessionRecordedEvent {
+    type: SessionEventType;
+    data: Record<string, unknown>;
+}
+export interface SessionRecording {
+    id: string;
+    sessionId: string;
+    startedAt: number;
+    endedAt: number;
+    durationMs: number;
+    frameCount: number;
+    frames: SessionFrame[];
+    metadata: {
+        sceneId: string;
+        buildVersion: string;
+        playerLevel?: number;
+        tags: string[];
+    };
+    /** Compressed size in bytes (if compressed) */
+    sizeBytes: number;
+}
+export interface SessionRecordingConfig {
+    enabled: boolean;
+    /** Target frames per second for recording */
+    fps: number;
+    /** Max recording duration (ms, 0 = unlimited) */
+    maxDurationMs: number;
+    /** What events to record */
+    recordTypes: SessionEventType[];
+    /** Record player position every frame */
+    recordPosition: boolean;
+    /** Compress recording data */
+    compress: boolean;
+}
+export declare const DEFAULT_RECORDING_CONFIG: SessionRecordingConfig;
+export interface FunnelStep {
+    id: string;
+    name: string;
+    description?: string;
+    /** Number of users/sessions that reached this step */
+    count: number;
+    /** Drop-off rate from previous step */
+    dropOffRate: number;
+}
+export interface FunnelDefinition {
+    id: string;
+    name: string;
+    steps: {
+        id: string;
+        name: string;
+        eventName: string;
+    }[];
+}
+export declare class TelemetryPipeline {
+    private config;
+    private buffer;
+    private flushed;
+    private flushTimer;
+    private sessionId;
+    private eventCounter;
+    private eventBus;
+    constructor(eventBus: EventBus, config?: Partial<TelemetryConfig>);
+    private generateId;
+    /** Track a telemetry event */
+    track(category: TelemetryEventCategory, name: string, data?: Record<string, unknown>, position?: {
+        x: number;
+        y: number;
+        z?: number;
+    }): void;
+    /** Flush buffered events */
+    flush(): TelemetryEvent[];
+    private startFlushTimer;
+    /** Get all events (current buffer + flushed) */
+    getAllEvents(): TelemetryEvent[];
+    /** Get events by category */
+    getByCategory(category: TelemetryEventCategory): TelemetryEvent[];
+    /** Get event count by name */
+    countByName(name: string): number;
+    getSessionId(): string;
+    getBufferSize(): number;
+    getTotalEvents(): number;
+    clear(): void;
+    destroy(): void;
+}
+export declare class HeatmapGenerator {
+    private config;
+    private grid;
+    private totalEvents;
+    constructor(config?: Partial<HeatmapConfig>);
+    private cellKey;
+    private worldToCell;
+    /** Add an event at a world position */
+    addEvent(x: number, y: number, weight?: number): void;
+    /** Add events from telemetry data */
+    addFromTelemetry(events: TelemetryEvent[]): void;
+    /** Get the grid as an array of cells with normalized values */
+    getCells(): HeatmapCell[];
+    /** Apply Gaussian blur to the grid */
+    getBlurredCells(): HeatmapCell[];
+    /** Render heatmap to a canvas */
+    renderToCanvas(ctx: CanvasRenderingContext2D, width: number, height: number): void;
+    private interpolateColor;
+    private lerpColor;
+    getTotalEvents(): number;
+    getConfig(): Readonly<HeatmapConfig>;
+    clear(): void;
+}
+export declare class SessionRecorder {
+    private config;
+    private recording;
+    private frames;
+    private startedAt;
+    private lastFrameTime;
+    private pendingEvents;
+    private recordTimer;
+    private sessionId;
+    constructor(config?: Partial<SessionRecordingConfig>);
+    /** Start recording */
+    start(): void;
+    /** Stop recording and return the session */
+    stop(sceneId?: string, buildVersion?: string): SessionRecording;
+    /** Add an event to the current frame batch */
+    recordEvent(type: SessionEventType, data: Record<string, unknown>): void;
+    /** Record player position (convenience) */
+    recordPosition(x: number, y: number, z?: number): void;
+    private captureFrame;
+    isRecording(): boolean;
+    getFrameCount(): number;
+    getDurationMs(): number;
+}
+export declare class SessionPlayer {
+    private recording;
+    private currentFrame;
+    private playing;
+    private speed;
+    private playTimer;
+    private onFrame;
+    load(recording: SessionRecording): void;
+    /** Start playback */
+    play(onFrame: (frame: SessionFrame, index: number) => void): void;
+    private advanceFrame;
+    stop(): void;
+    pause(): void;
+    seek(frameIndex: number): void;
+    setSpeed(speed: number): void;
+    getProgress(): number;
+    isPlaying(): boolean;
+}
+export declare class FunnelTracker {
+    private funnels;
+    private progress;
+    define(funnel: FunnelDefinition): void;
+    /** Record that a session reached a funnel step */
+    recordStep(funnelId: string, stepEventName: string, sessionId: string): void;
+    /** Get funnel analysis */
+    analyze(funnelId: string): FunnelStep[];
+    getFunnels(): FunnelDefinition[];
+}
+export declare class GameplayAnalytics {
+    readonly telemetry: TelemetryPipeline;
+    readonly recorder: SessionRecorder;
+    readonly funnels: FunnelTracker;
+    private heatmaps;
+    private eventBus;
+    constructor(eventBus: EventBus, telemetryConfig?: Partial<TelemetryConfig>, recordingConfig?: Partial<SessionRecordingConfig>);
+    /** Create or get a heatmap */
+    heatmap(id: string, config?: Partial<HeatmapConfig>): HeatmapGenerator;
+    /** Track and automatically distribute to relevant heatmaps */
+    trackEvent(category: TelemetryEventCategory, name: string, data?: Record<string, unknown>, position?: {
+        x: number;
+        y: number;
+        z?: number;
+    }): void;
+    /** Get summary stats */
+    getSummary(): {
+        totalEvents: number;
+        sessionId: string;
+        heatmapCount: number;
+        isRecording: boolean;
+        recordedFrames: number;
+    };
+    destroy(): void;
+}
+export declare function useGameplayAnalytics(eventBus: EventBus, telemetryConfig?: Partial<TelemetryConfig>, recordingConfig?: Partial<SessionRecordingConfig>): {
+    analytics: GameplayAnalytics;
+    trackEvent: (category: TelemetryEventCategory, name: string, data?: Record<string, unknown>, position?: {
+        x: number;
+        y: number;
+        z?: number;
+    }) => void;
+    summary: {
+        totalEvents: number;
+        sessionId: string;
+        heatmapCount: number;
+        isRecording: boolean;
+        recordedFrames: number;
+    };
+    refreshSummary: () => void;
+    startRecording: () => void;
+    stopRecording: (sceneId?: string) => SessionRecording;
+    heatmap: (id: string, config?: Partial<HeatmapConfig>) => HeatmapGenerator;
+};
+export interface AnalyticsDashboardProps {
+    analytics: GameplayAnalytics;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare const AnalyticsDashboard: React.FC<AnalyticsDashboardProps>;

package/dist/types/dialogue/DialogueSystem.d.ts

@@ -0,0 +1,326 @@
+import type { Vec2 } from '../core/types';
+import { EventBus } from '../core/EventBus';
+import React from 'react';
+/** Dialogue node types */
+export type DialogueNodeType = 'start' | 'text' | 'choice' | 'branch' | 'set_variable' | 'check_variable' | 'event' | 'random' | 'end';
+/** Variable types supported in dialogues */
+export type DialogueVarType = 'boolean' | 'number' | 'string';
+/** Comparison operators for conditions */
+export type ComparisonOp = 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'startsWith' | 'endsWith';
+/** Character emotion types */
+export type EmotionType = 'neutral' | 'happy' | 'sad' | 'angry' | 'surprised' | 'scared' | 'disgusted' | 'confused' | 'thoughtful' | 'excited' | 'tired' | 'love' | 'custom';
+/** Text effect types */
+export type TextEffectType = 'none' | 'typewriter' | 'shake' | 'wave' | 'rainbow' | 'fade';
+export interface DialogueVariable {
+    id: string;
+    name: string;
+    type: DialogueVarType;
+    defaultValue: boolean | number | string;
+    description?: string;
+    persistent?: boolean;
+    scope: 'conversation' | 'global';
+}
+export interface VariableCondition {
+    variableId: string;
+    operator: ComparisonOp;
+    value: boolean | number | string;
+}
+export interface DialogueCharacter {
+    id: string;
+    name: string;
+    displayName: string;
+    /** Portrait images per emotion */
+    portraits: Record<EmotionType, string>;
+    voiceId?: string;
+    defaultEmotion: EmotionType;
+    textColor?: string;
+    nameColor?: string;
+    textSpeed?: number;
+}
+export interface DialogueNodeBase {
+    id: string;
+    type: DialogueNodeType;
+    position: Vec2;
+    comment?: string;
+    tags?: string[];
+}
+export interface StartNode extends DialogueNodeBase {
+    type: 'start';
+    label: string;
+    nextNode: string | null;
+}
+export interface TextNode extends DialogueNodeBase {
+    type: 'text';
+    characterId: string;
+    text: string;
+    emotion?: EmotionType;
+    textEffect?: TextEffectType;
+    audioClip?: string;
+    duration?: number;
+    nextNode: string | null;
+}
+export interface ChoiceOption {
+    id: string;
+    text: string;
+    nextNode: string | null;
+    conditions?: VariableCondition[];
+    /** Variables to set when this choice is selected */
+    setVariables?: {
+        variableId: string;
+        value: boolean | number | string;
+    }[];
+    disabled?: boolean;
+    tooltip?: string;
+}
+export interface ChoiceNode extends DialogueNodeBase {
+    type: 'choice';
+    characterId?: string;
+    prompt?: string;
+    options: ChoiceOption[];
+    timeout?: number;
+    defaultOption?: string;
+}
+export interface BranchNode extends DialogueNodeBase {
+    type: 'branch';
+    conditions: VariableCondition[];
+    /** AND or OR logic for multiple conditions */
+    logic: 'and' | 'or';
+    trueNode: string | null;
+    falseNode: string | null;
+}
+export interface SetVariableNode extends DialogueNodeBase {
+    type: 'set_variable';
+    variableId: string;
+    operation: 'set' | 'add' | 'subtract' | 'multiply' | 'toggle' | 'append';
+    value: boolean | number | string;
+    nextNode: string | null;
+}
+export interface CheckVariableNode extends DialogueNodeBase {
+    type: 'check_variable';
+    conditions: VariableCondition[];
+    logic: 'and' | 'or';
+    trueNode: string | null;
+    falseNode: string | null;
+}
+export interface EventNode extends DialogueNodeBase {
+    type: 'event';
+    eventType: string;
+    eventData: Record<string, unknown>;
+    nextNode: string | null;
+}
+export interface RandomNode extends DialogueNodeBase {
+    type: 'random';
+    outputs: {
+        id: string;
+        weight: number;
+        nextNode: string | null;
+    }[];
+}
+export interface EndNode extends DialogueNodeBase {
+    type: 'end';
+    result?: 'success' | 'failure' | 'neutral';
+    setVariables?: {
+        variableId: string;
+        value: boolean | number | string;
+    }[];
+}
+export type DialogueNode = StartNode | TextNode | ChoiceNode | BranchNode | SetVariableNode | CheckVariableNode | EventNode | RandomNode | EndNode;
+export interface DialogueTree {
+    id: string;
+    name: string;
+    description?: string;
+    version: string;
+    characters: DialogueCharacter[];
+    variables: DialogueVariable[];
+    nodes: DialogueNode[];
+    startNodeId: string;
+    metadata: {
+        author?: string;
+        created: string;
+        modified: string;
+        tags?: string[];
+        locale: string;
+    };
+}
+export interface DialogueState {
+    treeId: string;
+    currentNodeId: string | null;
+    variables: Record<string, boolean | number | string>;
+    history: string[];
+    choicesMade: {
+        nodeId: string;
+        optionId: string;
+        timestamp: number;
+    }[];
+    startTime: number;
+    isActive: boolean;
+    isPaused: boolean;
+}
+export type DialogueEventType = 'dialogue:started' | 'dialogue:ended' | 'dialogue:node-entered' | 'dialogue:text-displayed' | 'dialogue:choice-selected' | 'dialogue:variable-changed' | 'dialogue:event-triggered' | 'dialogue:paused' | 'dialogue:resumed';
+export interface DialogueEvent {
+    type: DialogueEventType;
+    treeId: string;
+    nodeId?: string;
+    data?: unknown;
+    timestamp: number;
+}
+export declare class DialogueEngine {
+    private trees;
+    private globalVariables;
+    private currentState;
+    private events;
+    private onTextCallback?;
+    private onChoiceCallback?;
+    private onEndCallback?;
+    constructor(events?: EventBus);
+    registerTree(tree: DialogueTree): void;
+    unregisterTree(treeId: string): void;
+    getTree(treeId: string): DialogueTree | undefined;
+    getAllTrees(): DialogueTree[];
+    setGlobalVariable(name: string, value: boolean | number | string): void;
+    getGlobalVariable(name: string): boolean | number | string | undefined;
+    getVariable(variableId: string): boolean | number | string | undefined;
+    private setVariable;
+    startDialogue(treeId: string, startLabel?: string): boolean;
+    endDialogue(): void;
+    pauseDialogue(): void;
+    resumeDialogue(): void;
+    getState(): DialogueState | null;
+    isActive(): boolean;
+    private goToNode;
+    private processNode;
+    private processTextNode;
+    private processChoiceNode;
+    private processBranchNode;
+    private processSetVariableNode;
+    private processEventNode;
+    private processRandomNode;
+    private processEndNode;
+    selectChoice(optionId: string): boolean;
+    /** Advance to next node (for text nodes) */
+    advance(): boolean;
+    private evaluateConditions;
+    private evaluateCondition;
+    onText(callback: (node: TextNode, character: DialogueCharacter) => void): void;
+    onChoice(callback: (node: ChoiceNode, options: ChoiceOption[]) => void): void;
+    onEnd(callback: (node: EndNode, state: DialogueState) => void): void;
+    private emitEvent;
+    subscribe(eventType: DialogueEventType, handler: (event: DialogueEvent) => void): () => void;
+}
+export declare class DialogueTreeBuilder {
+    private tree;
+    private nodeCounter;
+    constructor(id: string, name: string);
+    private generateId;
+    description(desc: string): this;
+    author(author: string): this;
+    locale(locale: string): this;
+    tags(tags: string[]): this;
+    addCharacter(character: DialogueCharacter): this;
+    addVariable(variable: DialogueVariable): this;
+    boolVar(id: string, name: string, defaultValue?: boolean, scope?: 'conversation' | 'global'): this;
+    numVar(id: string, name: string, defaultValue?: number, scope?: 'conversation' | 'global'): this;
+    strVar(id: string, name: string, defaultValue?: string, scope?: 'conversation' | 'global'): this;
+    addStart(label: string, nextNode?: string | null, position?: Vec2): this;
+    addText(characterId: string, text: string, nextNode?: string | null, options?: Partial<Omit<TextNode, 'id' | 'type' | 'characterId' | 'text' | 'nextNode'>>): this;
+    addChoice(options: ChoiceOption[], settings?: Partial<Omit<ChoiceNode, 'id' | 'type' | 'options'>>): this;
+    addBranch(conditions: VariableCondition[], trueNode: string | null, falseNode: string | null, logic?: 'and' | 'or', position?: Vec2): this;
+    addSetVariable(variableId: string, operation: SetVariableNode['operation'], value: boolean | number | string, nextNode?: string | null, position?: Vec2): this;
+    addEvent(eventType: string, eventData: Record<string, unknown>, nextNode?: string | null, position?: Vec2): this;
+    addRandom(outputs: {
+        weight: number;
+        nextNode: string | null;
+    }[], position?: Vec2): this;
+    addEnd(result?: EndNode['result'], setVariables?: EndNode['setVariables'], position?: Vec2): this;
+    build(): DialogueTree;
+    /** Get the ID of the last added node */
+    lastNodeId(): string;
+    /** Get node by index (1-based for readability) */
+    nodeId(index: number): string;
+}
+export interface DialogueBoxProps {
+    /** The text to display */
+    text: string;
+    /** Character name */
+    characterName?: string;
+    /** Character portrait URL */
+    portrait?: string;
+    /** Emotion for styling */
+    emotion?: EmotionType;
+    /** Text effect */
+    textEffect?: TextEffectType;
+    /** Characters per second for typewriter effect */
+    textSpeed?: number;
+    /** Called when text fully displayed */
+    onComplete?: () => void;
+    /** Called when user clicks to advance */
+    onAdvance?: () => void;
+    /** Custom styles */
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * React hook for typewriter text effect
+ */
+export declare function useTypewriter(text: string, speed?: number, enabled?: boolean): {
+    displayedText: string;
+    isComplete: boolean;
+    skip: () => void;
+};
+/**
+ * DialogueBox component for displaying dialogue text
+ */
+export declare const DialogueBox: React.FC<DialogueBoxProps>;
+export interface ChoiceListProps {
+    /** Available choices */
+    options: ChoiceOption[];
+    /** Prompt text */
+    prompt?: string;
+    /** Called when a choice is selected */
+    onSelect: (optionId: string) => void;
+    /** Timeout in ms (optional) */
+    timeout?: number;
+    /** Custom styles */
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * ChoiceList component for displaying dialogue choices
+ */
+export declare const ChoiceList: React.FC<ChoiceListProps>;
+/**
+ * Serialize dialogue tree to JSON string
+ */
+export declare function serializeDialogueTree(tree: DialogueTree): string;
+/**
+ * Deserialize dialogue tree from JSON string
+ */
+export declare function deserializeDialogueTree(json: string): DialogueTree;
+/**
+ * Validate dialogue tree structure
+ */
+export declare function validateDialogueTree(tree: unknown): DialogueTree;
+/**
+ * Find unreachable nodes in dialogue tree
+ */
+export declare function findUnreachableNodes(tree: DialogueTree): string[];
+export interface DialogueLocalization {
+    treeId: string;
+    locale: string;
+    texts: Record<string, string>;
+    characterNames: Record<string, string>;
+}
+/**
+ * Extract all translatable strings from a dialogue tree
+ */
+export declare function extractTranslatableStrings(tree: DialogueTree): {
+    nodeTexts: Record<string, string>;
+    characterNames: Record<string, string>;
+};
+/**
+ * Apply localization to a dialogue tree (creates a copy)
+ */
+export declare function applyLocalization(tree: DialogueTree, localization: DialogueLocalization): DialogueTree;
+export declare const DEFAULT_TEXT_SPEED = 50;
+export declare const EMOTION_COLORS: Record<EmotionType, string>;
+export declare function createEmptyDialogueTree(id: string, name: string): DialogueTree;

package/dist/types/dialogue/index.d.ts

@@ -0,0 +1,2 @@
+export { DialogueEngine, DialogueTreeBuilder, DialogueBox, ChoiceList, useTypewriter, serializeDialogueTree, deserializeDialogueTree, validateDialogueTree, findUnreachableNodes, extractTranslatableStrings, applyLocalization, DEFAULT_TEXT_SPEED, EMOTION_COLORS, createEmptyDialogueTree, } from './DialogueSystem';
+export type { DialogueNodeType, DialogueNode, DialogueNodeBase, StartNode, TextNode, ChoiceNode, ChoiceOption, BranchNode, SetVariableNode, CheckVariableNode, EventNode, RandomNode, EndNode, DialogueVarType, DialogueVariable, VariableCondition, ComparisonOp, DialogueCharacter, EmotionType, TextEffectType, DialogueTree, DialogueState, DialogueEventType, DialogueEvent, DialogueLocalization, DialogueBoxProps, ChoiceListProps, } from './DialogueSystem';

package/dist/types/editor/NiceGameEditor.d.ts

@@ -1,7 +1,7 @@
 import React from 'react';
 import type { GameProject, EntityId } from '../core/types';
 import { EventBus } from '../core/EventBus';
-import { World } from '../ecs/World';
+import { World, type ComponentMap } from '../ecs/World';
 import { SceneManager } from '../scene/SceneManager';
 export interface UndoEntry {
     description: string;
@@ -94,6 +94,12 @@ type EditorAction = {
 } | {
     type: 'MARK_CLEAN';
 };
+export interface ConsoleEntry {
+    id: number;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    timestamp: number;
+}
 export interface EditorContextValue {
     state: EditorState;
     dispatch: React.Dispatch<EditorAction>;
@@ -101,6 +107,11 @@ export interface EditorContextValue {
     undoStack: UndoStack;
     sceneManager: SceneManager;
     events: EventBus;
+    worldVersion: number;
+    refreshWorld: () => void;
+    createNewEntity: (name: string, components?: (keyof ComponentMap)[]) => number;
+    consoleLogs: ConsoleEntry[];
+    addLog: (level: ConsoleEntry['level'], message: string) => void;
 }
 export declare function useEditor(): EditorContextValue;
 export declare function serializeProject(project: GameProject): string;