@benjos/create-boilerplate 1.5.1 → 1.5.6

package/template-vue/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "template-vue",
+    "private": true,
+    "version": "1.5.6",
+    "type": "module",
+    "scripts": {
+        "dev": "vite",
+        "build": "vue-tsc -b && vite build",
+        "preview": "vite preview",
+        "lint": "eslint . --max-warnings 0",
+        "lint:fix": "eslint . --fix",
+        "format": "prettier --write .",
+        "format:check": "prettier --check ."
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/howler": "^2.2.12",
+        "@types/three": "^0.183.1",
+        "@vitejs/plugin-vue": "^6.0.5",
+        "@vue/tsconfig": "^0.9.0",
+        "eslint": "^10.1.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-prettier": "^5.5.5",
+        "prettier": "^3.8.1",
+        "sass-embedded": "^1.98.0",
+        "three-perf": "^1.0.11",
+        "typescript": "~5.9.3",
+        "typescript-eslint": "^8.57.1",
+        "vite": "^8.0.1",
+        "vite-plugin-glsl": "^1.5.6",
+        "vue-tsc": "^3.2.6"
+    },
+    "dependencies": {
+        "@benjos/cookware": "^1.0.4",
+        "@benjos/spices": "^1.0.1",
+        "@dimforge/rapier3d": "^0.19.3",
+        "gsap": "^3.14.2",
+        "howler": "^2.2.4",
+        "lil-gui": "^0.21.0",
+        "three": "^0.183.2",
+        "vue": "^3.5.30"
+    }
+}

package/template-vue/readme.md

@@ -0,0 +1,34 @@
+# 🎨 Three.js Vue Boilerplate
+
+Three.js + Vue + Vite + TypeScript boilerplate with a singleton-based architecture.
+
+## 🚀 Quick Start
+
+```bash
+npm i
+npm run dev
+```
+
+## ✨ Features
+
+- Three.js + Vue 3 + Vite + TypeScript
+- GLSL shader support (vite-plugin-glsl)
+- Singleton-based manager architecture (DebugManager, LoaderManager, ThreeAssetsManager, etc.)
+- Lazy loading with animated transitions between views
+- Multi-view system with Vue components and Three.js views (init/reset/dispose lifecycle)
+- ThreeApp layer (LoaderThreeApp, MainThreeApp) for scene orchestration
+- Camera controller system with base classes (MainThreeCameraController, DebugThreeCameraController)
+- ESLint + Prettier
+
+## 🐛 Debug Mode
+
+Add `#debug` to URL: `http://localhost:5173/#debug`
+
+- `Shift + H` → Toggle debug UI + perf monitor
+- `Shift + C` → Toggle debug camera (OrbitControls)
+- `Shift + W` → Toggle wireframe
+- `Ctrl + Click` → Center camera on object
+
+## 📄 License
+
+MIT

package/template-vue/src/experiences/Experience.ts

@@ -0,0 +1,27 @@
+import './styles/style.scss';
+
+import InitCommand from './commands/InitCommand';
+import { ViewId } from './constants/experiences/ViewId';
+import MainThree from './engines/threes/MainThree';
+import MainThreeApp from './engines/threes/app/MainThreeApp';
+import LoaderManager from './managers/LoaderManager';
+
+class Experience {
+    private _isInitialized = false;
+
+    public async init(): Promise<void> {
+        if (this._isInitialized) return;
+        this._isInitialized = true;
+
+        InitCommand.init();
+        MainThree.init();
+
+        await LoaderManager.loadAssetsWithTransition(this._onReady);
+    }
+
+    private readonly _onReady = async (): Promise<void> => {
+        await MainThreeApp.setCurrentView(ViewId.THREE_WORLD_1);
+    };
+}
+
+export default new Experience();

package/template-vue/src/experiences/cameras/threes/DebugThreeCameraController.ts

