live2d-widget Documentation

File: README.md Copy Chapter

Live2D Widget

English

特性 Copy Chapter

• 在网页中添加 Live2D 看板娘
• 轻量级，除 Live2D Cubism Core 外无其他运行时依赖
• 核心代码由 TypeScript 编写，易于集成

注：以上人物模型仅供展示之用，本仓库并不包含任何模型。

你也可以查看示例网页：

• 在 米米的博客 的左下角可查看效果
• demo/demo.html，展现基础功能
• demo/login.html，仿 NPM 的登陆界面

使用 Copy Chapter

如果你是小白，或者只需要最基础的功能，那么只用将这一行代码加入 html 页面的 head 或 body 中，即可加载看板娘：

<script src="https://fastly.jsdelivr.net/npm/[email protected]/dist/autoload.js"></script>

添加代码的位置取决于你的网站的构建方式。例如，如果你使用的是 Hexo，那么需要在主题的模版文件中添加以上代码。对于用各种模版引擎生成的页面，修改方法类似。
如果网站启用了 PJAX，由于看板娘不必每页刷新，需要注意将该脚本放到 PJAX 刷新区域之外。

但是！我们强烈推荐自己进行配置，让看板娘更加适合你的网站！
如果你有兴趣自己折腾的话，请看下面的详细说明。

配置 Copy Chapter

你可以对照 dist/autoload.js 的源码查看可选的配置项目。autoload.js 会自动加载两个文件：waifu.css 和 waifu-tips.js。waifu-tips.js 会创建 initWidget 函数，这就是加载看板娘的主函数。initWidget 函数接收一个 Object 类型的参数，作为看板娘的配置。以下是配置选项：

模型仓库 Copy Chapter

本仓库中并不包含任何模型，需要单独配置模型仓库，并通过 cdnPath 选项进行设置。
旧版本的 initWidget 函数支持 apiPath 参数，这要求用户自行搭建后端，可以参考 live2d_api。后端接口会对模型资源进行整合并动态生成 JSON 描述文件。自 1.0 版本起，相关功能已通过前端实现，因此不再需要专门的 apiPath，所有模型资源都可通过静态方式提供。只要存在 model_list.json 和模型对应的 textures.cache，即可支持换装等功能。

开发 Copy Chapter

如果以上「配置」部分提供的选项还不足以满足你的需求，那么你可以自己进行修改。本仓库的目录结构如下：

• src 目录下包含了各个组件的 TypeScript 源代码，例如按钮和对话框等；
• build 目录下包含了基于 src 中源代码构建后的文件（请不要直接修改！）；
• dist 目录下包含了进一步打包后网页直接可用的文件，其中：
  • autoload.js 用于自动加载其它资源，例如样式表等；
  • waifu-tips.js 是由 build/waifu-tips.js 自动打包生成的，不建议直接修改；
  • waifu.css 是看板娘的样式表；
  • waifu-tips.json 中定义了触发条件（selector，CSS 选择器）和触发时显示的文字（text）。
    waifu-tips.json 中默认的 CSS 选择器规则是对 Hexo 的 NexT 主题 有效的，为了适用于你自己的网页，可能需要自行修改，或增加新内容。
    警告：waifu-tips.json 中的内容可能不适合所有年龄段，或不宜在工作期间访问。在使用时，请自行确保它们是合适的。

要在本地部署本项目的开发测试环境，你需要安装 Node.js 和 npm，然后执行以下命令：

git clone https://github.com/stevenjoezhang/live2d-widget.git
npm install

如果需要使用 Cubism 3 及更新的模型，请单独下载并解压 Cubism SDK for Web 到 src 目录下，例如 src/CubismSdkForWeb-5-r.4。受 Live2D 许可协议（包括 Live2D Proprietary Software License Agreement 和 Live2D Open Software License Agreement）限制，本项目无法包含 Cubism SDK for Web 的源码。
如果只需要使用 Cubism 2 版本的模型，可以跳过此步骤。本仓库使用的代码满足 Live2D 许可协议中 Redistributable Code 相关条款。
完成后，使用以下命令进行编译和打包。

npm run build

src 目录中的 TypeScript 代码会被编译到 build 目录中，build 目录中的代码会被进一步打包到 dist 目录中。
为了能够兼容 Cubism 2 和 Cubism 3 及更新的模型，并减小代码体积，Cubism Core 及相关的代码会根据检测到的模型版本动态加载。

