bucciafico-lib 1.0.4-BETA

package/README.md

@@ -0,0 +1,178 @@
+# Bucciafico Lib
+
+bucciafico-lib is a framework-agnostic 3D rendering engine built on top of Three.js. It is designed
+specifically for visualizing, posing, and manipulating Minecraft character skins and items.
+The library features a custom rendering pipeline that includes voxelized outer layers for skins, shader-based glow
+effects, post-processing (bloom, outline), and a robust undo/redo history system for editor implementations.
+
+The library utilizes a plugin-based architecture, allowing developers to include only the necessary features (e.g., just the viewer core) or extend it with a full suite of editing tools, post-processing effects, and item management.
+## Features
+
+The repository is organized into the following workspaces:
+
+- **Advanced Skin Rendering:** Automatically detects Classic (Steve) and Slim (Alex) models.
+- **Voxelized Outer Layers:** The second layer of the skin (hat, jacket, sleeves) is generated as 3D voxels rather than
+  flat planes, providing depth and realism.
+- **Custom Shader Effects:** Includes a specialized shader for creating inner-body glow/backlight effects with
+  configurable gradient, strength, and blur.
+- **Item Extrusion:** Procedurally generates 3D meshes from 2D item textures.
+- **Post-Processing Pipeline:** Integrated UnrealBloom and Outline passes for high-quality visuals and object selection
+  highlighting.
+- **Editor Tools:** Built-in support for Gizmo controls (Translate, Rotate, Scale), Raycasting, and History management (
+  Undo/Redo).
+- **High-Resolution Export:** Capable of rendering high-resolution, transparent PNG screenshots independent of the
+  canvas viewport size.
+
+## Installation
+
+The library relies on `three` as a peer dependency.
+
+```bash
+npm install three
+npm install bucciafico-lib
+```
+
+## Usage
+
+### Basic Initialization
+If you only need to display a character without interaction or advanced effects:
+
+```javascript
+import { SkinViewer } from 'bucciafico-lib';
+
+const container = document.getElementById('viewer-container');
+
+// Initialize Core
+const viewer = new SkinViewer(container, {
+    showGrid: true,
+    transparent: true,
+    cameraEnabled: true
+});
+
+// Load Skin
+viewer.loadSkinByUsername('HappyGFX');
+```
+
+### Full Editor Setup
+To enable Gizmos, Glow effects, and Item management, register the respective plugins.
+
+```javascript
+import { SkinViewer, EditorPlugin, EffectsPlugin, ItemsPlugin } from 'bucciafico-lib';
+
+const viewer = new SkinViewer(document.getElementById('app'));
+
+// Initialize Plugins
+const editor = new EditorPlugin();
+const effects = new EffectsPlugin();
+const items = new ItemsPlugin();
+const io = new IOPlugin();
+
+// Register Plugins
+viewer.addPlugin(editor);
+viewer.addPlugin(effects);
+viewer.addPlugin(items);
+viewer.addPlugin(io);
+
+// Load Skin
+viewer.loadSkinByUsername('Notch');
+```
+
+### Configuration Options
+
+The `SkinViewer` constructor accepts a configuration object:
+
+| Option          | Type    | Default    | Description                                                   |
+|-----------------|---------|------------|---------------------------------------------------------------|
+| `showGrid`      | boolean | `true`     | Toggles the visibility of the ground grid helper.             |
+| `transparent`   | boolean | `false`    | If true, the canvas background is transparent (alpha 0).      |
+| `bgColor`       | number  | `0x141417` | Hex color of the background if transparency is disabled.      |
+| `cameraEnabled` | boolean | `true`     | Enables or disables mouse interaction with the camera.        |
+
+## API Reference
+
+### Skin Loading
+```javascript
+// Load skin from URL (returns Promise<boolean> isSlim)
+viewer.loadSkin('path/to/skin.png');
+
+// Load by Username
+viewer.loadSkinByUsername('Notch');
+
+// Set Pose (Rotation in radians)
+viewer.setPose({
+    head: { rot: [0.2, 0, 0] },
+    leftArm: { rot: [-0.5, 0, 0] }
+});
+
+// Get Plugin Instance
+const editor = viewer.getPlugin('EditorPlugin');
+```
+
+### Editor
+```javascript
+const editor = viewer.getPlugin('EditorPlugin');
+
+// Change Gizmo Mode
+editor.setTransformMode('rotate'); // 'translate', 'rotate', 'scale'
+
+// Selection
+editor.deselect(); // Clear selection
+
+// History
+editor.undo();
+editor.redo();
+```
+
+### Effects
+```javascript
+const fx = viewer.getPlugin('EffectsPlugin');
+
+// Configure Glow
+fx.updateConfig({
+    enabled: true,
+    strength: 1.5, // Bloom intensity
+    radius: 0.4,   // Bloom radius
+    height: 0.5,   // Gradient height (0.0 - 1.0)
+    thickness: 4   // Glow thickness
+});
+
+// Capture Screenshot (Transparent PNG)
+const dataUrl = fx.captureScreenshot(1920, 1080);
+```
+
+### Items
+```javascript
+const items = viewer.getPlugin('ItemsPlugin');
+
+// Add Item
+items.addItem('path/to/sword.png', 'Diamond Sword').then(mesh => {
+    console.log('Item added');
+});
+
+// Remove Item
+items.removeItem(meshObject);
+```
+
+### IOPlugin
+```javascript
+const io = viewer.getPlugin('IOPlugin');
+
+// Export State
+// You can filter what to export using options
+const jsonState = io.exportState({
+    skin: true,
+    camera: true,
+    effects: true,
+    pose: true,
+    items: true
+});
+
+// Import State (Async)
+io.importState(jsonState).then(() => {
+    console.log('Scene restored');
+});
+```
+
+
+## License
+MIT License

