bucciafico-lib 1.0.7 → 1.0.9

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "bucciafico-lib",
-  "version": "1.0.7",
-  "description": "Modular 3D rendering engine for Minecraft skins based on Three.js",
-  "type": "module",
-  "main": "./index.js",
-  "exports": {
-    ".": "./index.js"
-  },
-  "files": [
-    "src",
-    "index.js",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [
-    "minecraft",
-    "3d",
-    "threejs",
-    "skin",
-    "viewer",
-    "renderer"
-  ],
-  "author": "Dawid Maj",
-  "license": "MIT",
-  "peerDependencies": {
-    "three": "^0.160.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/HappyGFX/bucciafico-lib.git"
-  },
-  "bugs": {
-    "url": "https://github.com/HappyGFX/bucciafico-lib/issues"
-  },
-  "homepage": "https://github.com/HappyGFX/bucciafico-lib#readme"
-}
+{
+  "name": "bucciafico-lib",
+  "version": "1.0.9",
+  "description": "Modular 3D rendering engine for Minecraft skins based on Three.js",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "src",
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "minecraft",
+    "3d",
+    "threejs",
+    "skin",
+    "viewer",
+    "renderer"
+  ],
+  "author": "Dawid Maj",
+  "license": "MIT",
+  "peerDependencies": {
+    "three": "^0.160.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HappyGFX/bucciafico-lib.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HappyGFX/bucciafico-lib/issues"
+  },
+  "homepage": "https://github.com/HappyGFX/bucciafico-lib#readme"
+}

package/src/core/SkinViewer.js

@@ -3,6 +3,9 @@ import { CameraManager } from '../managers/CameraManager.js';
 import { SceneSetup } from '../objects/SceneSetup.js';
 import { SkinModel } from '../objects/SkinModel.js';
 import { detectSlimSkin } from '../utils/SkinUtils.js';
+import {disposeObjectTree} from "../utils/ThreeUtils.js";
+import {EventManager} from "../managers/EventManager.js";
+import {createPlaceholderTexture} from "../utils/TextureUtils.js";
 
 /**
  * Core 3D Viewer class.
@@ -30,6 +33,9 @@ export class SkinViewer {
             ...config
         };
 
+        this.skinData = null;
+        this.capeData = null;
+
         /** @type {Map<string, Object>} Registered plugins. */
         this.plugins = new Map();
 
