LivLiv Player 0.3.0

The first version of LivLiv Player on npm. The interface settled first, so a page written for 0.2 needs a few changes. Format 4 is unchanged.

What to change from 0.2

0.2	0.3
import ... from '@livliv/player' and its subpaths	'@livliv-dev/player', the package's name on npm.
player.act('away')	player.setAway(true) and setAway(false). act('away') now throws: it was a switch among one-off moves.
player.puppet	No longer in the types. player.poke() and player.canvasToModel() are what pages used it for. The field still exists and can change in any version.
player.load(a); player.load(b) played a, then b	The new load replaces the one running, which rejects with an AbortError. If you catch errors, let this one through: if (e.name === 'AbortError') return.
dispose() on a load running rejected with an Error	It rejects with an AbortError, as load() on a disposed player does.
Errors told apart by their message	e.code, on a LivLivError. The messages can change.

Install

npm install @livliv-dev/player

The npm package is the player alone, without characters/. The featured characters are in this repository's characters/: copy the ones you use next to your page, with their licence. Kujira, Kujira Q and Pen come from other people's work; their sources, credits and terms are in characters/CREDITS.md.

Face tracking also needs @mediapipe/tasks-vision (1.1.1), and VRM characters need three and @pixiv/three-vrm. All three are optional peer dependencies.

New

• load(source, { signal, onProgress, poster }): call a load off, follow how far it has come, show a picture until the first frame.
• LivLivError, with a code for each reason, from @livliv-dev/player and @livliv-dev/player/body.
• player.contextLost and player.onContextLost: the page hears when the WebGL context is gone. See API.md.
• dispose({ release: true }): gives the WebGL context up, for a canvas leaving the page.
• player.setAway(), player.poke(), player.canvasToModel().
• example/react.html, which loads React from esm.sh.

Changed

• A model that breaks while it is built leaves the character before as it was. It used to leave an empty canvas.
• The pose stays in the ranges of PARAM_RANGES on Player too, as it did on BodyPlayer. A value that is not a number counts as the default.
• maxPixelRatio can be read and changed on a Player.
• snapshot() on a Player draws first, so it is the pose as it is now, on a paused player too.
• A BodyPlayer's Frame.time counts the frames before this one, as a Player's does. Its idle motion runs one frame later.
• Player and BodyPlayer now share their code. Nothing a Player draws changed in our frame-by-frame comparison.

Requirements

WebGL2 and ES2023: Chrome / Edge 97+, Firefox 104+, Safari 15.4+. Tested on current desktop Chromium, Firefox and WebKit; not yet on real phones or in in-app WebViews.

Known

Issue #1 is still open, and a fresh export from Blender hasn't been tested.

License

Code: Apache License 2.0. Featured characters, which are not in the npm package: characters/LICENSE.md and characters/CREDITS.md.

All changes: CHANGELOG.md and v0.2.1...v0.3.0

---

中文：这是第一个发布到 npm 的版本。接口先定了下来，所以为 0.2 写的页面要改几处：act('away')、player.puppet、连续调用 load()、靠错误信息判断错误，改法见上面的表。安装：npm install @livliv-dev/player。npm 包里只有播放器，不含 characters/；精选角色在这个仓库里，把要用的角色连同许可一起复制到你的页面旁边。Kujira、Kujira Q 和 Pen 来自别人的作品，来源和条款见 characters/CREDITS.md。目前在桌面的 Chromium、Firefox、WebKit 上测过，手机还没有测。issue #1 还开着，从 Blender 新导出的文件也没有测过。

日本語：npm で公開する最初のバージョンです。先に API を確定したため、0.2 向けのページは数か所の変更が必要です。act('away')、player.puppet、続けて呼ぶ load()、メッセージによるエラー判定が対象で、変更方法は上の表にあります。インストールは npm install @livliv-dev/player です。npm パッケージに入っているのはプレイヤーだけで、characters/ は含まれません。厳選キャラクターはこのリポジトリにあるので、使うキャラクターをライセンスと一緒にページの横にコピーしてください。Kujira、Kujira Q、Pen は他の方の作品がもとになっており、出典と利用条件は characters/CREDITS.md にあります。テストはデスクトップの Chromium、Firefox、WebKit のみで、スマートフォンではまだ行っていません。issue #1 は未解決で、Blender から新たに書き出したファイルもテストしていません。