package/index.js

@@ -0,0 +1,5 @@
+export { SkinViewer } from './src/core/SkinViewer.js';
+export { EditorPlugin } from './src/plugins/EditorPlugin.js';
+export { EffectsPlugin } from './src/plugins/EffectsPlugin.js';
+export { ItemsPlugin } from './src/plugins/ItemsPlugin.js';
+export { IOPlugin } from './src/plugins/IOPlugin.js';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "bucciafico-lib",
+  "version": "1.0.4-BETA",
+  "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

@@ -0,0 +1,195 @@
+import * as THREE from 'three';
+import { CameraManager } from '../managers/CameraManager.js';
+import { SceneSetup } from '../objects/SceneSetup.js';
+import { SkinModel } from '../objects/SkinModel.js';
+import { detectSlimSkin } from '../utils/SkinUtils.js';
+
+/**
+ * Core 3D Viewer class.
+ * Lightweight, modular engine that handles the basic Three.js scene, camera, and character model.
+ * Extended functionality (Editor, Effects, Items) is added via Plugins.
+ */
+export class SkinViewer {
+    /**
+     * @param {HTMLElement} containerElement - The DOM element to attach the canvas to.
+     * @param {Object} [config] - Basic configuration.
+     * @param {boolean} [config.showGrid=true] - Visibility of the floor grid.
+     * @param {boolean} [config.transparent=false] - Background transparency.
+     * @param {number} [config.bgColor=0x141417] - Background hex color.
+     * @param {boolean} [config.cameraEnabled=true] - OrbitControls state.
+     */
+    constructor(containerElement, config = {}) {
+        this.container = containerElement;
+        this.config = {
+            showGrid: config.showGrid ?? true,
+            transparent: config.transparent ?? false,
+            bgColor: config.bgColor ?? 0x141417,
+            cameraEnabled: config.cameraEnabled ?? true,
+            ...config
+        };
+
+        /** @type {Map<string, Object>} Registered plugins. */
+        this.plugins = new Map();
+
+        /** @type {boolean} Flag to stop the animation loop. */
+        this.isDisposed = false;
+
+        // --- 1. RENDERER SETUP ---
+        this.renderer = new THREE.WebGLRenderer({
+            antialias: true,
+            alpha: this.config.transparent,
+            preserveDrawingBuffer: true
+        });
+
+        const w = this.container.clientWidth;
+        const h = this.container.clientHeight;
+
+        this.renderer.setSize(w, h);
+        this.renderer.setPixelRatio(window.devicePixelRatio);
+        this.renderer.outputColorSpace = THREE.SRGBColorSpace;
+        this.renderer.autoClear = false; // Required for post-processing plugins
+
+        this.container.appendChild(this.renderer.domElement);
+
+        // --- 2. SCENE SETUP ---
+        this.scene = new THREE.Scene();
+        if (!this.config.transparent) {
+            this.scene.background = new THREE.Color(this.config.bgColor);
+        }
+
+        this.overlayScene = new THREE.Scene();
+
+        this.sceneSetup = new SceneSetup(this.scene);
+        this.sceneSetup.setGridVisible(this.config.showGrid);
+
+        this.cameraManager = new CameraManager(this.renderer.domElement, w, h);
+        this.cameraManager.setEnabled(this.config.cameraEnabled);
+
+        this.skinModel = new SkinModel();
+        this.scene.add(this.skinModel.getGroup());
+
+        // --- 3. START LOOP ---
+        this.animate = this.animate.bind(this);
+        this.animate();
+    }
+
+    /**
+     * Registers and initializes a plugin.
+     * @param {Object} plugin - The plugin instance (must have an init() method).
+     * @returns {Object} The registered plugin instance.
+     */
+    addPlugin(plugin) {
+        const name = plugin.constructor.name;
+        if (this.plugins.has(name)) return this.plugins.get(name);
+
+        if (plugin.init) plugin.init(this);
+        this.plugins.set(name, plugin);
+
+        return plugin;
+    }
+
+    /**
+     * Retrieves a registered plugin by class name.
+     * @param {string} name - e.g., 'EditorPlugin', 'EffectsPlugin'.
+     * @returns {Object|undefined}
+     */
+    getPlugin(name) {
+        return this.plugins.get(name);
+    }
+
+    /**
+     * Loads a skin from URL.
+     * @param {string} imageUrl
+     * @returns {Promise<boolean>} isSlim
+     */
+    loadSkin(imageUrl) {
+        return new Promise((resolve, reject) => {
+            new THREE.TextureLoader().load(imageUrl, (texture) => {
+                texture.magFilter = THREE.NearestFilter;
+                texture.colorSpace = THREE.SRGBColorSpace;
+
+                const currentPose = this.skinModel.getPose();
+                const isSlim = detectSlimSkin(texture.image);
+
+                const editor = this.getPlugin('EditorPlugin');
+                if (editor) editor.deselect();
+
+                this.skinModel.build(texture, isSlim);
+                this.skinModel.setPose(currentPose);
+                this.skinData = { type: 'url', value: imageUrl };
+
+                resolve(isSlim);
+            }, undefined, reject);
+        });
+    }
+
+    loadSkinByUsername(username) {
+        this.skinData = { type: 'username', value: username };
+        const url = `https://minotar.net/skin/${username}.png?v=${Date.now()}`;
+
+        return this.loadSkin(url).then(res => {
+            this.skinData = { type: 'username', value: username };
+            return res;
+        });
+    }
+
+    setPose(poseData) {
+        // Record history if Editor is present
+        const editor = this.getPlugin('EditorPlugin');
+        if (editor) editor.saveHistory();
+
+        this.skinModel.setPose(poseData);
+    }
+
+    /**
+     * Handles window resize. Should be called by the implementation layer.
+     */
+    onResize() {
+        if (!this.container) return;
+        const w = this.container.clientWidth;
+        const h = this.container.clientHeight;
+
+        this.cameraManager.onResize(w, h);
+        this.renderer.setSize(w, h);
+
+        // Notify all plugins
+        this.plugins.forEach(p => {
+            if (p.onResize) p.onResize(w, h);
+        });
+    }
+
+    animate() {
+        if (this.isDisposed) return;
+        requestAnimationFrame(this.animate);
+
+        this.cameraManager.update();
+
+        const effects = this.getPlugin('EffectsPlugin');
+
+        if (effects) {
+            effects.render();
+        } else {
+            this.renderer.clear();
+            this.renderer.render(this.scene, this.cameraManager.camera);
+        }
+
+        this.renderer.clearDepth();
+        this.renderer.render(this.overlayScene, this.cameraManager.camera);
+    }
+
+    dispose() {
+        this.isDisposed = true;
+
+        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();
+    }
+}