@@ -0,0 +1,55 @@
+import { DomKeyboardManager, DomPointerManager } from '@benjos/cookware';
+import { KeyboardConstant } from '@benjos/spices';
+import { Vector3 } from 'three';
+import { OrbitControls } from 'three/examples/jsm/Addons.js';
+import { CameraId } from '../../constants/experiences/CameraId';
+import MainThreeApp from '../../engines/threes/app/MainThreeApp';
+import ThreeRaycasterManager from '../../managers/threes/ThreeRaycasterManager';
+import { type ThreeCameraOptions, ThreeCameraType } from '../../types/cameraTypes';
+import ThreeCameraControllerBase from './bases/ThreeCameraControllerBase';
+
+export default class DebugThreeCameraController extends ThreeCameraControllerBase<OrbitControls> {
+    private static readonly _DEBUG_CAMERA_OPTIONS: ThreeCameraOptions = {
+        type: ThreeCameraType.PERSPECTIVE,
+        fov: 75,
+        aspect: window.innerWidth / window.innerHeight,
+        near: 0.1,
+        far: 1000,
+    };
+    private static readonly _DEFAULT_CAMERA_POSITION: Vector3 = new Vector3(0, 1.5, 3);
+    private static readonly _CONTROLS_DAMPING_FACTOR: number = 0.05;
+    private static readonly _CONTROLS_CENTER_KEY: string = KeyboardConstant.CODES.CONTROL_LEFT;
+
+    constructor() {
+        super(CameraId.THREE_DEBUG, DebugThreeCameraController._DEBUG_CAMERA_OPTIONS);
+        this._camera.position.copy(DebugThreeCameraController._DEFAULT_CAMERA_POSITION);
+        this._setControls();
+        this.disable();
+    }
+
+    public override enable(): void {
+        super.enable();
+        DomPointerManager.onPointerDown.add(this._onMouseDown);
+    }
+
+    public override disable(): void {
+        super.disable();
+        DomPointerManager.onPointerDown.remove(this._onMouseDown);
+    }
+
+    private _setControls(): void {
+        this._controls = new OrbitControls(this._camera, MainThreeApp.domElementContainer);
+        this._controls.enableDamping = true;
+        this._controls.dampingFactor = DebugThreeCameraController._CONTROLS_DAMPING_FACTOR;
+    }
+
+    private readonly _onMouseDown = (): void => {
+        if (DomKeyboardManager.isKeyDown(DebugThreeCameraController._CONTROLS_CENTER_KEY)) {
+            const intersect = ThreeRaycasterManager.castFromCameraToPointer(MainThreeApp.scene.children);
+            if (intersect.length > 0) {
+                this._controls.target.copy(intersect[0].point);
+                this._controls.update();
+            }
+        }
+    };
+}

package/template-vue/src/experiences/cameras/threes/LoaderThreeCameraController.ts

@@ -0,0 +1,25 @@
+import { Vector3 } from 'three';
+import { CameraId } from '../../constants/experiences/CameraId';
+import LoaderThreeApp from '../../engines/threes/app/LoaderThreeApp';
+import { type ThreeCameraOptions, ThreeCameraType } from '../../types/cameraTypes';
+import ThreeCameraControllerBase from './bases/ThreeCameraControllerBase';
+
+export default class LoaderThreeCameraController extends ThreeCameraControllerBase {
+    private static readonly _LOADER_CAMERA_OPTIONS: ThreeCameraOptions = {
+        type: ThreeCameraType.PERSPECTIVE,
+        fov: 75,
+        aspect: window.innerWidth / window.innerHeight,
+        near: 0.1,
+        far: 1,
+    };
+    private static readonly _DEFAULT_CONTAINER_POSITION: Vector3 = new Vector3(0, 0, 0);
+
+    constructor() {
+        super(CameraId.THREE_LOADER, LoaderThreeCameraController._LOADER_CAMERA_OPTIONS, LoaderThreeApp.scene);
+        this._container.position.copy(LoaderThreeCameraController._DEFAULT_CONTAINER_POSITION);
+    }
+
+    public override update(dt: number): void {
+        super.update(dt);
+    }
+}

package/template-vue/src/experiences/cameras/threes/MainThreeCameraController.ts

