@fonsecabarreto/genesis-gl-core 0.1.0

package/dist/Editor/index.d.ts

@@ -0,0 +1,364 @@
+import { Vector3 } from '../Core/domain/interfaces/Vectors.js';
+
+/** Plain, JSON-serialisable description of a material preset. */
+interface MaterialSpec {
+    /** Unique identifier (crypto.randomUUID). */
+    id: string;
+    /** Human-readable name shown in the UI. */
+    name: string;
+    /** RGBA albedo / base colour [0–1]. */
+    albedoColor: [number, number, number, number];
+    /** RGB diffuse colour [0–1]. */
+    diffuse: [number, number, number];
+    /** RGB ambient colour [0–1]. */
+    ambientColor: [number, number, number];
+    /** RGB specular colour [0–1]. */
+    specular: [number, number, number];
+    /** Phong shininess exponent. */
+    shininess: number;
+    /** Opacity (d / Tr). */
+    dissolve: number;
+    /** Skip lighting calculations and render with raw albedo. */
+    unlit: boolean;
+    /** Render both front and back faces. */
+    doubleSided: boolean;
+    /** Optional public path to a texture image (relative to /public). */
+    texturePath?: string;
+    /** When true the texture wraps with GL_REPEAT instead of CLAMP_TO_EDGE. */
+    textureRepeat?: boolean;
+    /** Physics friction coefficient [0–1]. Defaults to 0.75 when omitted. */
+    friction?: number;
+}
+/** Create a spec with sensible defaults. */
+declare function createDefaultSpec(name?: string): MaterialSpec;
+
+type StoreListener$1 = (specs: MaterialSpec[]) => void;
+interface MaterialStoreOptions {
+    /**
+     * URL / public-folder path to a JSON file that seeds the store on {@link MaterialStore.init}.
+     * Example: `'data/materials.json'`
+     *
+     * The file is fetched once with `fetch()` during init. If the fetch succeeds its
+     * contents supersede anything already in `localStorage`.
+     */
+    filePath?: string;
+}
+/**
+ * Manages a collection of {@link MaterialSpec} presets.
+ *
+ * - Automatically persists to `localStorage` on every change (synchronous).
+ * - Call {@link init} once at startup to seed from a configurable JSON file.
+ * - Supports exporting / importing the whole collection as a `.json` file.
+ */
+declare class MaterialStore {
+    private specs;
+    private listeners;
+    private readonly filePath;
+    constructor(options?: MaterialStoreOptions);
+    /**
+     * Asynchronously loads materials from the configured {@link MaterialStoreOptions.filePath}.
+     * Call this once during app / resource initialisation (e.g. inside `loadResources`).
+     *
+     * The file data is merged on top of any localStorage data; conflicting IDs are
+     * overwritten by the file version.
+     */
+    init(): Promise<void>;
+    getAll(): MaterialSpec[];
+    get(id: string): MaterialSpec | undefined;
+    /** Add a brand-new spec and return it. */
+    create(name?: string): MaterialSpec;
+    /** Replace an existing spec (matched by id). */
+    update(spec: MaterialSpec): void;
+    /** Deep-clone a spec under a new id. */
+    duplicate(id: string): MaterialSpec | undefined;
+    delete(id: string): void;
+    /**
+     * Write the full collection to the server's `materials.json` via the
+     * `PUT /api/materials` endpoint provided by the Vite dev plugin.
+     * Silently no-ops if no `filePath` was configured.
+     */
+    syncToServer(): Promise<boolean>;
+    private persist;
+    private loadFromStorage;
+    /** Download the full collection as a `.json` file (defaults to the configured filePath name). */
+    exportToFile(filename?: string): Promise<void>;
+    /**
+     * Open a file-picker, parse the JSON, and merge imported specs.
+     * Existing specs with the same id are overwritten.
+     */
+    importFromFile(): Promise<void>;
+    subscribe(fn: StoreListener$1): () => void;
+    private emit;
+}
+
+/** JSON-serialisable description of a single item placed in the scene. */
+interface SceneItemSpec {
+    /** Unique identifier (crypto.randomUUID). */
+    id: string;
+    /** Human-readable label shown in the editor. */
+    name: string;
+    /**
+     * Key used to look up the base model in the DI / resource container.
+     * The model must have been loaded during resource initialisation.
+     */
+    resourceKey: string;
+    translation: Vector3;
+    rotation: Vector3;
+    scale: Vector3;
+    /**
+     * Custom AABB override relative to translation:
+     * `[offsetX, offsetY, offsetZ, width, height, depth]`.
+     * When `null` or omitted the model's auto-computed bbox is used.
+     */
+    bounds?: [number, number, number, number, number, number] | null;
+    /** Whether this item participates in collision detection. Defaults to `true`. */
+    collider?: boolean;
+    /**
+     * Optional material name (from `materials.json`) to override the model's
+     * default material. Applied to all meshes in the model at placement time.
+     */
+    materialKey?: string | null;
+}
+/** Top-level scene definition stored in `scene.json`. */
+interface SceneSpec {
+    /** World position where the player spawns. */
+    playerSpawn: Vector3;
+    /** All placed models in the scene. */
+    items: SceneItemSpec[];
+}
+/** Create a new scene item with sensible defaults. */
+declare function createDefaultSceneItem(name?: string, resourceKey?: string): SceneItemSpec;
+/** Create an empty scene. */
+declare function createDefaultScene(): SceneSpec;
+
+type StoreListener = (spec: SceneSpec) => void;
+interface SceneStoreOptions {
+    /**
+     * URL / public-folder path to a JSON file that seeds the store on {@link SceneStore.init}.
+     * Example: `'data/scene.json'`
+     */
+    filePath?: string;
+}
+/**
+ * Manages the current scene definition ({@link SceneSpec}).
+ *
+ * Follows the same patterns as `MaterialStore`:
+ * - Persists to `localStorage` on every change.
+ * - Call {@link init} once at startup to load from a JSON file.
+ * - Syncs back to the server via a PUT endpoint (Vite dev plugin).
+ */
+declare class SceneStore {
+    private scene;
+    private listeners;
+    private readonly filePath;
+    constructor(options?: SceneStoreOptions);
+    init(): Promise<void>;
+    get(): SceneSpec;
+    getItems(): SceneItemSpec[];
+    getItem(id: string): SceneItemSpec | undefined;
+    getPlayerSpawn(): [number, number, number];
+    setPlayerSpawn(x: number, y: number, z: number): void;
+    addItem(item: SceneItemSpec): void;
+    updateItem(item: SceneItemSpec): void;
+    deleteItem(id: string): void;
+    /** Replace the entire scene definition. */
+    setScene(spec: SceneSpec): void;
+    syncToServer(): Promise<boolean>;
+    private persist;
+    private loadFromStorage;
+    exportToFile(filename?: string): Promise<void>;
+    importFromFile(): Promise<void>;
+    subscribe(fn: StoreListener): () => void;
+    private emit;
+}
+
+interface EditorTab {
+    id: string;
+    /** Label shown on the tab button. */
+    label: string;
+    /** Called once to populate the tab's content container. */
+    buildContent: (container: HTMLElement) => void;
+    /** Called each time the tab becomes the active, visible tab. */
+    onActivate?: () => void;
+    /** Called each time the tab is hidden (tab switch or sidebar hide). */
+    onDeactivate?: () => void;
+    /** Optional cleanup called when the sidebar is unmounted. */
+    destroy?: () => void;
+}
+/**
+ * Fixed right-side editor sidebar.
+ *
+ * - Hosts a tab strip so new features can be added via {@link addTab}.
+ * - First tab is the Material Editor (colour preview swatches + full form).
+ * - Every store mutation auto-syncs to `materials.json` via the Vite dev plugin.
+ * - "🔄 Reload Game" triggers `location.reload()` to pick up JSON changes.
+ */
+declare class EditorSidebar {
+    private readonly store;
+    private root;
+    private tabBar;
+    private contentArea;
+    private tabs;
+    private activeTabId;
+    private listEl;
+    private formEl;
+    private selectedId;
+    private unsubMaterials?;
+    private _sidebarWidth;
+    private _dragging;
+    private _layoutMode;
+    private _layoutBtn;
+    private constructor();
+    static mount(store: MaterialStore): EditorSidebar;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    get isVisible(): boolean;
+    /** Register an extra tab. */
+    addTab(tab: EditorTab): void;
+    unmount(): void;
+    private build;
+    private toggleLayout;
+    private applyLayout;
+    private renderTabBar;
+    /** Activate a tab by id. Safe to call from outside (e.g. TopBar button). */
+    activateTab(id: string): void;
+    private buildMaterialsContent;
+    private refreshList;
+    private select;
+    private buildForm;
+    private onNew;
+    private onDuplicate;
+    private onDelete;
+    private mkBtn;
+}
+
+/** Entry from models.json */
+interface ModelRegistryEntry {
+    key: string;
+    name: string;
+    type: string;
+    path?: string;
+    description?: string;
+}
+interface SceneSectionOptions {
+    /** URL to the models registry JSON file. */
+    modelsFile?: string;
+    /** Returns the list of material names currently available. */
+    getMaterialNames?: () => string[];
+    /** Renderer reference — used to toggle hitbox debug visualisation. */
+    renderer?: {
+        debug: boolean;
+    };
+}
+/**
+ * Scene Editor — rendered as a tab inside the {@link EditorSidebar}.
+ *
+ * Lets the user:
+ *  – View / edit player spawn position.
+ *  – View / edit every scene item (translation, rotation, scale, bounds, collider).
+ *  – Add, duplicate, and delete items.
+ *  – Reload the game to apply changes.
+ */
+declare class SceneSection {
+    private readonly store;
+    private root;
+    private listEl;
+    private selectedId;
+    private formEl;
+    private unsub?;
+    private modelRegistry;
+    private readonly getMaterialNames;
+    private readonly modelsFile;
+    private readonly renderer;
+    private hitboxCheck;
+    private constructor();
+    static create(store: SceneStore, options?: SceneSectionOptions): SceneSection;
+    asTab(): EditorTab;
+    private onActivate;
+    private onDeactivate;
+    private buildContent;
+    private refreshList;
+    private refreshForm;
+    private buildSpawnForm;
+    private buildItemForm;
+    private onAdd;
+    private onDuplicate;
+    private onDelete;
+    private vec3Row;
+    private textRow;
+    private selectRow;
+    private checkRow;
+    private mkBtn;
+}
+
+/** Minimal sidebar interface used by TopBar for tab-aware buttons. */
+interface ISidebar {
+    show(): void;
+    toggle(): void;
+    activateTab(id: string): void;
+    readonly isVisible: boolean;
+}
+/**
+ * Slim top bar pinned at the top of the viewport.
+ * Houses engine tool buttons (e.g. Material Editor toggle).
+ */
+declare class TopBar {
+    private root;
+    private constructor();
+    static mount(materialPanel: ISidebar): TopBar;
+    unmount(): void;
+    private build;
+    /** Add the Models tab button after the game has started. */
+    addModelsButton(sidebar: ISidebar): void;
+    /** Add the Scene tab button after the game has started. */
+    addSceneButton(sidebar: ISidebar): void;
+    private mkToggleBtn;
+    private mkPanelToggleBtn;
+}
+
+/** Minimal interface: only the debug flag we need. */
+interface IRenderer {
+    debug: boolean;
+}
+/** Bounding box as stored on Model. */
+interface AABB {
+    min: [number, number, number];
+    max: [number, number, number];
+}
+/** Minimal model shape required by the inspector. */
+interface IModel {
+    translation: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+    boundingBox: AABB;
+}
+/** Minimal scene interface: just the keyed entry list. */
+interface IScene {
+    getEntries(): [string, IModel][];
+}
+/**
+ * Model Inspector — rendered as a tab inside the {@link EditorSidebar}.
+ *
+ * Lifecycle:
+ *  – `buildContent(container)` builds the DOM once when the tab is activated.
+ *  – `onActivate()` enables `renderer.debug` and starts a 200 ms refresh loop.
+ *  – `onDeactivate()` disables `renderer.debug` and stops the refresh loop.
+ *  – `asTab()` returns an {@link EditorTab} descriptor ready for `sidebar.addTab()`.
+ */
+declare class ModelsSection {
+    private readonly renderer;
+    private readonly scene;
+    private listEl;
+    private hitboxCheck;
+    private intervalId;
+    private constructor();
+    static create(renderer: IRenderer, scene: IScene): ModelsSection;
+    asTab(): EditorTab;
+    private start;
+    private stop;
+    private buildContent;
+    private refresh;
+}
+
+export { EditorSidebar, type EditorTab, type MaterialSpec, MaterialStore, type MaterialStoreOptions, type ModelRegistryEntry, ModelsSection, type SceneItemSpec, SceneSection, type SceneSectionOptions, type SceneSpec, SceneStore, type SceneStoreOptions, TopBar, createDefaultScene, createDefaultSceneItem, createDefaultSpec };