bucciafico-lib 1.0.7 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bucciafico-lib",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Modular 3D rendering engine for Minecraft skins based on Three.js",
   "type": "module",
   "main": "./index.js",

package/src/core/SkinViewer.js

@@ -3,6 +3,8 @@ 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";
 
 /**
  * Core 3D Viewer class.
@@ -30,6 +32,9 @@ export class SkinViewer {
             ...config
         };
 
+        this.skinData = null;
+        this.capeData = null;
+
         /** @type {Map<string, Object>} Registered plugins. */
         this.plugins = new Map();
 
@@ -39,6 +44,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,
@@ -88,6 +99,7 @@ export class SkinViewer {
 
         // --- 3. START LOOP ---
         this.animate = this.animate.bind(this);
+        this.emit('viewer:ready', this);
         this.animate();
     }
 
@@ -130,8 +142,13 @@ export class SkinViewer {
      * @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) => {
                 texture.magFilter = THREE.NearestFilter;
                 texture.colorSpace = THREE.SRGBColorSpace;
 
@@ -145,9 +162,20 @@ export class SkinViewer {
                 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 +189,96 @@ 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) => {
+                    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 +288,15 @@ export class SkinViewer {
         this.requestRender();
     }
 
+    /**
+     * Updates lighting intensity.
+     * @param {Object} config - { global, main, fill }
+     */
+    setEnvironment(config) {
+        this.sceneSetup.setLightConfig(config);
+        this.requestRender();
+    }
+
     /**
      * Handles window resize. Should be called by the implementation layer.
      */
@@ -215,19 +342,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
+        };
+    }
 }

package/src/objects/SkinModel.js

@@ -3,6 +3,7 @@ import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUti
 import { applySkinUVs } from '../utils/SkinUtils.js';
 import { createVoxelLayer } from '../utils/Voxelizer.js';
 import { createGlowMaterial } from '../materials/GlowMaterial.js';