@@ -0,0 +1,24 @@
+import { Vector3 } from 'three';
+import { CameraId } from '../../constants/experiences/CameraId';
+import { type ThreeCameraOptions, ThreeCameraType } from '../../types/cameraTypes';
+import ThreeCameraControllerBase from './bases/ThreeCameraControllerBase';
+
+export default class MainThreeCameraController extends ThreeCameraControllerBase {
+    private static readonly _MAIN_CAMERA_OPTIONS: ThreeCameraOptions = {
+        type: ThreeCameraType.PERSPECTIVE,
+        fov: 75,
+        aspect: window.innerWidth / window.innerHeight,
+        near: 0.1,
+        far: 1000,
+    };
+    private static readonly _DEFAULT_CONTAINER_POSITION: Vector3 = new Vector3(0, 1.5, 3);
+
+    constructor() {
+        super(CameraId.THREE_MAIN, MainThreeCameraController._MAIN_CAMERA_OPTIONS);
+        this._container.position.copy(MainThreeCameraController._DEFAULT_CONTAINER_POSITION);
+    }
+
+    public override update(dt: number): void {
+        super.update(dt);
+    }
+}

package/template-vue/src/experiences/cameras/threes/bases/ThreeCameraControllerBase.ts

@@ -0,0 +1,90 @@
+import { DomResizeManager } from '@benjos/cookware';
+import { Object3D, OrthographicCamera, PerspectiveCamera, Scene } from 'three';
+import type { CameraId } from '../../../constants/experiences/CameraId';
+import MainThreeApp from '../../../engines/threes/app/MainThreeApp';
+import { type ThreeCameraOptions, ThreeCameraType, type ThreeControls } from '../../../types/cameraTypes';
+
+export default abstract class ThreeCameraControllerBase<T extends ThreeControls = ThreeControls> extends Object3D {
+    private static readonly _DEFAULT_CAMERA_OPTIONS: ThreeCameraOptions = {
+        type: ThreeCameraType.PERSPECTIVE,
+        fov: 75,
+        aspect: window.innerWidth / window.innerHeight,
+        near: 0.1,
+        far: 1000,
+    };
+
+    protected readonly _cameraId: CameraId;
+    declare protected _camera: PerspectiveCamera | OrthographicCamera;
+    declare protected _container: Object3D;
+    declare protected _controls: T;
+
+    constructor(
+        cameraId: CameraId,
+        cameraOptions: ThreeCameraOptions = ThreeCameraControllerBase._DEFAULT_CAMERA_OPTIONS,
+        scene: Scene = MainThreeApp.scene
+    ) {
+        super();
+        this._cameraId = cameraId;
+
+        this._generateContainer();
+        this._generateCamera(cameraOptions);
+
+        scene.add(this);
+    }
+
+    private _generateContainer(): void {
+        this._container = new Object3D();
+        this.add(this._container);
+    }
+
+    private _generateCamera(cameraOptions: ThreeCameraOptions): void {
+        if (cameraOptions.type === ThreeCameraType.PERSPECTIVE) {
+            this._camera = new PerspectiveCamera(
+                cameraOptions.fov,
+                cameraOptions.aspect,
+                cameraOptions.near,
+                cameraOptions.far
+            );
+        } else {
+            this._camera = new OrthographicCamera(
+                cameraOptions.left,
+                cameraOptions.right,
+                cameraOptions.top,
+                cameraOptions.bottom,
+                cameraOptions.near,
+                cameraOptions.far
+            );
+        }
+        this._container.add(this._camera);
+    }
+
+    public enable(): void {
+        if (this._controls) this._controls.enabled = true;
+    }
+
+    public disable(): void {
+        if (this._controls) this._controls.enabled = false;
+    }
+
+    public resize(): void {
+        if (this._camera instanceof PerspectiveCamera) {
+            this._camera.aspect = DomResizeManager.width / DomResizeManager.height;
+        }
+        this._camera.updateProjectionMatrix();
+    }
+
+    public update(_dt: number): void {
+        if (this._controls) this._controls.update();
+    }
+
+    //#region Getters
+    //
+    public get cameraId(): CameraId {
+        return this._cameraId;
+    }
+    public get camera(): PerspectiveCamera | OrthographicCamera {
+        return this._camera;
+    }
+    //
+    //#endregion
+}

package/template-vue/src/experiences/commands/InitCommand.ts

