@jingx/three-dice-roll 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# three-dice-roll
+
+Reusable Three.js dice components with deterministic end results.
+
+The package exports:
+
+- `DiceComponent`: full casino-style three-dice game scene
+- `SpinnerDiceComponent`: one spinner-style die
+
+The animations are authored, not physics-simulated. A result is chosen first, then the component animates toward a valid final orientation for that result.
+
+## Install
+
+```bash
+npm install three-dice-roll three
+```
+
+`three` is a peer dependency and must be installed by the consuming app.
+
+## Usage
+
+### Three dice
+
+```js
+import { DiceComponent } from 'three-dice-roll';
+import 'three-dice-roll/style.css';
+
+const dice = new DiceComponent({
+  container: document.getElementById('app'),
+  result: [2, 5, 6],
+  startRoll: 1,
+  rollDoneCallBack(results) {
+    console.log(results);
+  },
+});
+
+dice.setProps({
+  result: [1, 1, 1],
+  startRoll: 2,
+});
+```
+
+### Spinner die
+
+```js
+import { SpinnerDiceComponent } from 'three-dice-roll';
+import 'three-dice-roll/style.css';
+
+const spinner = new SpinnerDiceComponent({
+  container: document.getElementById('app'),
+  result: 4,
+  startRoll: 1,
+  rollDoneCallBack(result) {
+    console.log(result);
+  },
+});
+```
+
+## API
+
+### `DiceComponent`
+
+Wraps the full three-dice casino game scene:
+
+- table stage
+- plate
+- dome
+- roll button and hand art
+- Three.js dice renderer and roll animation
+
+Props:
+
+- `container?: HTMLElement`
+- `result?: number[] | null`
+- `rollDoneCallBack?: (results: number[]) => void`
+- `startRoll?: boolean | number | string`
+- `interactive?: boolean`
+
+Methods:
+
+- `setProps(nextProps)`
+- `roll(result?)`
+- `getResults()`
+- `destroy()`
+
+### `SpinnerDiceComponent`
+
+Props:
+
+- `container?: HTMLElement`
+- `result?: number | null`
+- `rollDoneCallBack?: (result: number) => void`
+- `startRoll?: boolean | number | string`
+- `interactive?: boolean`
+
+Methods:
+
+- `setProps(nextProps)`
+- `roll(result?)`
+- `getResult()`
+- `destroy()`
+
+## Notes
+
+- Ships ESM and CommonJS entrypoints
+- Ships a Vite library build from `dist/`
+- Requires a bundler that can compile ESM dependencies
+
+### Next.js
+
+Use the components from a client component and import `three-dice-roll/style.css` once in that client boundary or in your app styles. There is a working example in `examples/next-ts`.
+
+## Local development
+
+```bash
+npm install
+npm run dev
+npm run build
+npm run publish:dry-run
+```