部署 Copy Chapter

在本地完成了修改后，你可以将修改后的项目部署在自己的服务器上，或者通过 CDN 加载。为了方便自定义有关内容，可以把这个仓库 Fork 一份，然后把修改后的内容通过 git push 到你的仓库中。

使用 jsDelivr CDN Copy Section

如果要通过 jsDelivr 加载 Fork 后的仓库，使用方法对应地变为

<script src="https://fastly.jsdelivr.net/gh/username/live2d-widget@latest/autoload.js"></script>

将此处的 username 替换为你的 GitHub 用户名。为了使 CDN 的内容正常刷新，需要创建新的 git tag 并推送至 GitHub 仓库中，否则此处的 @latest 仍然指向更新前的文件。此外 CDN 本身存在缓存，因此改动可能需要一定的时间生效。

使用 Cloudflare Pages Copy Section

也可以使用 Cloudflare Pages 来部署。在 Cloudflare Pages 中创建一个新的项目，选择你 Fork 的仓库。接下来，设置构建命令为 npm run build。完成后，Cloudflare Pages 会自动构建并部署你的项目。

Self-host Copy Section

你也可以直接把这些文件放到服务器上，而不是通过 CDN 加载。

• 可以把修改后的代码仓库克隆到服务器上，或者通过 ftp 等方式将本地文件上传到服务器的网站的目录下；
• 如果你是通过 Hexo 等工具部署的静态博客，请把本项目的代码放在博客源文件目录下（例如 source 目录）。重新部署博客时，相关文件就会自动上传到对应的路径下。为了避免这些文件被 Hexo 插件错误地修改，可能需要设置 skip_render。

这样，整个项目就可以通过你的域名访问了。不妨试试能否正常地通过浏览器打开 autoload.js 和 live2d.min.js 等文件，并确认这些文件的内容是完整和正确的。
一切正常的话，接下来修改 autoload.js 中的常量 live2d_path 为 dist 目录的 URL 即可。比如说，如果你能够通过

https://example.com/path/to/live2d-widget/dist/live2d.min.js

访问到 live2d.min.js，那么就把 live2d_path 的值修改为

https://example.com/path/to/live2d-widget/dist/

路径末尾的 / 一定要加上。
完成后，在你要添加看板娘的界面加入

<script src="https://example.com/path/to/live2d-widget/dist/autoload.js"></script>

就可以加载了。

鸣谢 Copy Chapter

感谢 BrowserStack 容许我们在真实的浏览器中测试此项目。
Thanks to BrowserStack for providing the infrastructure that allows us to test in real browsers!

感谢 jsDelivr 提供的 CDN 服务。
Thanks jsDelivr for providing public CDN service.

感谢 fghrsh 提供的 API 服务。

感谢 一言 提供的语句接口。

点击看板娘的纸飞机按钮时，会出现一个彩蛋，这来自于 WebsiteAsteroids。

更多 Copy Chapter

代码自这篇博文魔改而来：
https://www.fghrsh.net/post/123.html

更多内容可以参考：
https://nocilol.me/archives/lab/add-dynamic-poster-girl-with-live2d-to-your-blog-02
https://github.com/guansss/pixi-live2d-display

更多模型仓库：
https://github.com/zenghongtu/live2d-model-assets

除此之外，还有桌面版本：
https://github.com/TSKI433/hime-display
https://github.com/amorist/platelet
https://github.com/akiroz/Live2D-Widget
https://github.com/zenghongtu/PPet
https://github.com/LikeNeko/L2dPetForMac

以及 Wallpaper Engine：
https://github.com/guansss/nep-live2d

Live2D 官方网站：
https://www.live2d.com/en/

许可证 Copy Chapter

本仓库并不包含任何模型，用作展示的所有 Live2D 模型、图片、动作数据等版权均属于其原作者，仅供研究学习，不得用于商业用途。

本仓库的代码（不包括受 Live2D Proprietary Software License 和 Live2D Open Software License 约束的部分）基于 GNU General Public License v3 协议开源
http://www.gnu.org/licenses/gpl-3.0.html

Live2D 相关代码的使用请遵守对应的许可：

Live2D Cubism SDK 2.1 的许可证：
Live2D SDK License Agreement (Public)