package/src/managers/CameraManager.js

@@ -0,0 +1,52 @@
+import * as THREE from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+
+/**
+ * Wraps Three.js Camera and OrbitControls.
+ */
+export class CameraManager {
+    constructor(domElement, width, height) {
+        this.defaultFOV = 45;
+        this.defaultPosition = new THREE.Vector3(20, 10, 40);
+        this.defaultTarget = new THREE.Vector3(0, 0, 0);
+
+        this.camera = new THREE.PerspectiveCamera(this.defaultFOV, width / height, 0.1, 1000);
+        this.camera.position.copy(this.defaultPosition);
+
+        this.controls = new OrbitControls(this.camera, domElement);
+        this.controls.enableDamping = true;
+        this.controls.dampingFactor = 0.05;
+        this.controls.target.copy(this.defaultTarget);
+    }
+
+    update() { this.controls.update(); }
+    onResize(width, height) { this.camera.aspect = width / height; this.camera.updateProjectionMatrix(); }
+    setFOV(value) { this.camera.fov = value; this.camera.updateProjectionMatrix(); }
+    setDistance(distance) {
+        const direction = new THREE.Vector3().subVectors(this.camera.position, this.controls.target).normalize();
+        this.camera.position.copy(this.controls.target).add(direction.multiplyScalar(distance));
+    }
+    setEnabled(enabled) { this.controls.enabled = enabled; }
+    reset() {
+        this.setFOV(this.defaultFOV);
+        this.camera.position.copy(this.defaultPosition);
+        this.controls.target.copy(this.defaultTarget);
+        this.controls.update();
+    }
+    getSettingsJSON() {
+        const r = (val) => parseFloat(val.toFixed(3));
+        const rVec = (v) => [r(v.x), r(v.y), r(v.z)];
+        return {
+            fov: this.camera.fov,
+            zoom: r(this.camera.position.distanceTo(this.controls.target)),
+            position: rVec(this.camera.position),
+            target: rVec(this.controls.target)
+        };
+    }
+    loadSettingsJSON(data) {
+        if (data.fov) { this.camera.fov = data.fov; this.camera.updateProjectionMatrix(); }
+        if (data.position) this.camera.position.fromArray(data.position);
+        if (data.target) this.controls.target.fromArray(data.target);
+        this.controls.update();
+    }
+}

