@benjos/create-boilerplate 1.5.1 → 1.5.6

package/template-vue/src/experiences/engines/threes/app/bases/ThreeAppBase.ts

@@ -0,0 +1,128 @@
+import { DomResizeManager, TickerManager } from '@benjos/cookware';
+import { Scene } from 'three';
+import ThreeCameraControllerBase from '../../../../cameras/threes/bases/ThreeCameraControllerBase';
+import { ViewId } from '../../../../constants/experiences/ViewId';
+import LoaderManager from '../../../../managers/LoaderManager';
+import WebGLRendererBase from '../../../../renderers/threes/bases/WebGLRendererBase';
+import ThreeViewBase from '../../../../views/threes/bases/ThreeViewBase';
+
+export default abstract class ThreeAppBase {
+    declare protected _domElementContainer: HTMLElement;
+    declare protected _scene: Scene;
+    declare protected _cameraController: ThreeCameraControllerBase;
+    declare protected _renderer: WebGLRendererBase;
+    protected readonly _views: ThreeViewBase[];
+    protected readonly _viewBuilder: Map<ViewId, new () => ThreeViewBase>;
+    declare protected _currentView: ThreeViewBase;
+
+    constructor() {
+        this._views = [];
+        this._viewBuilder = new Map();
+    }
+
+    public init(): void {
+        TickerManager.add(this._update);
+
+        this._setDomElementContainer();
+        this._generateScenes();
+        this._generateCameras();
+        this._generateRenderers();
+        this._declareViews();
+
+        this._onResize();
+        DomResizeManager.onResize.add(this._onResize);
+    }
+
+    protected _setDomElementContainer(): void {
+        //
+    }
+
+    protected _generateScenes(): void {
+        //
+    }
+
+    protected _generateCameras(): void {
+        //
+    }
+
+    protected _generateRenderers(): void {
+        //
+    }
+
+    protected _declareViews(): void {
+        //
+    }
+
+    protected _generateView(viewId: ViewId): ThreeViewBase {
+        const ViewConstructor = this._viewBuilder.get(viewId);
+        if (!ViewConstructor) {
+            throw new Error(`View constructor for ID '${viewId}' not found.`);
+        }
+        const view = new ViewConstructor();
+        this._views.push(view);
+        return view;
+    }
+
+    public async setCurrentView(viewId: ViewId): Promise<void> {
+        if (this._currentView?.viewId === viewId) return;
+
+        let view = this._getViewById(viewId);
+        if (!view) view = this._generateView(viewId);
+
+        view.declareAssets();
+
+        await LoaderManager.loadAssetsWithTransition(this._swapView.bind(this, view));
+    }
+
+    private readonly _swapView = (view: ThreeViewBase): void => {
+        if (this._currentView) this._removeOldView(this._currentView);
+        this._currentView = view;
+        view.init();
+        this.scene.add(this._currentView);
+    }
+
+    private _getViewById(viewId: ViewId): ThreeViewBase | null {
+        let view;
+        for (const v of this._views) {
+            if (v.viewId === viewId) view = v;
+        }
+        return view || null;
+    }
+
+    private _removeOldView(view: ThreeViewBase): void {
+        this.scene.remove(view);
+        view.dispose();
+        view.reset();
+    }
+
+    protected _onResize = (): void => {
+        this._renderer.domElement.width = window.innerWidth;
+        this._renderer.domElement.height = window.innerHeight;
+
+        this._cameraController.resize();
+        this._renderer.resize();
+    };
+
+    private _update = (dt: number): void => {
+        this._cameraController.update(dt);
+        this._currentView?.update(dt);
+        this._renderer.update(dt);
+    };
+
+    //#region Getters
+    //
+    public get domElementContainer(): HTMLElement {
+        return this._domElementContainer;
+    }
+    public get scene(): Scene {
+        return this._scene;
+    }
+    public get renderer(): WebGLRendererBase {
+        return this._renderer;
+    }
+    public get cameraController(): ThreeCameraControllerBase {
+        return this._cameraController;
+    }
+    //
+    //#endregion
+}

