mirror of
https://github.com/stevenjoezhang/live2d-widget.git
synced 2024-11-23 13:27:02 +08:00
Create README.en.md
This commit is contained in:
Mimi
parent
ae27493c29
commit
1ac32abfd6
189
README.en.md
Normal file
189
README.en.md
Normal file
@ -0,0 +1,189 @@
|
||||
# Live2D Widget
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[中文](README.md)
|
||||
|
||||
## Features
|
||||
|
||||
Add Live2D widget to web page. Compatible with PJAX.
|
||||
|
||||
<img src="assets/screenshot-2.png" width="280"><img src="assets/screenshot-3.png" width="280"><img src="assets/screenshot-1.png" width="270">
|
||||
|
||||
(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](https://zhangshuqiao.org)
|
||||
- [demo.html](https://mi.js.org/live2d-widget/demo/demo.html) to demonstrate basic functionality
|
||||
- [login.html](https://mi.js.org/live2d-widget/demo/login.html) to imitate the login interface of NPM
|
||||
|
||||
## Usage
|
||||
|
||||
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:
|
||||
```xml
|
||||
<script src="https://fastly.jsdelivr.net/gh/stevenjoezhang/live2d-widget@latest/autoload.js"></script>
|
||||
```
|
||||
The placement of the code depends on how your website is built. For example, if you are using [Hexo](https://hexo.io), 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
|
||||
|
||||
You can refer to the source code of `autoload.js` to see the available configuration options. `autoload.js` will automatically load three files: `waifu.css`, `live2d.min.js`, 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:
|
||||
|
||||
| Option | Type | Default Value | Description |
|
||||
| ------ | ---- | ------------- | ----------- |
|
||||
| `waifuPath` | `string` | `https://fastly.jsdelivr.net/gh/stevenjoezhang/live2d-widget@latest/waifu-tips.json` | Path to the widget resources, can be modified |
|
||||
| `apiPath` | `string` | `https://live2d.fghrsh.net/api/` | API path, optional |
|
||||
| `cdnPath` | `string` | `https://fastly.jsdelivr.net/gh/fghrsh/live2d_api/` | CDN path, optional |
|
||||
| `tools` | `string[]` | see `autoload.js` | Buttons of the loaded tools, optional |
|
||||
|
||||
Among them, the parameters `apiPath` and `cdnPath` only need to set one of them. `apiPath` is the URL of the backend API, which can be set up and modified by yourself (there are many things to modify, not discussed here). You can refer to [live2d_api](https://github.com/fghrsh/live2d_api) for more information. On the other hand, `cdnPath` is used to load resources through CDN services like jsDelivr, which provides better stability.
|
||||
|
||||
## Customization
|
||||
|
||||
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/waifu-tips.js` contains the logic for the button and dialog box.
|
||||
- `waifu-tips.js` is automatically generated by `src/waifu-tips.js` and it is not recommended to modify it directly.
|
||||
- `waifu-tips.json` defines the triggering conditions (`selector`, CSS selector) and the displayed text when triggered (`text`).
|
||||
- `waifu.css` is the style sheet for the virtual assistant.
|
||||
|
||||
By default, the CSS selector rules in `waifu-tips.json` are effective for the Hexo [NexT theme](http://github.com/next-theme/hexo-theme-next), 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:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/stevenjoezhang/live2d-widget.git
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
If you have any questions, feel free to raise an issue. If you have any modification suggestions, welcome to submit a pull request.
|
||||
|
||||
## Deploy
|
||||
|
||||
After making modifications locally, you can deploy the modified project on a server or load it via a CDN for use on a webpage.
|
||||
|
||||
### Using CDN
|
||||
|
||||
To customize the content, you can fork this repository and push the modified content to your own repository using `git push`. In this case, the usage method becomes:
|
||||
|
||||
```xml
|
||||
<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. Relevant documentation:
|
||||
- [Git Basics - Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
|
||||
- [Managing releases in a repository](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)
|
||||
|
||||
### Self-host
|
||||
|
||||
Alternatively, you can directly host these files on your server instead of loading them via CDN.
|
||||
|
||||
- If you can connect to your host via `ssh`, clone the forked and modified code repository onto your server.
|
||||
- If your host cannot be accessed via `ssh` (e.g., a regular virtual host), modify the code locally and upload the files to the website directory on the host 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 `live2d-widget` directory. For example, if you can access `live2d.min.js` through the following URL:
|
||||
```
|
||||
https://example.com/path/to/live2d-widget/live2d.min.js
|
||||
```
|
||||
then modify the value of `live2d_path` to:
|
||||
```
|
||||
https://example.com/path/to/live2d-widget/
|
||||
```
|
||||
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:
|
||||
```xml
|
||||
<script src="https://example.com/path/to/live2d-widget/autoload.js"></script>
|
||||
```
|
||||
This will load the widget.
|
||||
|
||||
## Thanks
|
||||
|
||||
<a href="https://www.browserstack.com/">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" height="80" srcset="https://d98b8t1nnulk5.cloudfront.net/production/images/layout/logo-header.png?1469004780">
|
||||
<source media="(prefers-color-scheme: light)" height="80" srcset="https://live.browserstack.com/images/opensource/browserstack-logo.svg">
|
||||
<img alt="BrowserStack Logo" height="80" src="https://live.browserstack.com/images/opensource/browserstack-logo.svg">
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
> Thanks to [BrowserStack](https://www.browserstack.com/) for providing the infrastructure that allows us to test in real browsers!
|
||||
|
||||
<a href="https://www.jsdelivr.com">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" height="80" srcset="https://raw.githubusercontent.com/jsdelivr/jsdelivr-media/master/white/svg/jsdelivr-logo-horizontal.svg">
|
||||
<source media="(prefers-color-scheme: light)" height="80" srcset="https://raw.githubusercontent.com/jsdelivr/jsdelivr-media/master/default/svg/jsdelivr-logo-horizontal.svg">
|
||||
<img alt="jsDelivr Logo" height="80" src="https://raw.githubusercontent.com/jsdelivr/jsdelivr-media/master/default/svg/jsdelivr-logo-horizontal.svg">
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
> Thanks to jsDelivr for providing public CDN service.
|
||||
|
||||
The code is modified based on this blog post:
|
||||
https://www.fghrsh.net/post/123.html
|
||||
|
||||
Thanks to [Hitokoto](https://hitokoto.cn) 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](http://www.websiteasteroids.com).
|
||||
|
||||
## More
|
||||
|
||||
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/xiazeyu/live2d-widget.js
|
||||
https://github.com/summerscar/live2dDemo
|
||||
|
||||
Regarding the backend API models:
|
||||
https://github.com/xiazeyu/live2d-widget-models
|
||||
https://github.com/xiaoski/live2d_models_collection
|
||||
|
||||
In addition to that, there are desktop versions available:
|
||||
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
|
||||
|
||||
## License
|
||||
|
||||
Released under the GNU General Public License v3
|
||||
http://www.gnu.org/licenses/gpl-3.0.html
|
||||
|
||||
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.
|
||||
|
||||
Official Live2D websites:
|
||||
https://www.live2d.com/en/
|
||||
https://live2d.github.io
|
||||
|
||||
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.
|
||||
http://www.live2d.com/eula/live2d-open-software-license-agreement_en.html
|
||||
|
||||
> The terms and conditions do prohibit modification, but obfuscating in `live2d.min.js` would not be considered illegal modification.
|
||||
|
||||
https://community.live2d.com/discussion/140/webgl-developer-licence-and-javascript-question
|
||||
|
||||
## Update Log
|
||||
|
||||
On October 31, 2018, the original API provided by fghrsh was discontinued. Please update to the new address. Refer to the following article for more information:
|
||||
https://www.fghrsh.net/post/170.html
|
||||
|
||||
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.
|
||||
23
README.md
23
README.md
@ -7,10 +7,11 @@
|
||||
|
||||
|
||||
|
||||
## 特性 Feature
|
||||
[English](README.en.md)
|
||||
|
||||
## 特性
|
||||
|
||||
在网页中添加 Live2D 看板娘。兼容 PJAX，支持无刷新加载。
|
||||
Add Live2D widget to web page. Compatible with PJAX.
|
||||
|
||||
<img src="assets/screenshot-2.png" width="280"><img src="assets/screenshot-3.png" width="280"><img src="assets/screenshot-1.png" width="270">
|
||||
|
||||
@ -22,7 +23,7 @@ Add Live2D widget to web page. Compatible with PJAX.
|
||||
- [demo.html](https://mi.js.org/live2d-widget/demo/demo.html)，展现基础功能
|
||||
- [login.html](https://mi.js.org/live2d-widget/demo/login.html)，仿 NPM 的登陆界面
|
||||
|
||||
## 使用 Usage
|
||||
## 使用
|
||||
|
||||
如果你是小白，或者只需要最基础的功能，那么只用将这一行代码加入 html 页面的 `head` 或 `body` 中，即可加载看板娘：
|
||||
```xml
|
||||
@ -34,7 +35,7 @@ Add Live2D widget to web page. Compatible with PJAX.
|
||||
**但是！我们强烈推荐自己进行配置，让看板娘更加适合你的网站！**
|
||||
如果你有兴趣自己折腾的话，请看下面的详细说明。
|
||||
|
||||
## 配置 Configuration
|
||||
## 配置
|
||||
|
||||
你可以对照 `autoload.js` 的源码查看可选的配置项目。`autoload.js` 会自动加载三个文件：`waifu.css`，`live2d.min.js` 和 `waifu-tips.js`。`waifu-tips.js` 会创建 `initWidget` 函数，这就是加载看板娘的主函数。`initWidget` 函数接收一个 Object 类型的参数，作为看板娘的配置。以下是配置选项：
|
||||
|
||||
@ -47,7 +48,7 @@ Add Live2D widget to web page. Compatible with PJAX.
|
||||
|
||||
其中，`apiPath` 和 `cdnPath` 两个参数设置其中一项即可。`apiPath` 是后端 API 的 URL，可以自行搭建，并增加模型（需要修改的内容比较多，此处不再赘述），可以参考 [live2d_api](https://github.com/fghrsh/live2d_api)。而 `cdnPath` 则是通过 jsDelivr 这样的 CDN 服务加载资源，更加稳定。
|
||||
|
||||
## 自定义 Customization
|
||||
## 自定义
|
||||
|
||||
如果以上「配置」部分提供的选项还不足以满足你的需求，那么你可以自己进行修改。本仓库的目录结构如下：
|
||||
|
||||
@ -69,11 +70,11 @@ npm run build
|
||||
|
||||
如果有任何疑问，欢迎提 Issue。如果有任何修改建议，欢迎提 Pull Request。
|
||||
|
||||
## 部署 Deploy
|
||||
## 部署
|
||||
|
||||
在本地完成了修改后，你可以将修改后的项目部署在服务器上，或者通过 CDN 加载，以便在网页中使用。
|
||||
|
||||
### Using CDN
|
||||
### 使用 CDN
|
||||
|
||||
要自定义有关内容，可以把这个仓库 Fork 一份，然后把修改后的内容通过 git push 到你的仓库中。这时，使用方法对应地变为
|
||||
```xml
|
||||
@ -107,7 +108,7 @@ https://example.com/path/to/live2d-widget/
|
||||
```
|
||||
就可以加载了。
|
||||
|
||||
## 鸣谢 Thanks
|
||||
## 鸣谢
|
||||
|
||||
<a href="https://www.browserstack.com/">
|
||||
<picture>
|
||||
@ -138,7 +139,7 @@ https://www.fghrsh.net/post/123.html
|
||||
|
||||
点击看板娘的纸飞机按钮时，会出现一个彩蛋，这来自于 [WebsiteAsteroids](http://www.websiteasteroids.com)。
|
||||
|
||||
## 更多 More
|
||||
## 更多
|
||||
|
||||
更多内容可以参考：
|
||||
https://nocilol.me/archives/lab/add-dynamic-poster-girl-with-live2d-to-your-blog-02
|
||||
@ -158,7 +159,7 @@ https://github.com/LikeNeko/L2dPetForMac
|
||||
以及 Wallpaper Engine：
|
||||
https://github.com/guansss/nep-live2d
|
||||
|
||||
## 许可证 License
|
||||
## 许可证
|
||||
|
||||
Released under the GNU General Public License v3
|
||||
http://www.gnu.org/licenses/gpl-3.0.html
|
||||
@ -178,7 +179,7 @@ http://www.live2d.com/eula/live2d-open-software-license-agreement_en.html
|
||||
|
||||
https://community.live2d.com/discussion/140/webgl-developer-licence-and-javascript-question
|
||||
|
||||
## 更新 Update
|
||||
## 更新日志
|
||||
|
||||
2018年10月31日，由 fghrsh 提供的原 API 停用，请更新至新地址。参考文章：
|
||||
https://www.fghrsh.net/post/170.html
|
||||
|
||||
@ -213,15 +213,6 @@ window.addEventListener("load", () => {
|
||||
});
|
||||
}
|
||||
|
||||
function loadOtherModel() {
|
||||
const modelId = localStorage.getItem("modelId");
|
||||
fetch(`${apiPath}/switch/?id=${modelId}`)
|
||||
.then(response => response.json())
|
||||
.then(result => {
|
||||
loadModel(result.model.id);
|
||||
});
|
||||
}
|
||||
|
||||
function coverPosition(pos) {
|
||||
document.getElementById("cover").style.bottom = pos;
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user