package/src/managers/HistoryManager.js

@@ -0,0 +1,65 @@
+/**
+ * Manages the Undo/Redo stack for the editor.
+ * Handles state snapshots including poses and item transformations.
+ */
+export class HistoryManager {
+    /**
+     * @param {Function} applyStateCallback - Function to call when a state needs to be restored.
+     */
+    constructor(applyStateCallback) {
+        this.undoStack = [];
+        this.redoStack = [];
+        this.applyState = applyStateCallback;
+        this.maxHistory = 50;
+    }
+
+    /**
+     * Pushes a new state snapshot to the history stack.
+     * Clears the Redo stack as a new timeline is created.
+     * @param {Object} state - The snapshot object.
+     */
+    pushState(state) {
+        this.redoStack = [];
+        const stateStr = JSON.stringify(state);
+
+        // Don't save if state hasn't changed
+        if (this.undoStack.length > 0 && this.undoStack[this.undoStack.length - 1] === stateStr) {
+            return;
+        }
+
+        this.undoStack.push(stateStr);
+        if (this.undoStack.length > this.maxHistory) {
+            this.undoStack.shift();
+        }
+    }
+
+    /**
+     * Reverts to the previous state.
+     * @param {Object} currentState - The current state (to save into Redo before undoing).
+     */
+    undo(currentState) {
+        if (this.undoStack.length === 0) return;
+
+        this.redoStack.push(JSON.stringify(currentState));
+        const prevStateStr = this.undoStack.pop();
+
+        if (prevStateStr) {
+            this.applyState(JSON.parse(prevStateStr));
+        }
+    }
+
+    /**
+     * Reapplies a previously undone state.
+     * @param {Object} currentState - The current state (to save into Undo before redoing).
+     */
+    redo(currentState) {
+        if (this.redoStack.length === 0) return;
+
+        this.undoStack.push(JSON.stringify(currentState));
+        const nextStateStr = this.redoStack.pop();
+
+        if (nextStateStr) {
+            this.applyState(JSON.parse(nextStateStr));
+        }
+    }
+}

