@nice2dev/game-engine 0.1.0

package/dist/types/plugins/PluginSDK.d.ts

@@ -0,0 +1,134 @@
+import { EventBus } from '../core/EventBus';
+export type PluginState = 'installed' | 'active' | 'inactive' | 'error';
+export type PluginType = 'component' | 'system' | 'node' | 'editor-panel' | 'renderer' | 'template';
+export interface PluginManifest {
+    /** Unique plugin ID (reverse domain: com.author.plugin-name). */
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    license?: string;
+    homepage?: string;
+    repository?: string;
+    /** Plugin types this plugin provides. */
+    types: PluginType[];
+    /** engine version compatibility (semver range). */
+    engineVersion: string;
+    /** Dependencies (other plugin IDs → semver ranges). */
+    dependencies?: Record<string, string>;
+    /** Keywords for marketplace search. */
+    keywords?: string[];
+    /** Icon (data URL or relative path). */
+    icon?: string;
+    /** Entry point filename (relative). */
+    main?: string;
+}
+/** The context passed to plugins on activation. */
+export interface PluginContext {
+    /** Plugin's own manifest. */
+    manifest: PluginManifest;
+    /** Engine event bus for communication. */
+    events: EventBus;
+    /** Register an extension point entry. */
+    registerExtension: <T>(point: ExtensionPoint, entry: T) => void;
+    /** Unregister an extension point entry. */
+    unregisterExtension: <T>(point: ExtensionPoint, entry: T) => void;
+    /** Plugin-scoped storage (persisted). */
+    storage: PluginStorage;
+    /** Log a message under the plugin's namespace. */
+    log: (message: string) => void;
+    /** Log a warning under the plugin's namespace. */
+    warn: (message: string) => void;
+}
+/** Interface a plugin must implement. */
+export interface PluginDefinition {
+    /** Plugin manifest (metadata). */
+    manifest: PluginManifest;
+    /** Called when the plugin is activated. */
+    activate(ctx: PluginContext): void | Promise<void>;
+    /** Called when the plugin is deactivated. */
+    deactivate?(ctx: PluginContext): void | Promise<void>;
+    /** Called when the plugin is uninstalled (cleanup permanent data). */
+    uninstall?(ctx: PluginContext): void | Promise<void>;
+}
+export type ExtensionPoint = 'component-type' | 'system-type' | 'node-type' | 'editor-panel' | 'renderer-pass' | 'asset-importer' | 'game-template' | 'menu-item';
+export interface PluginStorage {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+    clear(): void;
+    keys(): string[];
+}
+/** Plugin instance (managed by PluginManager). */
+export interface PluginInstance {
+    definition: PluginDefinition;
+    state: PluginState;
+    activatedAt: number | null;
+    error: string | null;
+    extensions: Map<ExtensionPoint, unknown[]>;
+}
+export declare class PluginManager {
+    readonly events: EventBus;
+    private plugins;
+    private extensions;
+    install(definition: PluginDefinition): void;
+    activate(id: string): Promise<void>;
+    deactivate(id: string): Promise<void>;
+    uninstall(id: string): Promise<void>;
+    getPlugin(id: string): PluginInstance | undefined;
+    get allPlugins(): PluginInstance[];
+    get activePlugins(): PluginInstance[];
+    getExtensions<T>(point: ExtensionPoint): T[];
+    /** Search plugins by keyword. */
+    search(query: string): PluginInstance[];
+    private createContext;
+    /** Deactivate and remove all plugins. */
+    dispose(): Promise<void>;
+}
+export interface PluginTemplate {
+    type: PluginType;
+    name: string;
+    description: string;
+    /** Template code (TypeScript source). */
+    code: string;
+}
+export declare const PLUGIN_TEMPLATES: PluginTemplate[];
+export interface MarketplaceEntry {
+    id: string;
+    name: string;
+    description: string;
+    author: string;
+    version: string;
+    downloads: number;
+    rating: number;
+    types: PluginType[];
+    keywords: string[];
+    icon?: string;
+    free: boolean;
+    price?: number;
+    updated: string;
+}
+export interface MarketplaceSearchResult {
+    entries: MarketplaceEntry[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/** Offline-capable marketplace API (can be backed by REST later). */
+export declare class PluginMarketplace {
+    private catalog;
+    /** Register entries in the catalog (for offline/bundled). */
+    addEntries(entries: MarketplaceEntry[]): void;
+    /** Search the marketplace. */
+    search(query: string, options?: {
+        type?: PluginType;
+        free?: boolean;
+        page?: number;
+        pageSize?: number;
+    }): MarketplaceSearchResult;
+    /** Get a single entry by ID. */
+    getEntry(id: string): MarketplaceEntry | undefined;
+    /** Featured / top-rated plugins. */
+    getFeatured(count?: number): MarketplaceEntry[];
+}

package/dist/types/plugins/PluginTestKit.d.ts

@@ -0,0 +1,107 @@
+import { EventBus } from '../core/EventBus';
+import type { PluginDefinition, PluginContext, PluginManifest, ExtensionPoint, PluginStorage } from './PluginSDK';
+export type TestStatus = 'passed' | 'failed' | 'skipped';
+export interface TestResult {
+    name: string;
+    status: TestStatus;
+    duration: number;
+    error?: string;
+}
+export interface TestSuiteResult {
+    pluginId: string;
+    suiteName: string;
+    results: TestResult[];
+    passed: number;
+    failed: number;
+    skipped: number;
+    totalDuration: number;
+}
+export interface PluginTestCase {
+    name: string;
+    skip?: boolean;
+    fn: (ctx: TestPluginContext) => void | Promise<void>;
+}
+export declare class TestPluginStorage implements PluginStorage {
+    private data;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+    clear(): void;
+    keys(): string[];
+    /** Snapshot current storage state for assertions. */
+    snapshot(): Record<string, unknown>;
+    get size(): number;
+}
+export declare class TestPluginContext implements PluginContext {
+    readonly manifest: PluginManifest;
+    readonly events: EventBus;
+    readonly storage: TestPluginStorage;
+    readonly logs: string[];
+    readonly warnings: string[];
+    readonly registeredExtensions: Map<ExtensionPoint, unknown[]>;
+    constructor(manifest: PluginManifest);
+    log: (message: string) => void;
+    warn: (message: string) => void;
+    registerExtension: <T>(point: ExtensionPoint, entry: T) => void;
+    unregisterExtension: <T>(point: ExtensionPoint, entry: T) => void;
+    /** Get all extensions registered for a given point. */
+    getExtensions<T>(point: ExtensionPoint): T[];
+    /** Count extensions for a given point. */
+    extensionCount(point: ExtensionPoint): number;
+    /** Check if any extension was registered for a given point. */
+    hasExtension(point: ExtensionPoint): boolean;
+    /** Get storage snapshot for assertion/comparison. */
+    storageSnapshot(): Record<string, unknown>;
+    /** Reset context to fresh state (between tests). */
+    reset(): void;
+}
+export declare class PluginAssertionError extends Error {
+    constructor(message: string);
+}
+export declare const pluginAssert: {
+    /** Assert value is truthy. */
+    ok(value: unknown, message?: string): void;
+    /** Assert strict equality. */
+    equal<T>(actual: T, expected: T, message?: string): void;
+    /** Assert not equal. */
+    notEqual<T>(actual: T, notExpected: T, message?: string): void;
+    /** Assert deep equality (JSON comparison). */
+    deepEqual(actual: unknown, expected: unknown, message?: string): void;
+    /** Assert that a function throws. */
+    throws(fn: () => unknown, message?: string): void;
+    /** Assert async function throws. */
+    throwsAsync(fn: () => Promise<unknown>, message?: string): Promise<void>;
+    /** Assert array contains element. */
+    contains<T>(arr: readonly T[], item: T, message?: string): void;
+    /** Assert string includes substring. */
+    includes(str: string, substr: string, message?: string): void;
+    /** Assert extension was registered. */
+    hasExtension(ctx: TestPluginContext, point: ExtensionPoint, message?: string): void;
+    /** Assert extension count. */
+    extensionCount(ctx: TestPluginContext, point: ExtensionPoint, expected: number, message?: string): void;
+    /** Assert log message was emitted. */
+    logged(ctx: TestPluginContext, substr: string, message?: string): void;
+    /** Assert warning was emitted. */
+    warned(ctx: TestPluginContext, substr: string, message?: string): void;
+};
+export declare class PluginTestRunner {
+    private tests;
+    private _beforeEach;
+    private _afterEach;
+    /** Add a test case. */
+    test(name: string, fn: (ctx: TestPluginContext) => void | Promise<void>): this;
+    /** Add a skipped test case. */
+    skip(name: string, fn: (ctx: TestPluginContext) => void | Promise<void>): this;
+    /** Run something before each test. */
+    beforeEach(fn: (ctx: TestPluginContext) => void | Promise<void>): this;
+    /** Run something after each test. */
+    afterEach(fn: (ctx: TestPluginContext) => void | Promise<void>): this;
+    /** Run all tests against a plugin. */
+    run(plugin: PluginDefinition, suiteName?: string): Promise<TestSuiteResult>;
+}
+/** Create a default manifest for testing. */
+export declare function createTestManifest(overrides?: Partial<PluginManifest>): PluginManifest;
+/** Quick lifecycle test — activate, verify, deactivate. */
+export declare function testPluginLifecycle(plugin: PluginDefinition): Promise<TestSuiteResult>;
+/** Format test results as a readable string. */
+export declare function formatTestResults(suite: TestSuiteResult): string;

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

@@ -0,0 +1,2 @@
+export * from './PluginSDK';
+export * from './PluginTestKit';

package/dist/types/procedural/Procedural.d.ts

@@ -0,0 +1,90 @@
+import type { Vec2, Color } from '../core/types';
+export declare class SeededRandom {
+    private s;
+    constructor(seed?: number);
+    /** Returns [0, 1). */
+    next(): number;
+    /** Returns integer in [min, max] (inclusive). */
+    int(min: number, max: number): number;
+    /** Returns float in [min, max). */
+    float(min: number, max: number): number;
+    /** Returns true with given probability (0-1). */
+    chance(probability: number): boolean;
+    /** Pick a random element from an array. */
+    pick<T>(arr: readonly T[]): T;
+    /** Shuffle array in-place (Fisher-Yates). */
+    shuffle<T>(arr: T[]): T[];
+    /** Weighted random pick. Returns index. */
+    weighted(weights: number[]): number;
+    /** Random color. */
+    color(alpha?: number): Color;
+    /** Random unit vector. */
+    unitVec2(): Vec2;
+    /** Random point inside a circle. */
+    insideCircle(radius: number): Vec2;
+}
+export declare class PerlinNoise {
+    private perm;
+    constructor(seed?: number);
+    /** Get noise value at (x, y) → [-1, 1]. */
+    noise2D(x: number, y: number): number;
+    /** Fractal Brownian Motion (layered noise). */
+    fbm(x: number, y: number, octaves?: number, lacunarity?: number, gain?: number): number;
+}
+export interface WaveEntry {
+    type: string;
+    count: number;
+    delay: number;
+    spawnInterval: number;
+}
+export interface WaveConfig {
+    baseEnemyCount: number;
+    countGrowth: number;
+    typeProbabilities: {
+        type: string;
+        weight: number;
+        minWave: number;
+    }[];
+    groupSize: [number, number];
+    groupDelay: [number, number];
+    spawnInterval: [number, number];
+}
+export declare class WaveGenerator {
+    private rng;
+    constructor(seed?: number);
+    generateWave(waveNumber: number, config: WaveConfig): WaveEntry[];
+}
+export interface LootDrop {
+    id: string;
+    weight: number;
+    /** Drop quantity range. */
+    quantity: [number, number];
+    /** Minimum level to be eligible. */
+    minLevel?: number;
+    /** Maximum number of times this can drop per roll session. */
+    maxPerRoll?: number;
+}
+export declare class LootTable {
+    private rng;
+    private drops;
+    constructor(drops: LootDrop[], seed?: number);
+    /** Roll N items from the table. */
+    roll(count: number, level?: number): {
+        id: string;
+        quantity: number;
+    }[];
+    /** Simple yes/no chance to drop each item independently. */
+    rollEach(level?: number): {
+        id: string;
+        quantity: number;
+    }[];
+}
+export declare class ProceduralSprite {
+    private rng;
+    constructor(seed?: number);
+    /**
+     * Generate a symmetrical pixel art sprite as ImageData.
+     * Good for enemies, ships, items.
+     */
+    generate(width: number, height: number, palette: Color[], symmetry?: 'none' | 'horizontal' | 'vertical' | 'both'): ImageData;
+}

package/dist/types/procedural/WorldBuilding.d.ts

@@ -0,0 +1,200 @@
+import type { Vec2 } from '../core/types';
+export interface WorldStreamingConfig {
+    chunkSize: number;
+    loadRadius: number;
+    unloadRadius: number;
+    preloadRadius: number;
+    maxLoadedChunks: number;
+    loadPriority: 'distance' | 'direction' | 'combined';
+    transitionBlend: number;
+}
+export declare const DEFAULT_STREAMING: WorldStreamingConfig;
+export interface WorldChunk {
+    x: number;
+    y: number;
+    state: 'unloaded' | 'loading' | 'loaded' | 'active' | 'unloading';
+    entities: string[];
+    terrain?: ChunkTerrain;
+    lastAccess: number;
+    priority: number;
+}
+export interface ChunkTerrain {
+    heightmap: Float32Array;
+    biome: string;
+    decorations: TerrainDecoration[];
+}
+export interface TerrainDecoration {
+    type: string;
+    position: Vec2;
+    scale: number;
+    rotation: number;
+    variant: number;
+}
+export declare function getChunkCoord(worldPos: Vec2, chunkSize: number): {
+    cx: number;
+    cy: number;
+};
+export declare function getChunksInRadius(centerChunk: {
+    cx: number;
+    cy: number;
+}, radius: number): Array<{
+    cx: number;
+    cy: number;
+}>;
+export declare function chunkKey(cx: number, cy: number): string;
+export interface TerrainGenConfig {
+    seed: number;
+    octaves: number;
+    frequency: number;
+    amplitude: number;
+    lacunarity: number;
+    persistence: number;
+    heightScale: number;
+    erosionPasses: number;
+    biomes: BiomeDef[];
+    waterLevel: number;
+}
+export interface BiomeDef {
+    name: string;
+    minHeight: number;
+    maxHeight: number;
+    minMoisture: number;
+    maxMoisture: number;
+    color: string;
+    vegetation: VegetationRule[];
+    tileType: string;
+}
+export interface VegetationRule {
+    type: string;
+    density: number;
+    minScale: number;
+    maxScale: number;
+    clusterSize: number;
+    avoidRadius: number;
+}
+/** Simple value noise. */
+export declare function valueNoise2D(x: number, y: number, seed: number): number;
+/** Fractal Brownian Motion. */
+export declare function fbm(x: number, y: number, config: TerrainGenConfig): number;
+export declare function selectBiome(height: number, moisture: number, biomes: BiomeDef[]): BiomeDef | null;
+export declare const DEFAULT_BIOMES: BiomeDef[];
+export type WeatherType = 'clear' | 'cloudy' | 'rain' | 'heavy-rain' | 'storm' | 'snow' | 'blizzard' | 'fog' | 'sandstorm';
+export interface WeatherConfig {
+    type: WeatherType;
+    intensity: number;
+    windDirection: number;
+    windSpeed: number;
+    temperature: number;
+    humidity: number;
+    visibility: number;
+    lightingMultiplier: number;
+    particleDensity: number;
+    soundId?: string;
+    transitionDuration: number;
+}
+export interface WeatherSchedule {
+    entries: WeatherScheduleEntry[];
+    transitionDuration: number;
+    randomVariation: number;
+}
+export interface WeatherScheduleEntry {
+    startHour: number;
+    duration: number;
+    weather: WeatherType;
+    probability: number;
+    minIntensity: number;
+    maxIntensity: number;
+}
+export declare const WEATHER_PRESETS: Record<WeatherType, Partial<WeatherConfig>>;
+export declare function lerpWeather(a: WeatherConfig, b: WeatherConfig, t: number): WeatherConfig;
+export interface DayNightConfig {
+    dayLengthSeconds: number;
+    startHour: number;
+    sunriseHour: number;
+    sunsetHour: number;
+    ambientDay: string;
+    ambientNight: string;
+    ambientSunrise: string;
+    ambientSunset: string;
+    sunIntensityDay: number;
+    sunIntensityNight: number;
+    moonPhase: boolean;
+    starsAtNight: boolean;
+}
+export declare const DEFAULT_DAY_NIGHT: DayNightConfig;
+export type TimeOfDay = 'night' | 'dawn' | 'morning' | 'noon' | 'afternoon' | 'dusk';
+export declare function getTimeOfDay(hour: number): TimeOfDay;
+export declare function getGameHour(realElapsedSeconds: number, config: DayNightConfig): number;
+export declare function getSunAngle(hour: number, config: DayNightConfig): number;
+export interface NPCSchedule {
+    npcId: string;
+    entries: ScheduleEntry[];
+    defaultActivity: string;
+    defaultLocation: string;
+}
+export interface ScheduleEntry {
+    startHour: number;
+    endHour: number;
+    activity: string;
+    location: string;
+    waypoints?: Vec2[];
+    priority: number;
+    daysOfWeek?: number[];
+    conditions?: string[];
+}
+export declare function getCurrentScheduleEntry(schedule: NPCSchedule, hour: number, dayOfWeek: number): ScheduleEntry | null;
+export type QuestState = 'unavailable' | 'available' | 'active' | 'completed' | 'failed' | 'turned-in';
+export type ObjectiveType = 'kill' | 'collect' | 'deliver' | 'talk' | 'escort' | 'explore' | 'interact' | 'survive' | 'custom';
+export interface QuestDef {
+    id: string;
+    title: string;
+    description: string;
+    category: 'main' | 'side' | 'daily' | 'repeatable' | 'hidden';
+    level: number;
+    prerequisites: string[];
+    objectives: QuestObjective[];
+    rewards: QuestReward[];
+    timeLimit?: number;
+    failConditions?: string[];
+    dialogStart?: string;
+    dialogComplete?: string;
+    chain?: string;
+    repeatable: boolean;
+    autoComplete: boolean;
+}
+export interface QuestObjective {
+    id: string;
+    type: ObjectiveType;
+    description: string;
+    targetId?: string;
+    targetCount: number;
+    currentCount: number;
+    optional: boolean;
+    hidden: boolean;
+    location?: Vec2;
+    radius?: number;
+}
+export interface QuestReward {
+    type: 'xp' | 'gold' | 'item' | 'reputation' | 'unlock' | 'skill-point';
+    amount: number;
+    itemId?: string;
+    factionId?: string;
+}
+export interface QuestJournal {
+    activeQuests: QuestInstance[];
+    completedQuests: string[];
+    failedQuests: string[];
+    trackedQuestId?: string;
+}
+export interface QuestInstance {
+    questId: string;
+    state: QuestState;
+    objectives: QuestObjective[];
+    startTime: number;
+    completedTime?: number;
+}
+export declare function canStartQuest(questDef: QuestDef, journal: QuestJournal): boolean;
+export declare function startQuest(questDef: QuestDef, journal: QuestJournal): QuestInstance;
+export declare function updateObjective(instance: QuestInstance, objectiveId: string, incrementBy?: number): boolean;
+export declare function isQuestComplete(instance: QuestInstance): boolean;
+export declare function completeQuest(instance: QuestInstance, journal: QuestJournal): void;

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

@@ -0,0 +1,2 @@
+export { SeededRandom, PerlinNoise, WaveGenerator, LootTable, ProceduralSprite } from './Procedural';
+export type { WaveEntry, WaveConfig, LootDrop } from './Procedural';