@@ -0,0 +1,50 @@
+import { AssetUtils, DomKeyboardManager, DomPointerManager, DomResizeManager, TickerManager } from '@benjos/cookware';
+import { AssetId } from '../constants/experiences/AssetId';
+import DebugManager from '../managers/DebugManager';
+import LoaderManager from '../managers/LoaderManager';
+import ThreeAssetsManager from '../managers/threes/ThreeAssetsManager';
+import ThreeCameraControllerManager from '../managers/threes/ThreeCameraControllerManager';
+import ThreeRaycasterManager from '../managers/threes/ThreeRaycasterManager';
+
+class InitCommand {
+    public init(): void {
+        this._initUtils();
+        this._initProxies();
+        this._initManagers();
+        this._initCommonAssets();
+        this._initThreeSharedAssets();
+    }
+
+    private _initUtils(): void {
+        AssetUtils.Init();
+    }
+
+    private _initProxies(): void {
+        //
+    }
+
+    private _initManagers(): void {
+        TickerManager.init();
+        DomKeyboardManager.init();
+        DomPointerManager.init();
+        ThreeAssetsManager.init();
+        ThreeCameraControllerManager.init();
+        DomResizeManager.init();
+        DebugManager.init();
+        ThreeRaycasterManager.init();
+        LoaderManager.init();
+    }
+
+    private _initCommonAssets(): void {
+        //
+    }
+
+    private _initThreeSharedAssets(): void {
+        ThreeAssetsManager.addHDR(AssetId.THREE_HDR_TEMPLATE, AssetUtils.GetPath('hdrs/template.hdr'));
+        ThreeAssetsManager.addModel(AssetId.THREE_GLTF_TEMPLATE, AssetUtils.GetPath('models/template.glb'));
+        ThreeAssetsManager.addTexture(AssetId.THREE_TEXTURE_TEMPLATE, AssetUtils.GetPath('textures/template.jpg'));
+        ThreeAssetsManager.addFont(AssetId.THREE_FONT_TEMPLATE, AssetUtils.GetPath('fonts/template.typeface.json'));
+    }
+}
+
+export default new InitCommand();

package/template-vue/src/experiences/constants/experiences/AnimationId.ts

@@ -0,0 +1,3 @@
+export const AnimationId = {} as const;
+
+export type AnimationId = (typeof AnimationId)[keyof typeof AnimationId];

package/template-vue/src/experiences/constants/experiences/AssetId.ts

@@ -0,0 +1,8 @@
+export const AssetId = {
+    THREE_TEXTURE_TEMPLATE: 'THREE_TEXTURE_TEMPLATE',
+    THREE_HDR_TEMPLATE: 'THREE_HDR_TEMPLATE',
+    THREE_GLTF_TEMPLATE: 'THREE_GLTF_TEMPLATE',
+    THREE_FONT_TEMPLATE: 'THREE_FONT_TEMPLATE',
+} as const;
+
+export type AssetId = (typeof AssetId)[keyof typeof AssetId];

package/template-vue/src/experiences/constants/experiences/CameraId.ts

@@ -0,0 +1,7 @@
+export const CameraId = {
+    THREE_DEBUG: 'THREE_DEBUG',
+    THREE_MAIN: 'THREE_MAIN',
+    THREE_LOADER: 'THREE_LOADER',
+} as const;
+
+export type CameraId = (typeof CameraId)[keyof typeof CameraId];

package/template-vue/src/experiences/constants/experiences/DebugGuiTitle.ts

@@ -0,0 +1,6 @@
+export const DebugGuiTitle = {
+    THREE_RENDERER: 'Three Renderer',
+    THREE_VIEWS: 'Three Views',
+} as const;
+
+export type DebugGuiTitle = (typeof DebugGuiTitle)[keyof typeof DebugGuiTitle];

package/template-vue/src/experiences/constants/experiences/Object3dId.ts

@@ -0,0 +1,3 @@
+export const Object3DId = {} as const;
+
+export type Object3DId = (typeof Object3DId)[keyof typeof Object3DId];

package/template-vue/src/experiences/constants/experiences/ViewId.ts

@@ -0,0 +1,11 @@
+const ThreeViewId = {
+    THREE_LOADER: 'THREE_LOADER',
+    THREE_WORLD_1: 'THREE_WORLD_1',
+    THREE_WORLD_2: 'THREE_WORLD_2',
+} as const;
+
+export const ViewId = {
+    ...ThreeViewId,
+} as const;
+
+export type ViewId = (typeof ViewId)[keyof typeof ViewId];