Live2D Cubism SDK 5 的许可证：
Live2D Cubism Core は Live2D Proprietary Software License で提供しています。
https://www.live2d.com/eula/live2d-proprietary-software-license-agreement_cn.html
Live2D Cubism Components は Live2D Open Software License で提供しています。
https://www.live2d.com/eula/live2d-open-software-license-agreement_cn.html

更新日志 Copy Chapter

2020年1月1日起，本项目不再依赖于 jQuery。

2022年11月1日起，本项目不再需要用户单独加载 Font Awesome。

File: README.en.md Copy Chapter

Live2D Widget

中文

Features Copy Chapter

• Add Live2D widget to web page
• Lightweight, with no runtime dependencies other than Live2D Cubism Core
• Core code is written in TypeScript, making it easy to integrate

Note: The character models above are for demonstration purposes only and are not included in this repository.

You can also check out example web pages:

• Check the effect in the lower left corner of Mimi's Blog
• demo/demo.html to demonstrate basic functionality
• demo/login.html to imitate the login interface of NPM

Usage Copy Chapter

If you are a beginner or only need the basic functionality, you can simply add the following line of code to the head or body of your HTML page to load the widget:

<script src="https://fastly.jsdelivr.net/npm/[email protected]/dist/autoload.js"></script>

The placement of the code depends on how your website is built. For example, if you are using Hexo, you need to add the above code to the template file of your theme. The modification process is similar for pages generated using various template engines.
If your website uses PJAX, since the widget does not need to be refreshed on every page, make sure to place the script outside the PJAX refresh area.

However, we strongly recommend configuring the widget yourself to make it more suitable for your website!
If you are interested in customizing the widget, please refer to the detailed instructions below.

Configuration Copy Chapter

You can refer to the source code of dist/autoload.js to see the available configuration options. autoload.js will automatically load two files: waifu.css and waifu-tips.js. waifu-tips.js creates the initWidget function, which is the main function for loading the widget. The initWidget function accepts an object-type parameter as the configuration for the widget. The following are the available options:

Model Repository Copy Chapter

This repository does not include any models. You need to configure a separate model repository and set it via the cdnPath option.
Older versions of the initWidget function supported the apiPath parameter, which required users to set up their own backend. You can refer to live2d_api for details. The backend interface would integrate model resources and dynamically generate JSON description files. Since version 1.0, these features have been implemented on the frontend, so a dedicated apiPath is no longer required. All model resources can be provided statically. As long as model_list.json and the corresponding textures.cache for each model exist, features such as outfit changing are supported.

Development Copy Chapter

If the options provided in the "Configuration" section above are not enough to meet your needs, you can make modifications yourself. The directory structure of this repository is as follows:

• src directory contains the TypeScript code for each component, e.g. the button and dialog box.
• build directory contains files generated from the source code in src (please do not modify them directly!)
• dist directory contains the files that can be directly used on web pages after packaging, including:
  • autoload.js is used to automatically load other resources such as style sheets.
  • waifu-tips.js is automatically generated by build/waifu-tips.js and it is not recommended to modify it directly.
  • waifu.css is the style sheet for the widget.
  • waifu-tips.json defines the triggering conditions (selector, CSS selector) and the displayed text when triggered (text).
    By default, the CSS selector rules in waifu-tips.json are effective for the Hexo NexT theme, but you may need to modify or add new content to make it suitable for your own website.
    Warning: The content in waifu-tips.json may not be suitable for all age groups or appropriate to access during work. Please ensure their suitability when using them.

To deploy the development testing environment of this project locally, you need to install Node.js and npm, then execute the following commands:

git clone https://github.com/stevenjoezhang/live2d-widget.git
npm install

If you need to use Cubism 3 or newer models, please download and extract the Cubism SDK for Web separately into the src directory, for example, src/CubismSdkForWeb-5-r.4. Due to Live2D license agreements (including the Live2D Proprietary Software License Agreement and Live2D Open Software License Agreement), this project cannot include the source code of Cubism SDK for Web.
If you only need to use Cubism 2 models, you can skip this step. The code in this repository complies with the Redistributable Code terms of the Live2D license agreements.
Once completed, use the following command to compile and bundle the project.

npm run build

The TypeScript code in the src directory is compiled into the build directory, and the code in the build directory is further bundled into the dist directory.
To support both Cubism 2 and Cubism 3 (and newer) models while minimizing code size, Cubism Core and related code are loaded dynamically based on the detected model version.

