bbmodel-viewer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Renard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# bbmodel-viewer
+
+Render and view [Blockbench](https://blockbench.net) `.bbmodel` files in the
+browser with [three.js](https://threejs.org). Drop a container element in,
+point it at a file (URL, `File`, or parsed object) and get an orbit-controlled
+3D preview — cubes **and** meshes, per-face UVs, textures, and the full bone
+(outliner) hierarchy with correct pivots and rotations.
+
+Built for exactly this kind of use case: **previewing model files stored on a
+drive / CDN** without opening Blockbench.
+
+## Features
+
+- ✅ Cube elements with per-face UVs, `inflate`, per-face UV rotation
+- ✅ Mesh (poly) elements (triangles + quads)
+- ✅ Embedded textures (`data:` sources) with crisp nearest-neighbour filtering
+- ✅ Full outliner hierarchy: groups/bones with pivots and `ZYX` Euler rotation
+- ✅ Transparent textures (alpha cutout)
+- ✅ Orbit / zoom / pan controls, optional auto-rotate and ground grid
+- ✅ Auto camera framing, container resize handling, clean `dispose()`
+- ✅ TypeScript types, ESM + CJS builds, three.js as a peer dependency
+
+## Install
+
+```bash
+npm install bbmodel-viewer three
+```
+
+`three` is a **peer dependency** (`>=0.150.0`) so your app controls the version.
+
+## Quick start
+
+```ts
+import { BBModelViewer } from "bbmodel-viewer";
+
+const container = document.getElementById("viewer")!; // give it a size in CSS
+const viewer = new BBModelViewer(container, {
+  background: "#20232a",
+  autoRotate: true,
+});
+
+await viewer.load("/models/creeper.bbmodel");
+```
+
+The container should have a non-zero size (e.g. `width: 100%; height: 480px`).
+The viewer fills it and follows resizes automatically.
+
+### From a file input or drag & drop (drive viewer)
+
+```ts
+input.addEventListener("change", (e) => {
+  const file = (e.target as HTMLInputElement).files?.[0];
+  if (file) viewer.loadFile(file);
+});
+```
+
+### From an already-parsed object
+
+```ts
+const data = await fetch(url).then((r) => r.json());
+await viewer.loadModel(data);
+```
+
+## Options
+
+All options are optional.
+
+| Option                  | Type                        | Default        | Description                                              |
+| ----------------------- | --------------------------- | -------------- | ------------------------------------------------------- |
+| `background`            | `string \| number \| null`  | `"#20232a"`    | Scene background. `null`/`"transparent"` for see-through |
+| `grid`                  | `boolean`                   | `true`         | Ground grid aligned to the model base                   |
+| `controls`              | `boolean`                   | `true`         | Orbit / zoom / pan                                      |
+| `autoRotate`            | `boolean`                   | `false`        | Spin the model                                          |
+| `autoRotateSpeed`       | `number`                    | `1.0`          | Spin speed                                              |
+| `fov`                   | `number`                    | `45`           | Camera field of view (degrees)                          |
+| `ambientIntensity`      | `number`                    | `0.8`          | Ambient light                                           |
+| `directionalIntensity`  | `number`                    | `0.55`         | Key light                                               |
+| `doubleSided`           | `boolean`                   | `true`         | Render both sides of every polygon                      |
+| `alphaTest`             | `number`                    | `0.02`         | Alpha cutoff for transparent texels                     |
+| `antialias`             | `boolean`                   | `true`         | MSAA                                                    |
+| `pixelRatio`            | `number`                    | `min(dpr, 2)`  | Device pixel ratio cap                                  |
+| `onLoad`                | `(model, object) => void`   | —              | Fires after a model is added to the scene               |
+| `onError`               | `(error) => void`           | —              | Fires on load/parse failure                             |
+
+## API
+
+```ts
+const viewer = new BBModelViewer(container, options);
+
+await viewer.load(url, init?);   // fetch + render a .bbmodel URL
+await viewer.loadFile(file);     // render a File/Blob
+await viewer.loadModel(data);    // render a parsed bbmodel object
+viewer.frameModel();             // re-frame the camera on the model
+viewer.resize();                 // re-measure the container (also automatic)
+viewer.clear();                  // remove the model + free GPU memory
+viewer.dispose();                // tear everything down
+
+// Escape hatches for advanced use:
+viewer.scene;      // THREE.Scene
+viewer.camera;     // THREE.PerspectiveCamera
+viewer.renderer;   // THREE.WebGLRenderer
+viewer.controls;   // OrbitControls | undefined
+```
+
+### Lower-level building blocks
+
+If you just want the geometry (e.g. to drop into your own scene):
+
+```ts
+import { MaterialLibrary, buildModelObject } from "bbmodel-viewer";
+
+const materials = new MaterialLibrary(model, { alphaTest: 0.02, side: THREE.DoubleSide });
+await materials.load();
+const object3d = buildModelObject(model, materials); // THREE.Group
+myScene.add(object3d);
+```
+
+## Coordinate system & conventions
+
+- Units are Blockbench units (16 = one Minecraft block); the grid draws one cell
+  per block.
+- Rotations use Euler order `ZYX` (matching Blockbench's `Rz·Ry·Rx`).
+- Per-face UVs are read as `[u_min, v_min, u_max, v_max]` in texture pixels and
+  normalized by each texture's `uv_width`/`uv_height` (falling back to the
+  project `resolution`).
+- Textures use `NearestFilter` and no mipmaps for pixel-perfect art.
+
+## Notes & limitations
+
+- **Animations** are not played yet (static pose only). The bone hierarchy is
+  built, so this is a planned addition.
+- **`box_uv`**: files store computed per-face UVs, which are used directly; a
+  best-effort standard unwrap is used only if a face's `uv` is missing.
+- Cross-origin textures/URLs need appropriate CORS headers when loaded from a
+  remote drive.
+
+## Development
+
+```bash
+npm install
+npm run build       # bundle to dist/ (ESM + CJS + d.ts)
+npm run typecheck
+npm run example     # serve examples/ with Vite
+```
+
+## License
+
+MIT