=== 3D Product Customizer === Contributors: deosebitsoft Tags: woocommerce, 3d, product customizer, configurator, three.js Requires at least: 6.0 Tested up to: 6.9 Requires PHP: 7.4 Stable tag: 3.3 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html An interactive Three.js-powered 3D product configurator for WooCommerce — let customers customize materials, textures, and geometry in real time. == Description == 3D Product Customizer adds a fully interactive 3D configurator to your WooCommerce product pages. Customers can rotate the model, swap materials, show or hide parts, and add the configured product directly to their cart. **Key features:** * Real-time 3D model viewer powered by Three.js (WebGL) * PBR (Physically Based Rendering) material support — base color, roughness, normal, AO, metalness, and displacement maps * Per-step customization: define multiple configuration steps (e.g. Upper, Sole, Logo), each targeting specific model meshes * Bulk material assignment in the admin * Geometry visibility toggles — show or hide mesh groups per option * Undo / redo history * URL-based configuration sharing — customers can share their exact design via a link * Download a PDF preview * AR view on supported mobile devices * HDR environment map for realistic lighting * Background color switcher * Customization data saved to the WooCommerce order as line-item meta * Reusable texture library via a dedicated Custom Post Type == Source Code & Build Instructions == **All source code is human-readable and included in this plugin.** The `/js/` folder contains the original, uncompiled JavaScript source files: * `customizer.js` — Main 3D configurator frontend logic * `model-scanner.js` — 3D model mesh detection and analysis * `material-preview.js` — Material preview rendering * `ui.js` — UI state management and interactions * Admin scripts in `/admin/js/` — Dashboard-specific functionality The `/dist/` folder contains pre-compiled, production-ready bundles. These are generated by bundling the source files with their dependencies (three.js, pdf-lib, lucide) using Webpack. **The `/dist/` folder is auto-generated output and not part of the source code.** **Rebuilding from Source:** This plugin uses Webpack to compile and minify JavaScript, bundling dependencies to keep the plugin size manageable (avoiding the need to distribute `node_modules`). Requirements: * Node.js (v14 or newer) * npm (included with Node.js) Build commands: ``` npm install # Install dependencies from package.json npm run dev # Development build with watch mode (rebuilds on file changes) npm run build # Production build (minified and optimized) ``` **Dependencies:** * **three.js** — WebGL 3D rendering library (licensed under MIT) * **pdf-lib** — PDF generation for preview downloads (licensed under Apache 2.0) * **lucide** — Icon library (licensed under MIT) * **webpack** — Module bundler (licensed under MIT) All original code is GPLv2 or later. Third-party dependencies follow their respective open-source licenses, listed in `package.json`. == External Services == This plugin integrates with **Freemius** for license management, automatic updates, and premium feature delivery: * **Service:** Freemius License Management * **Server:** https://freemius.com * **Purpose:** Validates premium licenses, manages plugin updates, delivers premium features, and provides usage analytics * **Data Sent:** Plugin activation events, license key validation, and anonymized usage analytics * **Account Required:** Optional — only if upgrading to Premium * **Terms:** https://freemius.com/terms/ All other assets (JavaScript, CSS, images) are included locally within the plugin package. No other external services are used. **Free vs Premium:** The free version is fully functional for single-material customization. Premium unlocks advanced PBR workflows and productivity features for studios managing large product catalogs. | Feature | Free | Premium | | --- | --- | --- | | Upload & display a 3D model | ✓ | ✓ | | Base color texture or color picker per option | ✓ | ✓ | | Roughness & metalness sliders | ✓ | ✓ | | Customization steps | ✓ | ✓ | | Viewer Only Mode | ✓ | ✓ | | Camera, zoom & background settings | ✓ | ✓ | | HDR environment map | ✓ | ✓ | | Undo / redo, PDF, AR view | ✓ | ✓ | | Material Preview | - | ✓ | | Multiple textures per option | — | ✓ | | Bulk Add Materials to a step | — | ✓ | | Show / Hide mesh controls per option | — | ✓ | | Normal, AO, metalness & displacement maps | — | ✓ | | Reflection intensity & displacement scale | — | ✓ | | Hotstops/Annotations | - | ✓ | == Upgrade to Premium == 1. Inside WordPress admin, go to **3D Customizer → Account** (added after activation). 2. Click **Upgrade to Premium** and complete the purchase on the checkout page. 3. Return to **3D Customizer → Account/Upgrade** and enter your license key to activate. 4. Premium features unlock immediately — no plugin re-install required. Alternatively, click the **Upgrade to Premium** button that appears inside any locked premium feature panel. == Authors & Credits == **Development**: deosebIT Soft (https://deosebitsoft.ro/) This plugin was developed with attention to WordPress.org standards and is maintained by the deosebIT Soft team. For support, updates, and premium features, visit our website. == Installation == 1. Upload the `product-customizer` folder to `/wp-content/plugins/`. 2. Activate the plugin through the **Plugins** menu in WordPress. 3. Ensure WooCommerce is installed and active. 4. Navigate to **Model Textures** in the WordPress admin and create texture entries. Each texture can include a base-color image (featured image) plus optional PBR maps and scalar material properties. 5. Open any WooCommerce product and locate the **3D Configurator** metabox. 6. Upload or select a `.glb` / `.gltf` model using the **Select Model** button. 7. Click **Scan Model** to auto-detect mesh names from the file. 8. Add one or more **Steps** and assign **Options** (textures or geometry toggles) to each step. 9. Save the product. The 3D configurator will now appear on the product's front-end page. 10. Visit **Model Textures → Global Settings** to configure camera position, zoom limits, background colors, and an optional HDR environment map. == Frequently Asked Questions == = What 3D file formats are supported? = GLB (binary GLTF) is the recommended format. GLTF (JSON-based) is also supported. The plugin registers these MIME types with WordPress so they can be uploaded through the standard Media Library. = Can I use multiple HDR environment maps per product? = The HDR environment map is a global setting. All products share the same HDR file. Per-product HDR support is planned for a future release. = Why does the 3D viewer not appear on a product page? = The configurator only renders when the product has a valid `.glb` model URL AND at least one configured step with at least one option. Check the **3D Configurator** metabox on the product. = How is the customization saved to the order? = When a customer clicks **Add to cart**, the current configuration is sent as a JSON payload. Each selected option (part → material name) is stored as a WooCommerce line-item meta entry and is visible on the order detail and in emails. = Is this compatible with WooCommerce variable products? = The plugin targets simple products. Variable product support is not officially tested. = Are the bundled JavaScript files minified? = Yes. The source files are included in the `js/` directory and the `webpack.config.js` build configuration is included in the plugin package. == Screenshots == 1. Front-end 3D configurator on a WooCommerce product page — rotate the model and switch materials in real time. 2. Product metabox in the WordPress admin — add steps, assign texture options, and target specific meshes. 3. Texture modal — browse the reusable texture library and assign materials to a step option. 4. Model Texture editor — upload base color and PBR maps (roughness, normal, AO, metalness), set roughness and metalness sliders. 5. Global Settings page — configure initial camera position, zoom range, background colors, and HDR environment map. == Changelog == = 3.3 = * Fixed premium notice css * Added auto framing to the customizer * Updated admin model scanner layout = 3.2 = * Introduced Material preview metabox for Premium * Introduced color picker for materials with only basic colors = 3.0 = * Introduced Free vs Premium tier via Freemius licensing. * Premium: multiple textures per option (free tier limited to one per option). * Premium: Bulk Add Materials button in the product metabox. * Premium: Show/Hide mesh controls per customization option. * Premium: full PBR map set — normal, AO, metalness, and displacement map uploads. * Premium: reflection intensity and displacement scale sliders on texture entries. * Added custom isometric cube icon in the WordPress admin sidebar. * Added persistent upgrade prompts comparing free and premium features. * Freemius account menu integrated into the 3D Customizer admin menu. = 2.1 = * Added glass/transmission material support. * Added bulk material assignment in the product metabox. * Added drag-to-reorder for steps and options. * Added geometry visibility (show/hide meshes) per option. * Improved undo/redo history system. * Performance: texture list now cached with a transient. * Security: fixed text domain inconsistency across all files. * Security: attachment IDs now sanitized with absint() instead of sanitize_text_field(). * Security: ABSPATH guard moved to top of plugin-settings.php. * Security: all HTML attribute echoes in settings render callbacks now escaped with esc_attr(). = 2.0 = * Multi-texture options: assign multiple textures to a single option card. * New step/option data structure with explicit target meshes. * Added HDR environment map setting. * Added URL-based configuration sharing. * Added AR export with QR code. = 1.0 = * Initial release. == Upgrade Notice == = 3.2 = Introduces meterial preview (premium) and color picker for materials with only a basic color = 3.0 = Introduces the Free/Premium tier. Existing installs retain all previously available features. Premium features require a license key activated via 3D Customizer → Account/Upgrade. = 2.1 = Security and stability fixes. Update recommended for all users.