@npcify/web 0.1.0
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 +113 -0
- package/dist/index.d.ts +970 -0
- package/dist/index.js +8314 -0
- package/examples/index.html +5 -0
- package/examples/main.js +40 -0
- package/package.json +45 -0
package/README.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# @npcify/web
|
|
2
|
+
|
|
3
|
+
Add a Npcify character to any browser application with JavaScript. Includes VRM
|
|
4
|
+
rendering, animation, lip sync, live chat, baked conversations, and a canvas
|
|
5
|
+
integration. No Vue or React dependency.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install @npcify/web
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Use an ESM-capable bundler, such as Vite. This package includes the required
|
|
14
|
+
Npcify runtime code; consumers do not need private workspace packages.
|
|
15
|
+
|
|
16
|
+
## Plain JavaScript
|
|
17
|
+
|
|
18
|
+
Create a key in your character's **Export → API keys** tab. Choose the characters
|
|
19
|
+
that integration may access. Copy the key when created; it is shown only once.
|
|
20
|
+
|
|
21
|
+
```html
|
|
22
|
+
<canvas id="npc" style="width: 100%; height: 480px; touch-action: none"></canvas>
|
|
23
|
+
<button id="start" disabled>Start conversation</button>
|
|
24
|
+
<div id="replies"></div>
|
|
25
|
+
<p id="status" role="status"></p>
|
|
26
|
+
<script type="module" src="/main.js"></script>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
```js
|
|
30
|
+
// main.js
|
|
31
|
+
import { mountNpcify } from '@npcify/web'
|
|
32
|
+
|
|
33
|
+
const start = document.querySelector('#start')
|
|
34
|
+
const replies = document.querySelector('#replies')
|
|
35
|
+
const status = document.querySelector('#status')
|
|
36
|
+
const view = await mountNpcify({
|
|
37
|
+
canvas: document.querySelector('#npc'),
|
|
38
|
+
baseUrl: 'https://api.npcify.ai',
|
|
39
|
+
characterId: 'YOUR_CHARACTER_ID',
|
|
40
|
+
apiKey: 'YOUR_SCOPED_API_KEY',
|
|
41
|
+
serverRendering: false, // Use the setting from Export → Web SDK.
|
|
42
|
+
onError: (error) => { status.textContent = error.message },
|
|
43
|
+
})
|
|
44
|
+
const { npcify } = view
|
|
45
|
+
npcify.onOptionsReady(({ options }) => {
|
|
46
|
+
replies.replaceChildren()
|
|
47
|
+
for (const option of options) {
|
|
48
|
+
const button = document.createElement('button')
|
|
49
|
+
button.textContent = option.label
|
|
50
|
+
button.onclick = async () => {
|
|
51
|
+
replies.replaceChildren()
|
|
52
|
+
try { await npcify.sendMessage(option.label) }
|
|
53
|
+
catch (error) { status.textContent = error.message }
|
|
54
|
+
}
|
|
55
|
+
replies.append(button)
|
|
56
|
+
}
|
|
57
|
+
})
|
|
58
|
+
start.disabled = false
|
|
59
|
+
start.onclick = async () => {
|
|
60
|
+
start.disabled = true
|
|
61
|
+
try {
|
|
62
|
+
await npcify.unlockAudio()
|
|
63
|
+
await npcify.createConversation()
|
|
64
|
+
} catch (error) {
|
|
65
|
+
status.textContent = error.message
|
|
66
|
+
start.disabled = false
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
window.addEventListener('pagehide', () => { void view.dispose() }, { once: true })
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Run the included `examples/index.html` and `examples/main.js` with any ESM
|
|
73
|
+
bundler after replacing their configuration placeholders. Keys in browser code
|
|
74
|
+
are visible to visitors. Use narrow scopes; keep keys in your backend when they
|
|
75
|
+
must remain private. Calls made with a key are billed to its owner.
|
|
76
|
+
|
|
77
|
+
## Runtime and lifecycle
|
|
78
|
+
|
|
79
|
+
- `mountNpcify({ canvas, baseUrl, characterId, apiKey, serverRendering })` returns
|
|
80
|
+
`{ npcify, dispose }` after loading. Give the canvas a nonzero CSS size.
|
|
81
|
+
- Call `unlockAudio()` during a user gesture before starting playback.
|
|
82
|
+
- `onOptionsReady` delivers choices after playback finishes. `sendMessage(label)`
|
|
83
|
+
selects a choice. Custom replies depend on the character configuration.
|
|
84
|
+
- `onStagingResult` delivers full results. `onCharacterReveal` supports subtitles.
|
|
85
|
+
- `dispose()` stops rendering, releases GPU resources, and disconnects chat.
|
|
86
|
+
Call it when navigating away or removing the canvas.
|
|
87
|
+
- `serverRendering: true` uses acknowledged WebP frames through an authenticated
|
|
88
|
+
render session. Protected VRM/VRMA files stay on the server. Remount after a
|
|
89
|
+
render connection error. This release does not use the hosted site's WebRTC
|
|
90
|
+
video transport.
|
|
91
|
+
- Baked characters load their exported graph and run without runtime generation;
|
|
92
|
+
baked playback requires browser rendering.
|
|
93
|
+
- Keys may cover multiple characters. Editing scopes, rotating, or deleting keys
|
|
94
|
+
affects subsequent requests and disconnects associated conversation sockets.
|
|
95
|
+
- ESM only; `require()` is not a supported package entry point. Browser APIs are
|
|
96
|
+
used when creating a view; do not call `mountNpcify` during server rendering.
|
|
97
|
+
|
|
98
|
+
For custom rendering, use the exported `Npcify` class (`apiToken` option), call
|
|
99
|
+
`loadAssets()`, add `npcify.vrm.scene` to your scene, and call
|
|
100
|
+
`npcify.update(deltaSeconds)` from your render loop. Do not update that VRM a
|
|
101
|
+
second time. Call `endConversation()` when finished.
|
|
102
|
+
|
|
103
|
+
## Maintainer release
|
|
104
|
+
|
|
105
|
+
From the monorepo, run `pnpm -C packages/web typecheck`,
|
|
106
|
+
`pnpm -C packages/web build`, and `pnpm -C packages/web pack`. Inspect the tarball,
|
|
107
|
+
then test installing it in an empty project, importing its entry, resolving its
|
|
108
|
+
TypeScript types, and building the plain JavaScript example. Publish that
|
|
109
|
+
verified tarball using `npm publish <tarball> --access public`; npm may request
|
|
110
|
+
interactive 2FA. Check the registry version and install from the registry again.
|
|
111
|
+
|
|
112
|
+
Private Npcify dependencies are bundled into the ESM and declaration entry;
|
|
113
|
+
Third-party renderer and transport dependencies remain normal npm dependencies.
|