package/template-vue/src/experiences/constants/experiences/ViewType.ts

@@ -0,0 +1,6 @@
+export const ViewType = {
+    HTML: 'HTML',
+    THREE: 'THREE',
+} as const;
+
+export type ViewType = (typeof ViewType)[keyof typeof ViewType];

package/template-vue/src/experiences/engines/threes/MainThree.ts

@@ -0,0 +1,11 @@
+import LoaderThreeApp from './app/LoaderThreeApp';
+import MainThreeApp from './app/MainThreeApp';
+
+class MainThree {
+    public init(): void {
+        LoaderThreeApp.init();
+        MainThreeApp.init();
+    }
+}
+
+export default new MainThree();

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

@@ -0,0 +1,49 @@
+import { DomUtils } from '@benjos/cookware';
+import { Scene } from 'three';
+import LoaderThreeCameraController from '../../../cameras/threes/LoaderThreeCameraController';
+import { CameraId } from '../../../constants/experiences/CameraId';
+import LoaderManager from '../../../managers/LoaderManager';
+import ThreeCameraControllerManager from '../../../managers/threes/ThreeCameraControllerManager';
+import LoaderRenderer from '../../../renderers/threes/LoaderRenderer';
+import LoaderThreeView from '../../../views/threes/loaders/LoaderThreeView';
+import ThreeAppBase from './bases/ThreeAppBase';
+
+class LoaderThreeApp extends ThreeAppBase {
+    constructor() {
+        super();
+    }
+
+    protected override _setDomElementContainer(): void {
+        this._domElementContainer = DomUtils.GetLoader();
+    }
+
+    protected override _generateScenes(): void {
+        this._scene = new Scene();
+    }
+
+    protected override _generateCameras(): void {
+        ThreeCameraControllerManager.add(new LoaderThreeCameraController());
+        this._cameraController = ThreeCameraControllerManager.get(CameraId.THREE_LOADER);
+    }
+
+    protected override _generateRenderers(): void {
+        this._renderer = new LoaderRenderer(
+            this._scene,
+            ThreeCameraControllerManager.get(CameraId.THREE_LOADER).camera
+        );
+        this._domElementContainer.appendChild(this._renderer.domElement);
+    }
+
+    protected override _declareViews(): void {
+        const loaderThreeView = new LoaderThreeView();
+        this._views.push(loaderThreeView);
+        this._currentView = loaderThreeView;
+        loaderThreeView.init();
+        this._scene.add(loaderThreeView);
+
+        LoaderManager.setShowTransition(loaderThreeView.show);
+        LoaderManager.setHideTransition(loaderThreeView.hide);
+    }
+}
+
+export default new LoaderThreeApp();

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