package/template-vue/src/experiences/engines/vues/MainVue.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import LoaderView from '../../views/vues/LoaderView.vue';
+</script>
+
+<template>
+    <div id="loader">
+        <LoaderView />
+    </div>
+</template>

package/template-vue/src/experiences/managers/DebugManager.ts

@@ -0,0 +1,87 @@
+import { DomKeyboardManager } from '@benjos/cookware';
+import { KeyboardConstant } from '@benjos/spices';
+import GUI from 'lil-gui';
+import { ThreePerf } from 'three-perf';
+import { DebugGuiTitle } from '../constants/experiences/DebugGuiTitle';
+import MainThreeApp from '../engines/threes/app/MainThreeApp';
+
+class DebugManager {
+    private static readonly _IS_ACTIVE_STRING: string = '#debug';
+    private static readonly _GUI_WIDTH: number = 300;
+    private static readonly _GUI_TITLE: string = 'Debug Panel';
+    private static readonly _THREE_PERF_ANCHOR_X: 'left' | 'right' = 'left';
+    private static readonly _THREE_PERF_ANCHOR_Y: 'top' | 'bottom' = 'bottom';
+    private static readonly _TOGGLE_HIDDEN_KEYS: string[] = [
+        KeyboardConstant.CODES.SHIFT_LEFT,
+        KeyboardConstant.CODES.KEY_H,
+    ];
+
+    declare private _gui: GUI;
+    declare private _threePerf: ThreePerf;
+
+    public init(): void {
+        if (this.isActive) {
+            this._initGui();
+        }
+    }
+
+    private _initGui(): void {
+        this._gui = new GUI({
+            width: DebugManager._GUI_WIDTH,
+            title: DebugManager._GUI_TITLE,
+            closeFolders: true,
+        });
+        this._gui.close();
+        DomKeyboardManager.onKeyDown.remove(this._onKeyDown);
+        DomKeyboardManager.onKeyDown.add(this._onKeyDown);
+    }
+
+    private _initThreePerf = (): void => {
+        this._threePerf = new ThreePerf({
+            anchorX: DebugManager._THREE_PERF_ANCHOR_X,
+            anchorY: DebugManager._THREE_PERF_ANCHOR_Y,
+            domElement: document.body,
+            renderer: MainThreeApp.renderer,
+            showGraph: false,
+        });
+    };
+
+    private _addGuiFolder(title: DebugGuiTitle): GUI {
+        return this._gui.addFolder(title);
+    }
+
+    public getGuiFolder(title: DebugGuiTitle): GUI {
+        let gui = this._gui.folders.find(gui => gui._title === title);
+        if (!gui) gui = this._addGuiFolder(title);
+        return gui;
+    }
+
+    public beginThreePerf(): void {
+        if (!this._threePerf) this._initThreePerf();
+        this._threePerf.begin();
+    }
+
+    public endThreePerf(): void {
+        this._threePerf.end();
+    }
+
+    private readonly _onKeyDown = (_e: KeyboardEvent): void => {
+        if (DomKeyboardManager.areAllKeysDown(DebugManager._TOGGLE_HIDDEN_KEYS)) {
+            this._gui.show(this._gui._hidden);
+            this._threePerf.visible = !this._threePerf.visible;
+        }
+    };
+
+    //#region Getters
+    //
+    public get isActive(): boolean {
+        return window.location.hash === DebugManager._IS_ACTIVE_STRING;
+    }
+    public get gui(): GUI {
+        return this._gui;
+    }
+    //
+    //#endregion
+}
+
+export default new DebugManager();

package/template-vue/src/experiences/managers/LoaderManager.ts

