@objectifthunes/three-book 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +158 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# @objectifthunes/three-book
|
|
2
|
+
|
|
3
|
+
Procedural, interactive 3D book component for Three.js.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- Real-time page turning (drag with ray input).
|
|
8
|
+
- Auto-turn support (programmatic page turns).
|
|
9
|
+
- Covers + inner pages content model.
|
|
10
|
+
- Configurable paper/cover geometry (size, thickness, stiffness, quality).
|
|
11
|
+
- Book binding implementation (`StapleBookBinding`) included.
|
|
12
|
+
- Works as a regular `THREE.Group` in your scene graph.
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install @objectifthunes/three-book three
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
or
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pnpm add @objectifthunes/three-book three
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Quick Start
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import * as THREE from 'three';
|
|
30
|
+
import {
|
|
31
|
+
Book,
|
|
32
|
+
BookContent,
|
|
33
|
+
BookDirection,
|
|
34
|
+
StapleBookBinding,
|
|
35
|
+
} from '@objectifthunes/three-book';
|
|
36
|
+
|
|
37
|
+
const scene = new THREE.Scene();
|
|
38
|
+
const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 100);
|
|
39
|
+
camera.position.set(0, 4, 5);
|
|
40
|
+
|
|
41
|
+
const renderer = new THREE.WebGLRenderer({ antialias: true });
|
|
42
|
+
renderer.setSize(innerWidth, innerHeight);
|
|
43
|
+
document.body.appendChild(renderer.domElement);
|
|
44
|
+
|
|
45
|
+
const content = new BookContent();
|
|
46
|
+
content.direction = BookDirection.LeftToRight;
|
|
47
|
+
content.covers.push(frontOuterTex, frontInnerTex, backInnerTex, backOuterTex);
|
|
48
|
+
content.pages.push(page1Tex, page2Tex, page3Tex, page4Tex);
|
|
49
|
+
|
|
50
|
+
const book = new Book({
|
|
51
|
+
content,
|
|
52
|
+
binding: new StapleBookBinding(),
|
|
53
|
+
castShadows: true,
|
|
54
|
+
alignToGround: true,
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
book.init();
|
|
58
|
+
scene.add(book);
|
|
59
|
+
|
|
60
|
+
const clock = new THREE.Clock();
|
|
61
|
+
function animate() {
|
|
62
|
+
requestAnimationFrame(animate);
|
|
63
|
+
book.update(clock.getDelta());
|
|
64
|
+
renderer.render(scene, camera);
|
|
65
|
+
}
|
|
66
|
+
animate();
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Input / Page Dragging
|
|
70
|
+
|
|
71
|
+
Use your own ray source (`THREE.Raycaster` + pointer coords), then:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
book.startTurning(ray); // on pointer down
|
|
75
|
+
book.updateTurning(ray); // on pointer move
|
|
76
|
+
book.stopTurning(); // on pointer up
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Auto Turning
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
import { AutoTurnDirection, AutoTurnSettings } from '@objectifthunes/three-book';
|
|
83
|
+
|
|
84
|
+
const settings = new AutoTurnSettings();
|
|
85
|
+
book.startAutoTurning(AutoTurnDirection.Next, settings, 3);
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Content Model
|
|
89
|
+
|
|
90
|
+
- `BookContent.covers`: 4-side sequence expected.
|
|
91
|
+
- index 0: front outer
|
|
92
|
+
- index 1: front inner
|
|
93
|
+
- index 2: back inner
|
|
94
|
+
- index 3: back outer
|
|
95
|
+
- `BookContent.pages`: page sides in order.
|
|
96
|
+
- Each entry can be:
|
|
97
|
+
- `THREE.Texture`
|
|
98
|
+
- `IPageContent` implementation
|
|
99
|
+
- `null`
|
|
100
|
+
|
|
101
|
+
`null` entries still render the base paper/cover material color.
|
|
102
|
+
|
|
103
|
+
## Lifecycle
|
|
104
|
+
|
|
105
|
+
1. Create `Book` with options.
|
|
106
|
+
2. Call `book.init()` once after scene setup.
|
|
107
|
+
3. Call `book.update(deltaTime)` every frame.
|
|
108
|
+
4. Call `book.dispose()` when removing permanently.
|
|
109
|
+
|
|
110
|
+
If you mutate setup/content significantly, rebuild by setting properties and re-initializing through your app flow.
|
|
111
|
+
|
|
112
|
+
## Material and Tint Behavior
|
|
113
|
+
|
|
114
|
+
This package applies both texture map and material color.
|
|
115
|
+
|
|
116
|
+
- Final visible color is `map * color`.
|
|
117
|
+
- If you want texture colors unmodified, keep paper/cover setup color white:
|
|
118
|
+
- `new THREE.Color(1, 1, 1)`.
|
|
119
|
+
|
|
120
|
+
## API Surface (Main Exports)
|
|
121
|
+
|
|
122
|
+
- Core:
|
|
123
|
+
- `Book`, `BookContent`, `BookDirection`
|
|
124
|
+
- `Paper`, `PaperSetup`, `PaperUVMargin`
|
|
125
|
+
- `BookBinding`, `BookBound`
|
|
126
|
+
- `StapleBookBinding`, `StapleBookBound`, `StapleSetup`
|
|
127
|
+
- Content:
|
|
128
|
+
- `IPageContent`, `PageContent`, `SpritePageContent2`
|
|
129
|
+
- Auto turn:
|
|
130
|
+
- `AutoTurnDirection`, `AutoTurnMode`, `AutoTurnSettings`, `AutoTurnSetting`
|
|
131
|
+
- Low-level:
|
|
132
|
+
- `PaperMeshData`, `PaperPattern`, `PaperNode`, `PaperMeshUtility`
|
|
133
|
+
- `PaperMaterialData`, `RendererFactory`, `BookRenderer`, `MeshFactory`, `PaperMeshDataPool`
|
|
134
|
+
|
|
135
|
+
## Compatibility
|
|
136
|
+
|
|
137
|
+
- ESM package.
|
|
138
|
+
- Peer dependency: `three >= 0.150.0`.
|
|
139
|
+
|
|
140
|
+
## Development
|
|
141
|
+
|
|
142
|
+
From the workspace root:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
pnpm install
|
|
146
|
+
pnpm build
|
|
147
|
+
pnpm dev
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
- `pnpm build`: builds the library package.
|
|
151
|
+
- `pnpm dev`: builds the library first, then starts demo app.
|
|
152
|
+
|
|
153
|
+
## Troubleshooting
|
|
154
|
+
|
|
155
|
+
- `404` on npm publish for scoped package:
|
|
156
|
+
- Ensure the npm token/account has permission for the target org scope.
|
|
157
|
+
- Cover/page colors look unexpectedly tinted:
|
|
158
|
+
- Check `coverPaperSetup.color` / `pagePaperSetup.color`; non-white tints textures.
|