package/src/managers/PostProcessingManager.js

@@ -0,0 +1,107 @@
+import * as THREE from 'three';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass.js';
+import { ShaderPass } from 'three/examples/jsm/postprocessing/ShaderPass.js';
+import { UnrealBloomPass } from 'three/examples/jsm/postprocessing/UnrealBloomPass.js';
+import { OutputPass } from 'three/examples/jsm/postprocessing/OutputPass.js';
+import { OutlinePass } from 'three/examples/jsm/postprocessing/OutlinePass.js';
+
+/**
+ * Handles the post-processing pipeline (Bloom, Outline, Color Correction).
+ */
+export class PostProcessingManager {
+    constructor(renderer, scene, camera, width, height) {
+        this.scene = scene;
+
+        // 1. BLOOM COMPOSER (Renders glow map)
+        this.bloomComposer = new EffectComposer(renderer);
+        this.bloomComposer.renderToScreen = false;
+        this.bloomComposer.addPass(new RenderPass(scene, camera));
+
+        this.bloomPass = new UnrealBloomPass(new THREE.Vector2(width, height), 1.5, 0.4, 0.0);
+        this.bloomComposer.addPass(this.bloomPass);
+
+        // 2. FINAL COMPOSER
+        this.finalComposer = new EffectComposer(renderer);
+        this.finalComposer.addPass(new RenderPass(scene, camera));
+
+        // 3. OUTLINE PASS (Selection highlight)
+        this.outlinePass = new OutlinePass(new THREE.Vector2(width, height), scene, camera);
+        this.outlinePass.edgeStrength = 3.0;
+        this.outlinePass.visibleEdgeColor.set('#ffffff');
+        this.outlinePass.hiddenEdgeColor.set('#ffffff');
+        this.finalComposer.addPass(this.outlinePass);
+
+        // 4. MIX SHADER (Combines Base + Bloom preserving Alpha)
+        const MixShader = {
+            uniforms: {
+                tDiffuse: { value: null },
+                bloomTexture: { value: null }
+            },
+            vertexShader: `
+                varying vec2 vUv;
+                void main() {
+                    vUv = uv;
+                    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+                }
+            `,
+            fragmentShader: `
+                uniform sampler2D tDiffuse;
+                uniform sampler2D bloomTexture;
+                varying vec2 vUv;
+                void main() {
+                    vec4 baseColor = texture2D(tDiffuse, vUv);
+                    vec4 bloomColor = texture2D(bloomTexture, vUv);
+                    
+                    // Add only colors (RGB), keep the Base Alpha.
+                    // This prevents the black background of the bloom pass from overwriting transparency.
+                    gl_FragColor = vec4(baseColor.rgb + (bloomColor.rgb * 2.5), baseColor.a);
+                }
+            `
+        };
+
+        this.mixPass = new ShaderPass(MixShader);
+        this.mixPass.needsSwap = true;
+        this.finalComposer.addPass(this.mixPass);
+
+        // 5. OUTPUT PASS (sRGB correction)
+        this.finalComposer.addPass(new OutputPass());
+    }
+
+    resize(width, height) {
+        this.bloomComposer.setSize(width, height);
+        this.finalComposer.setSize(width, height);
+        this.bloomPass.resolution.set(width, height);
+        this.outlinePass.setSize(width, height);
+    }
+
+    /**
+     * Renders the scene in two passes to achieve the glow effect on specific objects only.
+     * @param {Function} prepareBloomCb - Callback to hide non-glowing objects.
+     * @param {Function} restoreSceneCb - Callback to restore visibility.
+     */
+    renderSelective(prepareBloomCb, restoreSceneCb) {
+        const prevBg = this.scene.background;
+        this.scene.background = new THREE.Color(0x000000);
+        this.outlinePass.enabled = false;
+
+        prepareBloomCb();
+        this.bloomComposer.render();
+        restoreSceneCb();
+
+        this.scene.background = prevBg;
+        this.outlinePass.enabled = true;
+        this.mixPass.uniforms.bloomTexture.value = this.bloomComposer.readBuffer.texture;
+        this.finalComposer.render();
+    }
+
+    setSelected(obj) {
+        this.outlinePass.selectedObjects = obj ? [obj] : [];
+    }
+
+    setBloom(en, str, rad, thr) {
+        this.bloomPass.strength = en ? Number(str) : 0;
+        this.bloomPass.radius = Number(rad);
+        this.bloomPass.threshold = Number(thr);
+    }
+}