@@ -0,0 +1,176 @@
+import { Action, TickerManager } from '@benjos/cookware';
+import ThreeAssetsManager from './threes/ThreeAssetsManager';
+
+class LoaderManager {
+    private static readonly _MIN_LOAD_DURATION: number = 0.5;
+
+    private _totalSize = 0;
+    private _loadedSize = 0;
+    private _progress = 0;
+    private _isTransitioning = false;
+    private _elapsed = 0;
+    private _hasAssetsToLoad = false;
+    private _assetsFinished = false;
+    private _transitionResolves: (() => void)[] = [];
+    private _showTransition: (() => Promise<void>) | null = null;
+    private _hideTransition: (() => Promise<void>) | null = null;
+
+    public readonly onBeginLoad = new Action();
+    public readonly onProgress = new Action();
+    public readonly onFinishLoad = new Action();
+    public readonly onShow = new Action();
+    public readonly onHide = new Action();
+
+    public init(): void {
+        this._addCallbacks();
+    }
+
+    public setShowTransition(callback: () => Promise<void>): void {
+        this._showTransition = callback;
+    }
+
+    public setHideTransition(callback: () => Promise<void>): void {
+        this._hideTransition = callback;
+    }
+
+    private _addCallbacks(): void {
+        this._removeCallbacks();
+        ThreeAssetsManager.onLoad.add(this._onLoad);
+        ThreeAssetsManager.onProgress.add(this._onAssetProgress);
+    }
+
+    private _removeCallbacks(): void {
+        ThreeAssetsManager.onLoad.remove(this._onLoad);
+        ThreeAssetsManager.onProgress.remove(this._onAssetProgress);
+    }
+
+    private _beginLoad = (): void => {
+        ThreeAssetsManager.beginLoad();
+        this.onBeginLoad.execute();
+    };
+
+    private _finishLoad = (): void => {
+        ThreeAssetsManager.finishLoad();
+        this.onFinishLoad.execute();
+    };
+
+    private async _showLoader(): Promise<void> {
+        this.onShow.execute();
+        if (this._showTransition) await this._showTransition();
+    }
+
+    private async _hideLoader(): Promise<void> {
+        this.onHide.execute();
+        if (this._hideTransition) await this._hideTransition();
+    }
+
+    private readonly _onAssetsFinish = (): void => {
+        this._assetsFinished = true;
+        this.onFinishLoad.remove(this._onAssetsFinish);
+    };
+
+    private readonly _onTransitionTick = (dt: number): void => {
+        this._elapsed += dt;
+        const timerProgress = Math.min(this._elapsed / LoaderManager._MIN_LOAD_DURATION, 1);
+
+        let assetProgress = 1;
+        if (this._hasAssetsToLoad && !this._assetsFinished) {
+            assetProgress = this._totalSize > 0 ? Math.min(this._loadedSize / this._totalSize, 1) : 0;
+        }
+
+        this._progress = Math.min(timerProgress, assetProgress);
+        this.onProgress.execute();
+
+        if (timerProgress >= 1 && this._assetsFinished) {
+            this._progress = 1;
+            this.onProgress.execute();
+            TickerManager.remove(this._onTransitionTick);
+            this._transitionResolves.forEach((resolve) => resolve());
+            this._transitionResolves.length = 0;
+        }
+    };
+
+    public async loadAssetsWithTransition(onReady?: () => void | Promise<void>): Promise<void> {
+        const isNested = this._isTransitioning;
+        if (!isNested) {
+            this._isTransitioning = true;
+            await this._showLoader();
+        }
+
+        this._hasAssetsToLoad = !this._checkIsFinished();
+
+        if (this._hasAssetsToLoad || !isNested) {
+            this._progress = 0;
+            this._elapsed = 0;
+            this._assetsFinished = !this._hasAssetsToLoad;
+            this.onProgress.execute();
+
+            if (this._hasAssetsToLoad) {
+                this.onFinishLoad.add(this._onAssetsFinish);
+                this._beginLoad();
+            }
+
+            await new Promise<void>((resolve) => {
+                this._transitionResolves.push(resolve);
+                TickerManager.add(this._onTransitionTick);
+            });
+        }
+
+        if (onReady) await onReady();
+
+        if (!isNested) {
+            this._isTransitioning = false;
+            await this._hideLoader();
+        }
+    }
+
+    private _onLoad = (): void => {
+        this._refreshSizes();
+        if (this._checkIsFinished()) this._finishLoad();
+    };
+
+    private _checkIsFinished = (): boolean => {
+        if (!ThreeAssetsManager.isLoaded) return false;
+        return true;
+    };
+
+    private _onAssetProgress = (): void => {
+        this._refreshSizes();
+        this._progress = this._totalSize > 0 ? Math.min(this._loadedSize / this._totalSize, 1) : 0;
+        this.onProgress.execute();
+    };
+
+    private _refreshSizes = (): void => {
+        this._refreshTotalSize();
+        this._refreshLoadedSize();
+    };
+
+    private _refreshTotalSize = (): void => {
+        this._totalSize = 0;
+        this._totalSize += ThreeAssetsManager.totalSize;
+    };
+
+    private _refreshLoadedSize = (): void => {
+        this._loadedSize = 0;
+        this._loadedSize += ThreeAssetsManager.loadedSize;
+    };
+
+    //#region Getters
+    //
+    public get isLoaded(): boolean {
+        return this._checkIsFinished();
+    }
+    public get progress(): number {
+        return this._progress;
+    }
+    public get totalSize(): number {
+        return this._totalSize;
+    }
+    public get loadedSize(): number {
+        return this._loadedSize;
+    }
+    //
+    //#endregion
+}
+
+export default new LoaderManager();