+import {disposeObjectTree} from "../utils/ThreeUtils.js";
 
 /**
  * Represents the Minecraft Character Model (Steve/Alex).
@@ -16,6 +17,8 @@ export class SkinModel {
         this.bodyMeshes = [];
         this.defaultPositions = {};
         this.blackMaterial = new THREE.MeshBasicMaterial({ color: 0x000000 });
+
+        this.LAYERS_COUNT = 20;
     }
 
     /**
@@ -59,15 +62,30 @@ export class SkinModel {
             this.bodyMeshes.push(voxelMesh);
         }
 
-        // 3. Glow Mesh (Copy of geometry for shader)
+        // 3. Glow Meshes (Multi-Layer Shells)
         const glowParts = [innerGeo.clone()];
         if (voxelGeo) glowParts.push(voxelGeo.clone());
-        const glowGeo = BufferGeometryUtils.mergeGeometries(glowParts, false);
-        const glowMat = createGlowMaterial(size.h);
-        const glowMesh = new THREE.Mesh(glowGeo, glowMat);
-        glowMesh.userData.glowMat = glowMat;
-        this.glowMeshes.push(glowMesh);
-        meshGroup.add(glowMesh);
+        const baseGlowGeo = BufferGeometryUtils.mergeGeometries(glowParts, false);
+
+        const partLayers = [];
+
+        for (let i = 0; i < this.LAYERS_COUNT; i++) {
+            const glowMat = createGlowMaterial(size.h);
+
+            glowMat.uniforms.thickness.value = 0;
+            glowMat.uniforms.opacity.value = 0;
+
+            const layerMesh = new THREE.Mesh(baseGlowGeo, glowMat);
+
+            layerMesh.userData.layerIndex = i;
+            layerMesh.userData.isGlow = true;
+            layerMesh.userData.glowMat = glowMat;
+
+            meshGroup.add(layerMesh);
+            partLayers.push(layerMesh);
+        }
+
+        this.glowMeshes.push(partLayers);
 
         pivotGroup.add(meshGroup);
         return pivotGroup;
@@ -79,7 +97,24 @@ export class SkinModel {
      * @param {boolean} isSlim - True for Alex model (3px arms), False for Steve (4px arms).
      */
     build(texture, isSlim = false) {
-        this.playerGroup.clear();
+        let capeBackup = null;
+        if (this.parts.cape) {
+            const mesh = this.parts.cape.children.find(c => c.isMesh);
+            if (mesh && mesh.material.map) {
+                capeBackup = {
+                    texture: mesh.material.map,
+                    position: this.parts.cape.position.clone(),
+                    rotation: this.parts.cape.rotation.clone(),
+                    scale: this.parts.cape.scale.clone()
+                };
+            }
+        }
+
+        if (this.playerGroup.children.length > 0) {
+            disposeObjectTree(this.playerGroup);
+            this.playerGroup.clear();
+        }
+
         this.parts = {};
         this.glowMeshes = [];
         this.bodyMeshes = [];
@@ -102,13 +137,132 @@ export class SkinModel {
             this.parts[name] = part;
             this.playerGroup.add(part);
         }
+
+        if (capeBackup) {
+            this.setCape(capeBackup.texture);
+
+            if (this.parts.cape) {
+                this.parts.cape.position.copy(capeBackup.position);
+                this.parts.cape.rotation.copy(capeBackup.rotation);
+                this.parts.cape.scale.copy(capeBackup.scale);
+            }
+        }
+    }
+
+    /**
+     * Adds or updates the Cape mesh.
+     * @param {THREE.Texture} texture
+     */
+    setCape(texture) {
+        if (this.parts.cape) {
+            if (this.parts.cape.userData.glowLayers) {
+                const layersToRemove = this.parts.cape.userData.glowLayers;
+                this.glowMeshes = this.glowMeshes.filter(layers => layers !== layersToRemove);
+            }
+
+            this.playerGroup.remove(this.parts.cape);
+            disposeObjectTree(this.parts.cape);
+            delete this.parts.cape;
+        }
+
+        if (!texture) return;
+
+        const size = { w: 10, h: 16, d: 1 };
+        const pivotPos = new THREE.Vector3(0, 0, -3);
+        const meshOffset = new THREE.Vector3(0, -8, 0.6);
+
+        const pivotGroup = new THREE.Group();
+        pivotGroup.position.copy(pivotPos);
+        pivotGroup.name = 'cape';
+        pivotGroup.rotation.x = 0.2;
+
+        this.defaultPositions['cape'] = pivotPos.clone();
+
+        const geo = new THREE.BoxGeometry(size.w, size.h, size.d);
+        applySkinUVs(geo, 0, 0, 10, 16, 1, 64, 32);
+
+        const mat = new THREE.MeshStandardMaterial({
+            map: texture,
+            side: THREE.DoubleSide,
+            transparent: true,
+            alphaTest: 0.5
+        });
+
+        const mainMesh = new THREE.Mesh(geo, mat);
+        mainMesh.position.copy(meshOffset);
+        mainMesh.rotation.y = Math.PI;
+        mainMesh.userData.originalMat = mat;
+
+        pivotGroup.add(mainMesh);
+        this.bodyMeshes.push(mainMesh);
+
+        const capeLayers = [];
+        const shellGeo = geo.clone();
+
+        for (let i = 0; i < this.LAYERS_COUNT; i++) {
+            const glowMat = createGlowMaterial(size.h);
+
+            glowMat.uniforms.thickness.value = 0;
+            glowMat.uniforms.opacity.value = 0;
+            glowMat.polygonOffset = true;
+            glowMat.polygonOffsetFactor = i * 0.1;
+
+            const layerMesh = new THREE.Mesh(shellGeo, glowMat);
+
+            layerMesh.position.copy(meshOffset);
+            layerMesh.rotation.y = Math.PI;
+
+            layerMesh.userData.layerIndex = i;
+            layerMesh.userData.isGlow = true;
+            layerMesh.userData.glowMat = glowMat;
+
+            pivotGroup.add(layerMesh);
+            capeLayers.push(layerMesh);
+        }
+
+        this.glowMeshes.push(capeLayers);
+        pivotGroup.userData.glowLayers = capeLayers;
+
+        this.playerGroup.add(pivotGroup);
+        this.parts['cape'] = pivotGroup;
     }
 
     getGroup() { return this.playerGroup; }
 
