@objectifthunes/three-book 0.1.2 → 0.1.3

package/README.md

@@ -1,15 +1,24 @@
 # @objectifthunes/three-book
 
-Procedural, interactive 3D book component for Three.js.
+A procedural, interactive 3D book for [Three.js](https://threejs.org/) — drag pages to turn them, apply textures to every surface, and drop the whole thing into your scene as a regular `THREE.Group`.
+
+<p align="center">
+  <img src="../../docs/images/default.png" width="49%" alt="Closed book" />
+  <img src="../../docs/images/open-half.png" width="49%" alt="Book opened halfway" />
+</p>
+<p align="center">
+  <img src="../../docs/images/page-curl.png" width="49%" alt="Page mid-curl" />
+  <img src="../../docs/images/demo-ui.png" width="49%" alt="Demo app with tweakable controls" />
+</p>
 
 ## Features
 
-- Real-time page turning (drag with ray input).
-- Auto-turn support (programmatic page turns).
-- Covers + inner pages content model.
-- Configurable paper/cover geometry (size, thickness, stiffness, quality).
-- Book binding implementation (`StapleBookBinding`) included.
-- Works as a regular `THREE.Group` in your scene graph.
+- **Drag-to-turn pages** — raycaster-based interaction, works with mouse or touch.
+- **Programmatic page turns** — auto-turn API for scripted animations.
+- **Per-surface textures** — assign a `THREE.Texture` (or `null`) to each cover side and page side independently.
+- **Configurable geometry** — page/cover width, height, thickness, stiffness, color.
+- **Built-in binding** — `StapleBookBinding` handles spine positioning out of the box.
+- **Standard scene-graph citizen** — `Book` extends `THREE.Group`; add it, transform it, remove it like anything else.
 
 ## Installation
 
@@ -23,6 +32,8 @@ or
 pnpm add @objectifthunes/three-book three
 ```
 
+Peer dependency: `three >= 0.150.0` (ESM).
+
 ## Quick Start
 
 ```ts
@@ -34,6 +45,7 @@ import {
   StapleBookBinding,
 } from '@objectifthunes/three-book';
 
+// 1. Set up your scene as usual
 const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 100);
 camera.position.set(0, 4, 5);
@@ -42,21 +54,40 @@ const renderer = new THREE.WebGLRenderer({ antialias: true });
 renderer.setSize(innerWidth, innerHeight);
 document.body.appendChild(renderer.domElement);
 
+// 2. Describe the book's content
 const content = new BookContent();
 content.direction = BookDirection.LeftToRight;
 content.covers.push(frontOuterTex, frontInnerTex, backInnerTex, backOuterTex);
 content.pages.push(page1Tex, page2Tex, page3Tex, page4Tex);
 
+// 3. Create the book
 const book = new Book({
   content,
   binding: new StapleBookBinding(),
   castShadows: true,
   alignToGround: true,
+  pagePaperSetup: {
+    width: 2,
+    height: 3,
+    thickness: 0.02,
+    stiffness: 0.2,
+    color: new THREE.Color(1, 1, 1),
+    material: null,
+  },
+  coverPaperSetup: {
+    width: 2.1,
+    height: 3.1,
+    thickness: 0.04,
+    stiffness: 0.5,
+    color: new THREE.Color(1, 1, 1),
+    material: null,
+  },
 });
 
 book.init();
 scene.add(book);
 