@@ -0,0 +1,112 @@
+import { DomKeyboardManager, DomUtils } from '@benjos/cookware';
+import { KeyboardConstant } from '@benjos/spices';
+import { MeshStandardMaterial, Scene } from 'three';
+import DebugThreeCameraController from '../../../cameras/threes/DebugThreeCameraController';
+import MainThreeCameraController from '../../../cameras/threes/MainThreeCameraController';
+import { CameraId } from '../../../constants/experiences/CameraId';
+import { DebugGuiTitle } from '../../../constants/experiences/DebugGuiTitle';
+import { ViewId } from '../../../constants/experiences/ViewId';
+import DebugManager from '../../../managers/DebugManager';
+import ThreeCameraControllerManager from '../../../managers/threes/ThreeCameraControllerManager';
+import Renderer from '../../../renderers/threes/Renderer';
+import World2ThreeView from '../../../views/threes/worlds/World2ThreeView';
+import WorldThreeView from '../../../views/threes/worlds/WorldThreeView';
+import ThreeAppBase from './bases/ThreeAppBase';
+
+class MainThreeApp extends ThreeAppBase {
+    private static readonly _DEBUG_WIREFRAME_MATERIAL_COLOR: number = 0x3f79f3;
+    private static readonly _TOGGLE_SWITCH_TO_DEBUG_CAMERA_KEYS: string[] = [
+        KeyboardConstant.CODES.SHIFT_LEFT,
+        KeyboardConstant.CODES.KEY_C,
+    ];
+    private static readonly _TOGGLE_WIREFRAME_KEYS: string[] = [
+        KeyboardConstant.CODES.SHIFT_LEFT,
+        KeyboardConstant.CODES.KEY_W,
+    ];
+
+    declare private _debugWireframeMaterial: MeshStandardMaterial;
+    declare private _debugPreviousCameraId: CameraId;
+
+    constructor() {
+        super();
+    }
+
+    public override init(): void {
+        super.init();
+
+        if (DebugManager.isActive) {
+            window.mainThreeApp = this;
+            DomKeyboardManager.onKeyDown.add(this._onKeyDown);
+        }
+    }
+
+    protected override _setDomElementContainer(): void {
+        this._domElementContainer = DomUtils.GetApp();
+    }
+
+    protected override _generateScenes(): void {
+        this._scene = new Scene();
+
+        if (DebugManager.isActive) {
+            this._debugWireframeMaterial = new MeshStandardMaterial({
+                wireframe: true,
+                color: MainThreeApp._DEBUG_WIREFRAME_MATERIAL_COLOR,
+            });
+        }
+    }
+
+    protected override _generateCameras(): void {
+        ThreeCameraControllerManager.add(new MainThreeCameraController(), true);
+        this._cameraController = ThreeCameraControllerManager.get(CameraId.THREE_MAIN);
+
+        if (DebugManager.isActive) {
+            this._debugPreviousCameraId = this._cameraController.cameraId;
+            ThreeCameraControllerManager.add(new DebugThreeCameraController());
+        }
+
+        ThreeCameraControllerManager.onActiveThreeCameraControllerChange.add(this._onActiveCameraControllerChange);
+    }
+
+    protected override _generateRenderers(): void {
+        this._renderer = new Renderer(this._scene, this._cameraController.camera, { antialias: true });
+        this._domElementContainer.appendChild(this._renderer.domElement);
+    }
+
+    protected override _declareViews(): void {
+        this._viewBuilder.set(ViewId.THREE_WORLD_1, WorldThreeView);
+        this._viewBuilder.set(ViewId.THREE_WORLD_2, World2ThreeView);
+
+        if (DebugManager.isActive) {
+            const viewsDebug = DebugManager.getGuiFolder(DebugGuiTitle.THREE_VIEWS)
+            viewsDebug.add({ resetCurrentView: () => this._currentView.reset() }, 'resetCurrentView');
+            viewsDebug.add({ createWorld1: () => this.setCurrentView(ViewId.THREE_WORLD_1) }, 'createWorld1');
+            viewsDebug.add({ createWorld2: () => this.setCurrentView(ViewId.THREE_WORLD_2) }, 'createWorld2');
+        }
+    }
+
+    private _onActiveCameraControllerChange = (): void => {
+        this._cameraController = ThreeCameraControllerManager.activeThreeCameraController;
+        this._renderer.setCamera(this._cameraController.camera);
+        this._onResize();
+    };
+
+    private readonly _onKeyDown = (_e: KeyboardEvent): void => {
+        if (DebugManager.isActive) {
+            if (DomKeyboardManager.areAllKeysDown(MainThreeApp._TOGGLE_SWITCH_TO_DEBUG_CAMERA_KEYS)) {
+                if (this._cameraController.cameraId !== CameraId.THREE_DEBUG) this._debugPreviousCameraId = this._cameraController.cameraId;
+                ThreeCameraControllerManager.setActiveCamera(
+                    this._cameraController.cameraId === CameraId.THREE_DEBUG ? this._debugPreviousCameraId : CameraId.THREE_DEBUG
+                );
+            } else if (DomKeyboardManager.areAllKeysDown(MainThreeApp._TOGGLE_WIREFRAME_KEYS)) {
+                if (this._scene.overrideMaterial === null) {
+                    this._scene.overrideMaterial = this._debugWireframeMaterial;
+                } else {
+                    this._scene.overrideMaterial = null;
+                }
+            }
+        }
+    };
+}
+
+export type { MainThreeApp };
+export default new MainThreeApp();