Deploy Copy Chapter

After making modifications locally, you can deploy the modified project on a server or load it via a CDN. To make it easier to customize, you can fork this repository and push your modified content to your own repository using git push.

Using jsDelivr CDN Copy Section

To load forked repository via jsDelivr, the usage method becomes:

<script src="https://fastly.jsdelivr.net/gh/username/live2d-widget@latest/autoload.js"></script>

Replace username with your GitHub username. To ensure the content of the CDN is refreshed correctly, you need to create a new git tag and push it to the GitHub repository. Otherwise, @latest in the URL will still point to the previous version. Additionally, CDN itself has caching, so the changes may take some time to take effect.

Using Cloudflare Pages Copy Section

You can also deploy using Cloudflare Pages. Create a new project in Cloudflare Pages and select your forked repository. Then, set the build command to npm run build. Once configured, Cloudflare Pages will automatically build and deploy your project.

Self-host Copy Section

Alternatively, you can directly host these files on your server instead of loading them via CDN.

• Clone the forked repository onto your server, or upload the local files to the website directory on the server using ftp or similar methods.
• If you are deploying a static blog using Hexo or similar tools, place the code of this project in the blog's source file directory (e.g., the source directory). When redeploying the blog, the relevant files will be automatically uploaded to the corresponding paths. To prevent these files from being incorrectly modified by Hexo plugins, you may need to set skip_render.

Afterwards, the entire project can be accessed through your domain name. You can try opening the autoload.js and live2d.min.js files in your browser and confirm that their content is complete and correct.
If everything is normal, you can proceed to modify the constant live2d_path in autoload.js to the URL of the dist directory. For example, if you can access live2d.min.js through the following URL:

https://example.com/path/to/live2d-widget/dist/live2d.min.js

then modify the value of live2d_path to:

https://example.com/path/to/live2d-widget/dist/

Make sure to include the trailing / in the path.
Once done, add the following code to the interface where you want to add the live2d-widget:

<script src="https://example.com/path/to/live2d-widget/dist/autoload.js"></script>

This will load the widget.

Thanks Copy Chapter

Thanks to BrowserStack for providing the infrastructure that allows us to test in real browsers!

Thanks to jsDelivr for providing public CDN service.

Thanks fghrsh for providing API service.

Thanks to Hitokoto for providing the sentence API.

When you click on the paper airplane button of the virtual assistant, a hidden surprise will appear. This feature is from WebsiteAsteroids.

More Copy Chapter

The code is modified based on this blog post:
https://www.fghrsh.net/post/123.html

For more information, you can refer to the following links:
https://nocilol.me/archives/lab/add-dynamic-poster-girl-with-live2d-to-your-blog-02
https://github.com/guansss/pixi-live2d-display

For more models:
https://github.com/zenghongtu/live2d-model-assets

In addition to that, there are desktop versions available:
https://github.com/TSKI433/hime-display
https://github.com/amorist/platelet
https://github.com/akiroz/Live2D-Widget
https://github.com/zenghongtu/PPet
https://github.com/LikeNeko/L2dPetForMac

And also Wallpaper Engine:
https://github.com/guansss/nep-live2d

Official Live2D websites:
https://www.live2d.com/en/

License Copy Chapter

This repository does not contain any models. The copyrights of all Live2D models, images, and motion data used for demonstration purposes belong to their respective original authors. They are provided for research and learning purposes only and should not be used for commercial purposes.

The code in this repository (excluding parts covered by the Live2D Proprietary Software License and the Live2D Open Software License) is released under the GNU General Public License v3
http://www.gnu.org/licenses/gpl-3.0.html

Please comply with the relevant licenses when using any Live2D-related code:

License for Live2D Cubism SDK 2.1:
Live2D SDK License Agreement (Public)

License for Live2D Cubism SDK 5:
Live2D Cubism Core is provided under the Live2D Proprietary Software License.
https://www.live2d.com/eula/live2d-proprietary-software-license-agreement_en.html
Live2D Cubism Components are provided under the Live2D Open Software License.
https://www.live2d.com/eula/live2d-open-software-license-agreement_en.html

Update Log Copy Chapter

Starting from January 1, 2020, this project no longer depends on jQuery.

Starting from November 1, 2022, this project no longer requires users to separately load Font Awesome.