+// 4. Update every frame
 const clock = new THREE.Clock();
 function animate() {
   requestAnimationFrame(animate);
@@ -66,17 +97,19 @@ function animate() {
 animate();
 ```
 
-## Input / Page Dragging
+## Page Dragging
 
-Use your own ray source (`THREE.Raycaster` + pointer coords), then:
+Wire up your own pointer/raycaster, then call three methods:
 
 ```ts
-book.startTurning(ray);   // on pointer down
-book.updateTurning(ray);  // on pointer move
-book.stopTurning();       // on pointer up
+book.startTurning(ray);   // pointer down
+book.updateTurning(ray);  // pointer move
+book.stopTurning();       // pointer up
 ```
 
-## Auto Turning
+## Auto Turn
+
+Turn pages programmatically:
 
 ```ts
 import { AutoTurnDirection, AutoTurnSettings } from '@objectifthunes/three-book';
@@ -87,55 +120,37 @@ book.startAutoTurning(AutoTurnDirection.Next, settings, 3);
 
 ## Content Model
 
-- `BookContent.covers`: 4-side sequence expected.
-  - index 0: front outer
-  - index 1: front inner
-  - index 2: back inner
-  - index 3: back outer
-- `BookContent.pages`: page sides in order.
-- Each entry can be:
-  - `THREE.Texture`
-  - `IPageContent` implementation
-  - `null`
-
-`null` entries still render the base paper/cover material color.
-
-## Lifecycle
+**Covers** — 4 entries, one per surface:
 
-1. Create `Book` with options.
-2. Call `book.init()` once after scene setup.
-3. Call `book.update(deltaTime)` every frame.
-4. Call `book.dispose()` when removing permanently.
+| Index | Surface |
+|-------|---------|
+| 0 | Front outer |
+| 1 | Front inner |
+| 2 | Back inner |
+| 3 | Back outer |
 
-If you mutate setup/content significantly, rebuild by setting properties and re-initializing through your app flow.
+**Pages** — ordered list of page-side textures. Each entry can be a `THREE.Texture`, an `IPageContent` implementation, or `null` (renders the base paper color).
 
-## Material and Tint Behavior
-
-This package applies both texture map and material color.
+## Lifecycle
 
-- Final visible color is `map * color`.
-- If you want texture colors unmodified, keep paper/cover setup color white:
-  - `new THREE.Color(1, 1, 1)`.
+1. `new Book(options)` — create.
+2. `book.init()` — build geometry (call once).
+3. `book.update(dt)` — call every frame.
+4. `book.dispose()` — clean up when done.
 
-## API Surface (Main Exports)
+## Material Tinting
 
-- Core:
-  - `Book`, `BookContent`, `BookDirection`
-  - `Paper`, `PaperSetup`, `PaperUVMargin`
-  - `BookBinding`, `BookBound`
-  - `StapleBookBinding`, `StapleBookBound`, `StapleSetup`
-- Content:
-  - `IPageContent`, `PageContent`, `SpritePageContent2`
-- Auto turn:
-  - `AutoTurnDirection`, `AutoTurnMode`, `AutoTurnSettings`, `AutoTurnSetting`
-- Low-level:
-  - `PaperMeshData`, `PaperPattern`, `PaperNode`, `PaperMeshUtility`
-  - `PaperMaterialData`, `RendererFactory`, `BookRenderer`, `MeshFactory`, `PaperMeshDataPool`
+Final color = `texture * paperColor`. Keep color white (`new THREE.Color(1, 1, 1)`) if you want textures to appear unmodified.
 
-## Compatibility
+## API Surface
 
-- ESM package.
-- Peer dependency: `three >= 0.150.0`.
+| Category | Exports |
+|----------|---------|
+| Core | `Book`, `BookContent`, `BookDirection`, `Paper`, `PaperSetup`, `PaperUVMargin` |
+| Binding | `BookBinding`, `BookBound`, `StapleBookBinding`, `StapleBookBound`, `StapleSetup` |
+| Content | `IPageContent`, `PageContent`, `SpritePageContent2` |
+| Auto turn | `AutoTurnDirection`, `AutoTurnMode`, `AutoTurnSettings`, `AutoTurnSetting` |
+| Low-level | `PaperMeshData`, `PaperPattern`, `PaperNode`, `PaperMeshUtility`, `PaperMaterialData`, `RendererFactory`, `BookRenderer`, `MeshFactory`, `PaperMeshDataPool` |
 
 ## Development
 
@@ -143,16 +158,6 @@ From the workspace root:
 
 ```bash
 pnpm install
-pnpm build
-pnpm dev
+pnpm build   # build the library
+pnpm dev     # build library + start demo app
 ```
-
-- `pnpm build`: builds the library package.
-- `pnpm dev`: builds the library first, then starts demo app.
-
-## Troubleshooting
-
-- `404` on npm publish for scoped package:
-  - Ensure the npm token/account has permission for the target org scope.
-- Cover/page colors look unexpectedly tinted:
-  - Check `coverPaperSetup.color` / `pagePaperSetup.color`; non-white tints textures.

package/package.json

@@ -1,30 +1,31 @@
-{
-  "name": "@objectifthunes/three-book",
-  "version": "0.1.2",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "peerDependencies": {
-    "three": ">=0.150.0"
-  },
-  "devDependencies": {
-    "three": "^0.172.0",
-    "@types/three": "^0.172.0",
-    "typescript": "^5.7.0",
-    "vite": "^6.0.0",
-    "vite-plugin-dts": "^4.0.0"
-  },
-  "scripts": {
-    "build": "vite build && tsc --emitDeclarationOnly",
-    "typecheck": "tsc --noEmit"
-  }
-}
+{
+  "name": "@objectifthunes/three-book",
+  "version": "0.1.3",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "prepack": "pnpm run build"
+  },
+  "peerDependencies": {
+    "three": ">=0.150.0"
+  },
+  "devDependencies": {
+    "three": "^0.172.0",
+    "@types/three": "^0.172.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.0.0"
+  }
+}