package/src/materials/GlowMaterial.js

@@ -0,0 +1,56 @@
+import * as THREE from 'three';
+
+const vertexShader = `
+    uniform float thickness;
+    varying float vY;
+    varying vec3 vNormal;
+    void main() {
+        vNormal = normal;
+        // Extrude vertex along normal
+        vec3 newPos = position + normal * thickness;
+        vY = position.y;
+        gl_Position = projectionMatrix * modelViewMatrix * vec4(newPos, 1.0);
+    }
+`;
+
+const fragmentShader = `
+    uniform float opacity;
+    uniform float gradientLimit;
+    uniform float partHeight;
+    varying float vY;
+    varying vec3 vNormal;
+    void main() {
+        if (opacity <= 0.01) discard;
+        // Discard bottom faces to avoid "floor" artifact
+        if (vNormal.y < -0.9) discard;
+        
+        // Gradient logic
+        float normalizedY = (vY + (partHeight / 2.0)) / partHeight;
+        float alpha = smoothstep(1.0 - gradientLimit, 1.0, normalizedY);
+        alpha *= smoothstep(0.0, 0.2, normalizedY);
+        
+        gl_FragColor = vec4(1.0, 1.0, 1.0, alpha * opacity);
+    }
+`;
+
+/**
+ * Creates a ShaderMaterial for the glow effect.
+ * It renders a larger, back-side version of the mesh with an opacity gradient.
+ * @param {number} partHeight - Height of the body part for gradient calculation.
+ */
+export function createGlowMaterial(partHeight) {
+    return new THREE.ShaderMaterial({
+        uniforms: {
+            opacity: { value: 0.0 },
+            gradientLimit: { value: 0.8 },
+            thickness: { value: 0.0 },
+            partHeight: { value: partHeight }
+        },
+        vertexShader,
+        fragmentShader,
+        transparent: true,
+        side: THREE.BackSide, // Render inside of the extruded box
+        depthWrite: false,
+        blending: THREE.AdditiveBlending
+    });
+}