package/template-vue/src/experiences/managers/threes/ThreeAssetsManager.ts

@@ -0,0 +1,263 @@
+import { Action, AssetUtils } from '@benjos/cookware';
+import {
+    DataTexture,
+    EquirectangularRefractionMapping,
+    LinearSRGBColorSpace,
+    RepeatWrapping,
+    Texture,
+    TextureLoader,
+    type ColorSpace,
+    type Mapping,
+    type Wrapping,
+} from 'three';
+import { DRACOLoader, Font, FontLoader, GLTFLoader, HDRLoader, type GLTF } from 'three/examples/jsm/Addons.js';
+import type { AssetId } from '../../constants/experiences/AssetId';
+import { AssetType } from '../../types/assetTypes';
+
+export interface ThreeAssetToLoad {
+    id: AssetId;
+    type: AssetType;
+    path: string;
+    option?: ThreeAssetOption;
+    loadedSize: number;
+    totalSize: number;
+}
+
+export interface ThreeAssetOption {}
+
+export interface ThreeTextureOption extends ThreeAssetOption {
+    colorSpace?: ColorSpace;
+    wrapping?: Wrapping;
+    repeatX?: number;
+    repeatY?: number;
+    centerX?: number;
+    centerY?: number;
+}
+
+export interface ThreeHDROption extends ThreeAssetOption {
+    mapping?: Mapping;
+    colorSpace?: ColorSpace;
+}
+
+export interface ThreeModelOption extends ThreeAssetOption {}
+
+export interface ThreeFontOption extends ThreeAssetOption {}
+
+class ThreeAssetsManager {
+    private static readonly _DRACO_LOADER_PATH: string = 'loaders/draco/';
+    private static readonly _DEFAULT_TEXTURE_OPTION_COLOR_SPACE: ColorSpace = LinearSRGBColorSpace;
+    private static readonly _DEFAULT_TEXTURE_OPTION_WRAPPING: Wrapping = RepeatWrapping;
+    private static readonly _DEFAULT_TEXTURE_OPTION_REPEAT_X: number = 1;
+    private static readonly _DEFAULT_TEXTURE_OPTION_REPEAT_Y: number = 1;
+    private static readonly _DEFAULT_TEXTURE_OPTION_CENTER_X: number = 0.5;
+    private static readonly _DEFAULT_TEXTURE_OPTION_CENTER_Y: number = 0.5;
+    private static readonly _DEFAULT_HDR_MAPPING: Mapping = EquirectangularRefractionMapping;
+    private static readonly _DEFAULT_HDR_COLOR_SPACE: ColorSpace = LinearSRGBColorSpace;
+    private static readonly _DEFAULT_LOADED_SIZE: number = 0;
+    private static readonly _DEFAULT_TOTAL_SIZE: number = -1;
+    private static readonly _DEFAULT_TEXTURE_TOTAL_SIZE: number = 1;
+
+    private readonly _assets: Map<string, Texture | DataTexture | GLTF | Font> = new Map<
+        string,
+        Texture | GLTF | Font
+    >();
+    private readonly _toLoadList: ThreeAssetToLoad[] = [];
+    private _expectedAssetsCount = 0;
+
+    private readonly _textureLoader = new TextureLoader();
+    private readonly _hdrLoader = new HDRLoader();
+    private readonly _gltfLoader = new GLTFLoader();
+    private readonly _dracoLoader = new DRACOLoader();
+    private readonly _fontLoader = new FontLoader();
+
+    public readonly onLoad = new Action();
+    public readonly onProgress = new Action();
+
+    public init(): void {
+        this._dracoLoader.setDecoderPath(AssetUtils.GetPath(ThreeAssetsManager._DRACO_LOADER_PATH));
+        this._gltfLoader.setDRACOLoader(this._dracoLoader);
+    }
+
+    public addTexture(id: AssetId, path: string, textureOption?: ThreeTextureOption): void {
+        this._toLoadList.push({
+            id,
+            type: AssetType.TEXTURE,
+            path,
+            option: textureOption,
+            loadedSize: ThreeAssetsManager._DEFAULT_LOADED_SIZE,
+            totalSize: ThreeAssetsManager._DEFAULT_TEXTURE_TOTAL_SIZE,
+        });
+        this._expectedAssetsCount++;
+    }
+
+    public addHDR(id: AssetId, path: string, hdrOption?: ThreeHDROption): void {
+        this._toLoadList.push({
+            id,
+            type: AssetType.HDR,
+            path,
+            option: hdrOption,
+            loadedSize: ThreeAssetsManager._DEFAULT_LOADED_SIZE,
+            totalSize: ThreeAssetsManager._DEFAULT_TOTAL_SIZE,
+        });
+        this._expectedAssetsCount++;
+    }
+
+    public addModel(id: AssetId, path: string, modelOption?: ThreeModelOption): void {
+        this._toLoadList.push({
+            id,
+            type: AssetType.MODEL,
+            path,
+            option: modelOption,
+            loadedSize: ThreeAssetsManager._DEFAULT_LOADED_SIZE,
+            totalSize: ThreeAssetsManager._DEFAULT_TOTAL_SIZE,
+        });
+        this._expectedAssetsCount++;
+    }
+
+    public addFont(id: AssetId, path: string, fontOption?: ThreeFontOption): void {
+        this._toLoadList.push({
+            id,
+            type: AssetType.FONT,
+            path,
+            option: fontOption,
+            loadedSize: ThreeAssetsManager._DEFAULT_LOADED_SIZE,
+            totalSize: ThreeAssetsManager._DEFAULT_TOTAL_SIZE,
+        });
+        this._expectedAssetsCount++;
+    }
+
+    public beginLoad(): void {
+        if (this._toLoadList.length === 0) {
+            this.onLoad.execute();
+            return;
+        }
+        for (const asset of this._toLoadList) {
+            if (asset.type === AssetType.TEXTURE) this._loadTexture(asset);
+            else if (asset.type === AssetType.HDR) this._loadHDR(asset);
+            else if (asset.type === AssetType.MODEL) this._loadModel(asset);
+            else if (asset.type === AssetType.FONT) this._loadFont(asset);
+        }
+    }
+
+    public finishLoad(): void {
+        this._toLoadList.length = 0;
+    }
+
+    private _loadTexture(asset: ThreeAssetToLoad): void {
+        const option = asset.option as ThreeTextureOption | undefined;
+        this._textureLoader.load(
+            asset.path,
+            (texture) => {
+                texture.colorSpace = option?.colorSpace ?? ThreeAssetsManager._DEFAULT_TEXTURE_OPTION_COLOR_SPACE;
+                texture.wrapS = texture.wrapT = option?.wrapping ?? ThreeAssetsManager._DEFAULT_TEXTURE_OPTION_WRAPPING;
+                texture.repeat.set(
+                    option?.repeatX ?? ThreeAssetsManager._DEFAULT_TEXTURE_OPTION_REPEAT_X,
+                    option?.repeatY ?? ThreeAssetsManager._DEFAULT_TEXTURE_OPTION_REPEAT_Y
+                );
+                texture.center.set(
+                    option?.centerX ?? ThreeAssetsManager._DEFAULT_TEXTURE_OPTION_CENTER_X,
+                    option?.centerY ?? ThreeAssetsManager._DEFAULT_TEXTURE_OPTION_CENTER_Y
+                );
+                asset.loadedSize = asset.totalSize;
+                this._onLoad(asset.id, texture);
+            },
+            (event: ProgressEvent) => this._onProgress(asset, event),
+            () => this._onError(AssetType.TEXTURE, asset.id, asset.path)
+        );
+    }
+
+    private _loadHDR(asset: ThreeAssetToLoad): void {
+        const option = asset.option as ThreeHDROption | undefined;
+        this._hdrLoader.load(
+            asset.path,
+            (dataTexture) => {
+                dataTexture.mapping = option?.mapping ?? ThreeAssetsManager._DEFAULT_HDR_MAPPING;
+                dataTexture.colorSpace = option?.colorSpace ?? ThreeAssetsManager._DEFAULT_HDR_COLOR_SPACE;
+                this._onLoad(asset.id, dataTexture);
+            },
+            (event: ProgressEvent) => this._onProgress(asset, event),
+            () => this._onError(AssetType.HDR, asset.id, asset.path)
+        );
+    }
+
+    private _loadModel(asset: ThreeAssetToLoad): void {
+        this._gltfLoader.load(
+            asset.path,
+            (model) => this._onLoad(asset.id, model),
+            (event: ProgressEvent) => this._onProgress(asset, event),
+            () => this._onError(AssetType.MODEL, asset.id, asset.path)
+        );
+    }
+
+    private _loadFont(asset: ThreeAssetToLoad): void {
+        this._fontLoader.load(
+            asset.path,
+            (font) => this._onLoad(asset.id, font),
+            (event: ProgressEvent) => this._onProgress(asset, event),
+            () => this._onError(AssetType.FONT, asset.id, asset.path)
+        );
+    }
+
+    private _onLoad(id: AssetId, asset: Texture | GLTF | Font): void {
+        this._assets.set(id, asset);
+        this.onLoad.execute();
+    }
+
+    private _onProgress(asset: ThreeAssetToLoad, event: ProgressEvent): void {
+        if (asset.totalSize === ThreeAssetsManager._DEFAULT_TOTAL_SIZE) asset.totalSize = event.total;
+        asset.loadedSize = event.loaded;
+        this.onProgress.execute();
+    }
+
+    private _onError(type: AssetType, id: AssetId, path: string): void {
+        throw new Error(`ThreeAssetsManager: Failed to load ${type} with id '${id}' from path '${path}'`);
+    }
+
+    public getTexture(id: AssetId): Texture {
+        const asset = this._assets.get(id);
+        if (!asset) throw new Error(`Texture with id '${id}' not found!`);
+        return asset as Texture;
+    }
+
+    public getHDR(id: AssetId): DataTexture {
+        const asset = this._assets.get(id);
+        if (!asset) throw new Error(`HDR with id '${id}' not found!`);
+        return asset as DataTexture;
+    }
+
+    public getModel(id: AssetId): GLTF {
+        const asset = this._assets.get(id);
+        if (!asset) throw new Error(`Model with id '${id}' not found!`);
+        return asset as GLTF;
+    }
+
+    public getFont(id: AssetId): Font {
+        const asset = this._assets.get(id);
+        if (!asset) throw new Error(`Font with id '${id}' not found!`);
+        return asset as Font;
+    }
+
+    //#region Getters
+    //
+    public get isLoaded(): boolean {
+        return this._assets.size === this._expectedAssetsCount;
+    }
+    public get totalSize(): number {
+        let totalSize = 0;
+        for (const asset of this._toLoadList) {
+            totalSize += asset.totalSize;
+        }
+        return totalSize;
+    }
+    public get loadedSize(): number {
+        let loadedSize = 0;
+        for (const asset of this._toLoadList) {
+            loadedSize += asset.loadedSize;
+        }
+        return loadedSize;
+    }
+    //
+    //#endregion
+}
+
+export default new ThreeAssetsManager();