@connected-web/terrain-editor 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,409 @@
+import * as THREE from 'three';
+
+type HeightSampler = {
+    width: number;
+    height: number;
+    data: Float32Array;
+};
+declare function createHeightSampler(texture: THREE.Texture): HeightSampler | null;
+declare function sampleHeightValue(sampler: HeightSampler, u: number, v: number): number;
+declare function applyHeightField(geometry: THREE.PlaneGeometry, sampler: HeightSampler, options: {
+    seaLevel: number;
+    heightScale: number;
+}): {
+    minY: number;
+    maxY: number;
+};
+declare function buildRimMesh(geometry: THREE.PlaneGeometry, floorY: number, material?: THREE.Material): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material, THREE.Object3DEventMap>;
+
+type MarkerSpriteStateStyle = {
+    textColor: string;
+    backgroundColor: string;
+    borderColor: string;
+    borderThickness: number;
+    opacity: number;
+};
+type MarkerSpriteTheme = {
+    fontFamily: string;
+    fontWeight: string;
+    maxFontSize: number;
+    minFontSize: number;
+    paddingX: number;
+    paddingY: number;
+    borderRadius: number;
+    states: {
+        default: MarkerSpriteStateStyle;
+        hover?: Partial<MarkerSpriteStateStyle>;
+        focus?: Partial<MarkerSpriteStateStyle>;
+    };
+};
+type MarkerStemStateStyle = {
+    color: string;
+    opacity: number;
+};
+type MarkerStemGeometryShape = 'cylinder' | 'triangle' | 'square' | 'pentagon' | 'hexagon';
+type MarkerStemTheme = {
+    shape: MarkerStemGeometryShape;
+    radius: number;
+    scale?: number;
+    states: {
+        default: MarkerStemStateStyle;
+        hover?: Partial<MarkerStemStateStyle>;
+        focus?: Partial<MarkerStemStateStyle>;
+    };
+};
+type TerrainTheme = {
+    locationMarkers: {
+        sprite: MarkerSpriteTheme;
+        stem: MarkerStemTheme;
+    };
+};
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+type TerrainThemeOverrides = DeepPartial<TerrainTheme>;
+declare function getDefaultTerrainTheme(): TerrainTheme;
+declare function resolveTerrainTheme(...overrides: Array<TerrainTheme | TerrainThemeOverrides | undefined>): TerrainTheme;
+
+type LayerToggleState = {
+    biomes: Record<string, boolean>;
+    overlays: Record<string, boolean>;
+};
+type LocationViewState = {
+    distance: number;
+    polar: number;
+    azimuth: number;
+    targetPixel?: {
+        x: number;
+        y: number;
+    };
+};
+type TerrainLocation = {
+    id: string;
+    name?: string;
+    icon?: string;
+    showBorder?: boolean;
+    pixel: {
+        x: number;
+        y: number;
+    };
+    uv?: {
+        u: number;
+        v: number;
+    };
+    world?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    view?: LocationViewState;
+};
+type LocationPickPayload = {
+    pixel: {
+        x: number;
+        y: number;
+    };
+    uv: {
+        u: number;
+        v: number;
+    };
+    world: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+type ViewerLifecycleState = 'initializing' | 'loading-textures' | 'building-geometry' | 'first-render' | 'stabilizing' | 'ready';
+type TerrainInitOptions = {
+    onReady?: () => void;
+    onLifecycleChange?: (state: ViewerLifecycleState) => void;
+    heightScale?: number;
+    waterLevelPercent?: number;
+    layers?: LayerToggleState;
+    interactive?: boolean;
+    onLocationPick?: (payload: LocationPickPayload) => void;
+    onLocationHover?: (locationId: string | null) => void;
+    onLocationClick?: (locationId: string) => void;
+    locations?: TerrainLocation[];
+    theme?: TerrainThemeOverrides;
+    cameraView?: LocationViewState;
+};
+type TerrainHandle = {
+    destroy: () => void;
+    updateLayers: (state: LayerToggleState) => Promise<void>;
+    setInteractiveMode: (enabled: boolean) => void;
+    updateLocations: (locations: TerrainLocation[], focusedId?: string) => void;
+    setFocusedLocation: (locationId?: string | null) => void;
+    navigateTo: (payload: {
+        pixel: {
+            x: number;
+            y: number;
+        };
+        locationId?: string;
+        world?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        view?: LocationViewState;
+        instant?: boolean;
+    }) => void;
+    setHoveredLocation: (id: string | null) => void;
+    setCameraOffset: (offset: number, focusId?: string) => void;
+    onCameraMove: (callback: (newState: LocationViewState) => void) => void;
+    getViewState: () => LocationViewState;
+    setTheme: (overrides?: TerrainThemeOverrides) => void;
+    setSeaLevel: (level: number) => void;
+    invalidateIconTextures: (paths?: string[]) => void;
+    invalidateLayerMasks: (paths?: string[]) => void;
+    enableFrameCaptureMode: (fps?: number) => {
+        fps: number;
+    };
+    disableFrameCaptureMode: () => void;
+    captureFrame: (frameNumber: number, fps?: number) => {
+        frameNumber: number;
+        time: number;
+    };
+};
+type Cleanup = () => void;
+type Resolvable<T> = T | Promise<T>;
+type LegendLayer = {
+    mask: string;
+    rgb: [number, number, number];
+    label?: string;
+};
+type TerrainLegend = {
+    size: [number, number];
+    sea_level?: number;
+    heightmap: string;
+    topology?: string;
+    biomes: Record<string, LegendLayer>;
+    overlays: Record<string, LegendLayer>;
+};
+type TerrainDataset = {
+    legend: TerrainLegend;
+    getHeightMapUrl: () => Resolvable<string>;
+    getTopologyMapUrl: () => Resolvable<string>;
+    resolveAssetUrl: (path: string) => Resolvable<string>;
+    cleanup?: () => void;
+    theme?: TerrainThemeOverrides;
+};
+declare function initTerrainViewer(container: HTMLElement, dataset: TerrainDataset, options?: TerrainInitOptions): Promise<TerrainHandle>;
+
+type TerrainProjectFileEntry = {
+    path: string;
+    data: ArrayBuffer;
+    type?: string;
+    lastModified?: number;
+    sourceFileName?: string;
+};
+type TerrainProjectMetadata = {
+    label?: string;
+    author?: string;
+    source?: 'archive' | 'scratch';
+};
+type TerrainProjectSnapshot = {
+    legend?: TerrainLegend;
+    locations?: TerrainLocation[];
+    theme?: TerrainThemeOverrides;
+    metadata: TerrainProjectMetadata;
+    files: TerrainProjectFileEntry[];
+    dirty: boolean;
+};
+type TerrainProjectStore = {
+    getSnapshot: () => TerrainProjectSnapshot;
+    subscribe: (listener: (snapshot: TerrainProjectSnapshot) => void) => () => void;
+    loadFromArchive: (payload: {
+        legend: TerrainLegend;
+        locations?: TerrainLocation[];
+        theme?: TerrainThemeOverrides;
+        files?: TerrainProjectFileEntry[];
+        metadata?: TerrainProjectMetadata;
+    }) => void;
+    setLegend: (legend: TerrainLegend) => void;
+    setLocations: (locations?: TerrainLocation[]) => void;
+    setTheme: (theme?: TerrainThemeOverrides) => void;
+    updateMetadata: (metadata: Partial<TerrainProjectMetadata>) => void;
+    upsertFile: (entry: TerrainProjectFileEntry) => void;
+    removeFile: (path: string) => void;
+    reset: () => void;
+    markPersisted: () => void;
+};
+declare function createProjectStore(initial?: Partial<TerrainProjectSnapshot>): TerrainProjectStore;
+
+type WynArchiveProgressEvent = {
+    type: 'network-download';
+    loadedBytes: number;
+    totalBytes?: number;
+} | {
+    type: 'file-read';
+    loadedBytes: number;
+    totalBytes?: number;
+};
+type LoadWynArchiveOptions = {
+    onProgress?: (event: WynArchiveProgressEvent) => void;
+    includeFiles?: boolean;
+};
+type LoadedWynFile = {
+    dataset: TerrainDataset;
+    legend: TerrainLegend;
+    locations?: TerrainLocation[];
+    files?: TerrainProjectFileEntry[];
+    metadata?: TerrainProjectMetadata;
+};
+declare function loadWynArchive(url: string, options?: LoadWynArchiveOptions): Promise<LoadedWynFile>;
+declare function loadWynArchiveFromArrayBuffer(data: ArrayBuffer, options?: LoadWynArchiveOptions): Promise<LoadedWynFile>;
+declare function loadWynArchiveFromFile(file: File, options?: LoadWynArchiveOptions): Promise<LoadedWynFile>;
+
+type TerrainViewMode = 'embed' | 'popout' | 'fullscreen';
+type TerrainViewerHostOptions = {
+    viewerElement: HTMLElement;
+    embedTarget: HTMLElement;
+    title?: string;
+    subtitle?: string;
+    documentRoot?: Document;
+    onModeChange?: (mode: TerrainViewMode) => void;
+};
+type TerrainViewerHostHandle = {
+    openPopout: () => void;
+    closePopout: () => void;
+    toggleFullscreen: () => Promise<void>;
+    getMode: () => TerrainViewMode;
+    destroy: () => void;
+};
+declare function createTerrainViewerHost(options: TerrainViewerHostOptions): TerrainViewerHostHandle;
+
+type ViewerOverlayButtonLocation = 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center' | 'center';
+type ViewerOverlayCustomButton = {
+    location: ViewerOverlayButtonLocation;
+    label: string;
+    description?: string;
+    callback?: () => void;
+};
+type ViewerOverlayStatusOptions = {
+    initialText: string;
+};
+type ViewerOverlaySelectFileOptions = {
+    enabled: boolean;
+    label: string;
+    callback?: (file: File) => void;
+};
+type ViewerOverlayPopoutOptions = {
+    enabled: boolean;
+    labelOpen: string;
+    labelClose: string;
+    onRequestOpen?: () => void;
+    onRequestClose?: () => void;
+};
+type ViewerOverlayFullscreenOptions = {
+    enabled: boolean;
+    labelEnter: string;
+    labelExit: string;
+    onToggle?: () => void;
+    displayInEmbed: boolean;
+};
+type ViewerOverlayOptions = {
+    status?: Partial<ViewerOverlayStatusOptions>;
+    selectFile?: Partial<Omit<ViewerOverlaySelectFileOptions, 'enabled' | 'label'>> & {
+        enabled?: boolean;
+        label?: string;
+    };
+    popout?: Partial<Omit<ViewerOverlayPopoutOptions, 'enabled' | 'labelOpen' | 'labelClose'>> & {
+        enabled?: boolean;
+        labelOpen?: string;
+        labelClose?: string;
+    };
+    fullscreen?: Partial<Omit<ViewerOverlayFullscreenOptions, 'enabled' | 'labelEnter' | 'labelExit' | 'displayInEmbed'>> & {
+        enabled?: boolean;
+        labelEnter?: string;
+        labelExit?: string;
+        displayInEmbed?: boolean;
+    };
+    customButtons?: ViewerOverlayCustomButton[];
+};
+type ViewerOverlayLoadingState = {
+    label: string;
+    loadedBytes: number;
+    totalBytes?: number;
+};
+type ViewerOverlayHandle = {
+    setStatus: (message: string) => void;
+    setStatusFade: (fade: boolean) => void;
+    setViewMode: (mode: TerrainViewMode) => void;
+    setLoadingProgress: (state: ViewerOverlayLoadingState | null) => void;
+    hideDropOverlay: () => void;
+    openFileDialog?: () => void;
+    destroy: () => void;
+};
+declare function createViewerOverlay(target: HTMLElement, optionsInput?: ViewerOverlayOptions): ViewerOverlayHandle;
+
+type BuildWynArchiveOptions = {
+    pretty?: boolean;
+};
+declare function buildWynArchive(project: TerrainProjectSnapshot, options?: BuildWynArchiveOptions): Promise<Blob>;
+
+type LayerBrowserEntry = {
+    id: string;
+    kind: 'biome' | 'overlay';
+    label: string;
+    mask: string;
+    color: [number, number, number];
+    visible: boolean;
+};
+type LayerBrowserState = {
+    legend?: TerrainLegend;
+    entries: LayerBrowserEntry[];
+};
+type LayerBrowserStore = {
+    getState: () => LayerBrowserState;
+    subscribe: (listener: (state: LayerBrowserState) => void) => () => void;
+    setLegend: (legend?: TerrainLegend) => void;
+    setVisibility: (id: string, visible: boolean) => void;
+    toggleVisibility: (id: string) => void;
+    setAll: (kind: 'biome' | 'overlay', visible: boolean) => void;
+    getLayerToggles: () => LayerToggleState;
+};
+declare function createLayerBrowserStore(legend?: TerrainLegend, initial?: Partial<LayerToggleState>): LayerBrowserStore;
+
+type MaskStrokeMode = 'paint' | 'erase';
+type MaskStrokePoint = {
+    x: number;
+    y: number;
+};
+type MaskStroke = {
+    points: MaskStrokePoint[];
+    radius: number;
+    strength?: number;
+    mode?: MaskStrokeMode;
+};
+type MaskImage = {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+type MaskEditorState = {
+    width: number;
+    height: number;
+    dirty: boolean;
+    undoCount: number;
+    redoCount: number;
+};
+type MaskEditorHandle = {
+    getState: () => MaskEditorState;
+    subscribe: (listener: (state: MaskEditorState) => void) => () => void;
+    applyStroke: (stroke: MaskStroke) => void;
+    clear: () => void;
+    undo: () => void;
+    redo: () => void;
+    exportMask: () => MaskImage;
+    loadMask: (mask: MaskImage) => void;
+    markClean: () => void;
+};
+type MaskEditorOptions = {
+    width: number;
+    height: number;
+    initialMask?: MaskImage;
+};
+declare function createMaskEditor(options: MaskEditorOptions): MaskEditorHandle;
+
+export { type BuildWynArchiveOptions, type Cleanup, type DeepPartial, type HeightSampler, type LayerBrowserEntry, type LayerBrowserState, type LayerBrowserStore, type LayerToggleState, type LegendLayer, type LoadWynArchiveOptions, type LoadedWynFile, type LocationPickPayload, type LocationViewState, type MarkerSpriteStateStyle, type MarkerSpriteTheme, type MarkerStemGeometryShape, type MarkerStemStateStyle, type MarkerStemTheme, type MaskEditorHandle, type MaskEditorState, type MaskImage, type MaskStroke, type MaskStrokeMode, type MaskStrokePoint, type TerrainDataset, type TerrainHandle, type TerrainLegend, type TerrainLocation, type TerrainProjectFileEntry, type TerrainProjectMetadata, type TerrainProjectSnapshot, type TerrainProjectStore, type TerrainTheme, type TerrainThemeOverrides, type TerrainViewMode, type TerrainViewerHostHandle, type TerrainViewerHostOptions, type ViewerLifecycleState, type ViewerOverlayCustomButton, type ViewerOverlayHandle, type ViewerOverlayLoadingState, type ViewerOverlayOptions, type WynArchiveProgressEvent, applyHeightField, buildRimMesh, buildWynArchive, createHeightSampler, createLayerBrowserStore, createMaskEditor, createProjectStore, createTerrainViewerHost, createViewerOverlay, getDefaultTerrainTheme, initTerrainViewer, loadWynArchive, loadWynArchiveFromArrayBuffer, loadWynArchiveFromFile, resolveTerrainTheme, sampleHeightValue };