@@ -39,6 +45,12 @@ export class SkinViewer {
         this.isVisible = true;
         this.needsRender = true;
 
+        this.events = new EventManager();
+
+        this.on = this.events.on.bind(this.events);
+        this.off = this.events.off.bind(this.events);
+        this.emit = this.events.emit.bind(this.events);
+
         // --- 1. RENDERER SETUP ---
         this.renderer = new THREE.WebGLRenderer({
             antialias: true,
@@ -62,6 +74,9 @@ export class SkinViewer {
             this.scene.background = new THREE.Color(this.config.bgColor);
         }
 
+        this.skinModel = new SkinModel();
+        this.scene.add(this.skinModel.getGroup());
+
         this.overlayScene = new THREE.Scene();
 
         this.sceneSetup = new SceneSetup(this.scene);
@@ -72,8 +87,7 @@ export class SkinViewer {
         });
         this.cameraManager.setEnabled(this.config.cameraEnabled);
 
-        this.skinModel = new SkinModel();
-        this.scene.add(this.skinModel.getGroup());
+        this.loadPlaceholderSkin();
 
         this.observer = new IntersectionObserver((entries) => {
             if (entries[0].isIntersecting) {
@@ -88,6 +102,7 @@ export class SkinViewer {
 
         // --- 3. START LOOP ---
         this.animate = this.animate.bind(this);
+        this.emit('viewer:ready', this);
         this.animate();
     }
 
@@ -124,14 +139,32 @@ export class SkinViewer {
         return this.plugins.get(name);
     }
 
+    loadPlaceholderSkin() {
+        const placeholderTex = createPlaceholderTexture();
+        this.skinData = null;
+        this.resetCape();
+        this.skinModel.build(placeholderTex, false, false);
+        this.requestRender();
+    }
+
     /**
      * Loads a skin from URL.
      * @param {string} imageUrl
      * @returns {Promise<boolean>} isSlim
      */
     loadSkin(imageUrl) {
+        this.emit('skin:loading', imageUrl);
+
         return new Promise((resolve, reject) => {
-            new THREE.TextureLoader().load(imageUrl, (texture) => {
+            const loader = new THREE.TextureLoader();
+            loader.setCrossOrigin('anonymous');
+
+            loader.load(imageUrl, (texture) => {
+                if (this.isDisposed) {
+                    texture.dispose();
+                    return;
+                }
+
                 texture.magFilter = THREE.NearestFilter;
                 texture.colorSpace = THREE.SRGBColorSpace;
 
@@ -141,13 +174,24 @@ export class SkinViewer {
                 const editor = this.getPlugin('EditorPlugin');
                 if (editor) editor.deselect();
 
-                this.skinModel.build(texture, isSlim);
+                this.skinModel.build(texture, isSlim, true);
                 this.skinModel.setPose(currentPose);
                 this.skinData = { type: 'url', value: imageUrl };
 
+                const fxPlugin = this.getPlugin('EffectsPlugin');
+                if (fxPlugin) {
+                    fxPlugin.forceUpdate();
+                }
+
                 this.requestRender();
+
+                this.emit('skin:loaded', { isSlim, texture });
+
                 resolve(isSlim);
-            }, undefined, reject);
+            }, undefined, (err) => {
+                this.emit('skin:error', err);
+                reject(err);
+            });
         });
     }
 
@@ -161,6 +205,101 @@ export class SkinViewer {
         });
     }
 
+    /**
+     * Loads a cape from URL.
+     * @param {string} imageUrl
+     */
+    loadCape(imageUrl) {
+        return new Promise((resolve, reject) => {
+            const loader = new THREE.TextureLoader();
+            loader.setCrossOrigin('anonymous');
+
+            loader.load(
+                imageUrl,
+                (texture) => {
+                    if (this.isDisposed) {
+                        texture.dispose();
+                        return;
+                    }
+
+                    texture.magFilter = THREE.NearestFilter;
+                    texture.colorSpace = THREE.SRGBColorSpace;
+
+                    texture.needsUpdate = true;
+
+                    this.skinModel.setCape(texture);
+
+                    const fxPlugin = this.getPlugin('EffectsPlugin');
+                    if (fxPlugin) {
+                        fxPlugin.forceUpdate();
+                    }
+
+                    this.capeData = { type: 'url', value: imageUrl };
+
+                    this.requestRender();
+                    this.emit('cape:loaded', imageUrl);
+                    resolve();
+                },
+                undefined,
+                (err) => {
+                    console.error("Error loading cape texture:", err);
+                    reject(err);
+                }
+            );
+        });
+    }
+
+
+    /**
+     * Loads a cape by username using capes.dev API.
+     * Supports Official, Optifine, LabyMod, etc.
+     * @param {string} username
+     */
+    async loadCapeByUsername(username) {
+        this.emit('cape:loading', username);
+
+        try {
+            const response = await fetch(`https://api.capes.dev/load/${username}`);
+
+            if (!response.ok) {
+                throw new Error(`User not found in capes.dev (Status: ${response.status})`);
+            }
+
+            const data = await response.json();
+            let capeUrl = null;
+
+            if (data.minecraft?.exists && data.minecraft?.imageUrl) {
+                capeUrl = data.minecraft.imageUrl;
+            } else if (data.optifine?.exists && data.optifine?.imageUrl) {
+                capeUrl = data.optifine.imageUrl;
+            } else if (data.labymod?.exists && data.labymod?.imageUrl) {
+                capeUrl = data.labymod.imageUrl;
+            } else if (data.tlauncher?.exists && data.tlauncher?.imageUrl) {
+                capeUrl = data.tlauncher.imageUrl;
+            }
+
+            if (capeUrl) {
+                await this.loadCape(capeUrl);
+                this.capeData = { type: 'username', value: username };
+                return true;
+            } else {
+                this.resetCape();
+                return false;
+            }
+
+        } catch (e) {
+            this.emit('cape:error', e);
+            return false;
+        }
+    }
+
+    resetCape() {
+        this.skinModel.setCape(null);
+        this.capeData = null;
+        this.requestRender();
+        this.emit('cape:removed');
+    }
+
     setPose(poseData) {
         // Record history if Editor is present
         const editor = this.getPlugin('EditorPlugin');
@@ -170,6 +309,40 @@ export class SkinViewer {
         this.requestRender();
     }
 
+    /**
+     * Updates lighting intensity.
+     * @param {Object} config - { global, main, fill }
+     */
+    setEnvironment(config) {
+        this.sceneSetup.setLightConfig(config);
+        this.requestRender();
+    }
+
+    /**
+     * Updates scene configuration at runtime.
+     * @param {Object} config
+     * @param {boolean} [config.showGrid]
+     * @param {boolean} [config.transparent]
+     * @param {string|number} [config.bgColor] - Hex color
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+
+        if (config.showGrid !== undefined) {
+            this.sceneSetup.setGridVisible(config.showGrid);
+        }
+
+        if (this.config.transparent) {
+            this.scene.background = null;
+            this.renderer.setClearAlpha(0);
+        } else {
+            this.renderer.setClearAlpha(1);
+            this.scene.background = new THREE.Color(this.config.bgColor);
+        }
+
+        this.requestRender();
+    }
+
     /**
      * Handles window resize. Should be called by the implementation layer.
      */
@@ -215,19 +388,37 @@ export class SkinViewer {
     }
 
     dispose() {
+        this.emit('viewer:dispose');
         this.isDisposed = true;
         this.observer.disconnect();
 
-        if (this.container && this.renderer.domElement) {
-            this.container.removeChild(this.renderer.domElement);
-        }
-
-        this.renderer.dispose();
-
-        // Dispose all plugins
         this.plugins.forEach(p => {
             if (p.dispose) p.dispose();
         });
         this.plugins.clear();
+
+        if (this.skinModel) {
+            this.skinModel.dispose();
+        }
+
+        disposeObjectTree(this.scene);
+        disposeObjectTree(this.overlayScene);
+
+        if (this.cameraManager) {
+            this.cameraManager.controls.dispose();
+        }
+
+        if (this.renderer) {
+            this.renderer.dispose();
+            this.renderer.forceContextLoss();
+
+            if (this.container && this.renderer.domElement) {
+                this.container.removeChild(this.renderer.domElement);
+            }
+            this.renderer.domElement = null;
+            this.renderer = null;
+        }
+
+        this.events.dispose();
     }
 }

package/src/managers/EventManager.js

@@ -0,0 +1,74 @@
+/**
+ * Custom Event Emitter implementation.
+ * Handles Pub/Sub architecture to decouple Core from Plugins and UI.
+ */
+export class EventManager {
+    constructor() {
+        /** @type {Map<string, Set<Function>>} */
+        this.listeners = new Map();
+    }
+
+    /**
+     * Subscribe to an event.
+     * @param {string} event - Event name (e.g. 'skin:loaded').
+     * @param {Function} callback - Function to execute.
+     * @returns {Function} Unsubscribe function for convenience.
+     */
+    on(event, callback) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(callback);
+
+        // Return unsubscribe function pattern
+        return () => this.off(event, callback);
+    }
+
+    /**
+     * Unsubscribe from an event.
+     * @param {string} event
+     * @param {Function} callback
+     */
+    off(event, callback) {
+        if (this.listeners.has(event)) {
+            this.listeners.get(event).delete(callback);
+        }
+    }
+
+    /**
+     * Subscribe to an event only once.
+     * @param {string} event
+     * @param {Function} callback
+     */
+    once(event, callback) {
+        const wrapper = (...args) => {
+            callback(...args);
+            this.off(event, wrapper);
+        };
+        this.on(event, wrapper);
+    }
+
+    /**
+     * Emit an event with optional data.
+     * @param {string} event
+     * @param {*} [data]
+     */
+    emit(event, data) {
+        if (this.listeners.has(event)) {
+            this.listeners.get(event).forEach(cb => {
+                try {
+                    cb(data);
+                } catch (e) {
+                    console.error(`Error in listener for event "${event}":`, e);
+                }
+            });
+        }
+    }
+
+    /**
+     * Clears all listeners. Used for disposal.
+     */
+    dispose() {
+        this.listeners.clear();
+    }
+}

package/src/managers/PostProcessingManager.js

@@ -131,4 +131,28 @@ export class PostProcessingManager {
         this.bloomPass.radius = Number(rad);
         this.bloomPass.threshold = Number(thr);
     }
+
+    dispose() {
+        if (this.bloomComposer) {
+            this.bloomComposer.renderTarget1.dispose();
+            this.bloomComposer.renderTarget2.dispose();
+        }
+
+        if (this.finalComposer) {
+            this.finalComposer.renderTarget1.dispose();
+            this.finalComposer.renderTarget2.dispose();
+        }
+
+        if (this.bloomPass) {
+            this.bloomPass.dispose();
+        }
+
+        if (this.outlinePass) {
+            this.outlinePass.dispose();
+        }
+
+        if (this.mixPass && this.mixPass.material) {
+            this.mixPass.material.dispose();
+        }
+    }
 }

package/src/objects/SceneSetup.js

@@ -7,19 +7,32 @@ export class SceneSetup {
     constructor(scene) {
         this.scene = scene;
         this.gridHelper = null;
+
+        this.ambientLight = null;
+        this.hemiLight = null;
+        this.dirLightMain = null;
+        this.dirLightFill = null;
+
         this.initLights();
         this.initHelpers();
     }
 
     initLights() {
-        this.scene.add(new THREE.AmbientLight(0xffffff, 0.8));
-        this.scene.add(new THREE.HemisphereLight(0xffffff, 0x444444, 0.5));
-        const dl = new THREE.DirectionalLight(0xffffff, 0.8);
-        dl.position.set(10, 20, 10);
-        this.scene.add(dl);
-        const fl = new THREE.DirectionalLight(0xffffff, 0.4);
-        fl.position.set(0, 0, 20);
-        this.scene.add(fl);
+        // 1. Global Illumination
+        this.ambientLight = new THREE.AmbientLight(0xffffff, 0.8);
+        this.scene.add(this.ambientLight);
+
+        this.hemiLight = new THREE.HemisphereLight(0xffffff, 0x444444, 0.5);
+        this.scene.add(this.hemiLight);
+
+        // 2. Directional Lights (Shadows & Definition)
+        this.dirLightMain = new THREE.DirectionalLight(0xffffff, 0.8);
+        this.dirLightMain.position.set(10, 20, 10);
+        this.scene.add(this.dirLightMain);
+
+        this.dirLightFill = new THREE.DirectionalLight(0xffffff, 0.4);
+        this.dirLightFill.position.set(0, 0, 20);
+        this.scene.add(this.dirLightFill);
     }
 
     initHelpers() {
@@ -29,4 +42,32 @@ export class SceneSetup {
     }
 
     setGridVisible(vis) { if(this.gridHelper) this.gridHelper.visible = vis; }
+
+    /**
+     * Updates the intensity of scene lights.
+     * @param {Object} config
+     * @param {number} [config.global] - Intensity of Ambient/Hemi lights (0.0 - 2.0)
+     * @param {number} [config.main] - Intensity of Main Directional Light (0.0 - 2.0)
+     * @param {number} [config.fill] - Intensity of Fill Light (0.0 - 2.0)
+     */
+    setLightConfig(config) {
+        if (config.global !== undefined) {
+            this.ambientLight.intensity = config.global;
+            this.hemiLight.intensity = config.global * 0.6;
+        }
+        if (config.main !== undefined) {
+            this.dirLightMain.intensity = config.main;
+        }
+        if (config.fill !== undefined) {
+            this.dirLightFill.intensity = config.fill;
+        }
+    }
+
+    getLightConfig() {
+        return {
+            global: this.ambientLight.intensity,
+            main: this.dirLightMain.intensity,
+            fill: this.dirLightFill.intensity
+        };
+    }
 }