-    updateBorderThickness(v) { const t = v * 0.05; this.glowMeshes.forEach(m => m.userData.glowMat.uniforms.thickness.value = t); }
-    updateGlowHeight(p) { this.glowMeshes.forEach(m => m.userData.glowMat.uniforms.gradientLimit.value = p); }
-    setGlowEffect(en) { this.glowMeshes.forEach(m => m.userData.glowMat.uniforms.opacity.value = en ? 1.0 : 0.0); }
+    /**
+     * Updates thickness creating a solid volume effect.
+     * @param {number} v - Base thickness value.
+     */
+    updateBorderThickness(v) {
+        const maxThickness = v * 0.05;
+
+        this.glowMeshes.forEach(layers => {
+            layers.forEach((mesh, i) => {
+                const progress = (i + 1) / this.LAYERS_COUNT;
+
+                mesh.userData.glowMat.uniforms.thickness.value = maxThickness * progress;
+            });
+        });
+    }
+
+    updateGlowHeight(p) {
+        this.glowMeshes.forEach(layers => {
+            layers.forEach(m => m.userData.glowMat.uniforms.gradientLimit.value = p);
+        });
+    }
+
+    setGlowEffect(en) {
+        this.glowMeshes.forEach(layers => {
+            layers.forEach((mesh, i) => {
+                if (!en) {
+                    mesh.userData.glowMat.uniforms.opacity.value = 0.0;
+                } else {
+                    mesh.userData.glowMat.uniforms.opacity.value = 1.0 / (this.LAYERS_COUNT * 0.6);
+                }
+            });
+        });
+    }
+
     darkenBody() { this.bodyMeshes.forEach(m => m.material = this.blackMaterial); }
     restoreBody() { this.bodyMeshes.forEach(m => m.material = m.userData.originalMat); }
 
@@ -117,8 +271,22 @@ export class SkinModel {
             part.rotation.set(0,0,0);
             if (this.defaultPositions[name]) part.position.copy(this.defaultPositions[name]);
         }
+
+        this.playerGroup.position.set(0, 0, 0);
+        this.playerGroup.rotation.set(0, 0, 0);
+        this.playerGroup.scale.set(1, 1, 1);
+
         if (!pose) return;
+
+        if (pose.root) {
+            if (pose.root.pos) this.playerGroup.position.fromArray(pose.root.pos);
+            if (pose.root.rot) this.playerGroup.rotation.fromArray(pose.root.rot);
+            if (pose.root.scl) this.playerGroup.scale.fromArray(pose.root.scl);
+        }
+
         for (const [name, data] of Object.entries(pose)) {
+            if (name === 'root') continue;
+
             if (this.parts[name]) {
                 if(data.rot) this.parts[name].rotation.set(...data.rot);
                 if(data.pos) this.parts[name].position.set(...data.pos);
@@ -129,9 +297,34 @@ export class SkinModel {
     getPose() {
         const pose = {};
         const f = (n) => parseFloat(n.toFixed(3));
+
         for (const [name, part] of Object.entries(this.parts)) {
-            pose[name] = { rot: [f(part.rotation.x), f(part.rotation.y), f(part.rotation.z)], pos: [f(part.position.x), f(part.position.y), f(part.position.z)] };
+            pose[name] = {
+                rot: [f(part.rotation.x), f(part.rotation.y), f(part.rotation.z)],
+                pos: [f(part.position.x), f(part.position.y), f(part.position.z)]
+            };
         }
+
+        pose.root = {
+            pos: [f(this.playerGroup.position.x), f(this.playerGroup.position.y), f(this.playerGroup.position.z)],
+            rot: [f(this.playerGroup.rotation.x), f(this.playerGroup.rotation.y), f(this.playerGroup.rotation.z)],
+            scl: [f(this.playerGroup.scale.x), f(this.playerGroup.scale.y), f(this.playerGroup.scale.z)]
+        };
+
         return pose;
     }
+
+    dispose() {
+        if (this.playerGroup) {
+            if (this.playerGroup.parent) {
+                this.playerGroup.parent.remove(this.playerGroup);
+            }
+            disposeObjectTree(this.playerGroup);
+        }
+
+        this.parts = {};
+        this.glowMeshes = [];
+        this.bodyMeshes = [];
+        this.playerGroup = null;
+    }
 }