{"id":13439842,"url":"https://github.com/stevenjoezhang/live2d-widget","last_synced_at":"2025-05-14T13:00:28.060Z","repository":{"id":37333722,"uuid":"140525341","full_name":"stevenjoezhang/live2d-widget","owner":"stevenjoezhang","description":"把萌萌哒的看板娘抱回家 (ノ≧∇≦)ノ | Live2D widget for web platform","archived":false,"fork":false,"pushed_at":"2025-05-07T00:55:01.000Z","size":1060,"stargazers_count":9597,"open_issues_count":22,"forks_count":2485,"subscribers_count":85,"default_branch":"master","last_synced_at":"2025-05-07T12:45:09.931Z","etag":null,"topics":["javascript-plugin","live2d"],"latest_commit_sha":null,"homepage":"https://zhangshuqiao.org/2018-07/在网页中添加Live2D看板娘","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stevenjoezhang.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-07-11T05:22:00.000Z","updated_at":"2025-05-07T09:12:11.000Z","dependencies_parsed_at":"2023-02-12T03:10:27.909Z","dependency_job_id":"58b0a96f-fe7a-48bc-8d47-68750ffec5e3","html_url":"https://github.com/stevenjoezhang/live2d-widget","commit_stats":{"total_commits":142,"total_committers":3,"mean_commits":"47.333333333333336","dds":"0.014084507042253502","last_synced_commit":"bc08b5e19f2e7e20f4977046756c41ce1e98d62d"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevenjoezhang%2Flive2d-widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevenjoezhang%2Flive2d-widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevenjoezhang%2Flive2d-widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevenjoezhang%2Flive2d-widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stevenjoezhang","download_url":"https://codeload.github.com/stevenjoezhang/live2d-widget/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149597,"owners_count":22022846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript-plugin","live2d"],"created_at":"2024-07-31T03:01:17.566Z","updated_at":"2025-05-14T13:00:28.039Z","avatar_url":"https://github.com/stevenjoezhang.png","language":"JavaScript","funding_links":[],"categories":["HarmonyOS","JavaScript","游戏","TypeScript"],"sub_categories":["Windows Manager","网络服务_其他"],"readme":"# Live2D Widget\n\n![](https://forthebadge.com/images/badges/built-with-love.svg)\n![](https://forthebadge.com/images/badges/uses-html.svg)\n![](https://forthebadge.com/images/badges/made-with-javascript.svg)\n![](https://forthebadge.com/images/badges/contains-cat-gifs.svg)\n![](https://forthebadge.com/images/badges/powered-by-electricity.svg)\n![](https://forthebadge.com/images/badges/makes-people-smile.svg)\n\n[中文](README.md)\n\n## Features\n\nAdd Live2D widget to web page. Compatible with PJAX.\n\n\u003cimg src=\"demo/screenshots/screenshot-2.png\" width=\"280\"\u003e\u003cimg src=\"demo/screenshots/screenshot-3.png\" width=\"280\"\u003e\u003cimg src=\"demo/screenshots/screenshot-1.png\" width=\"270\"\u003e\n\n(Note: The character models above are for demonstration purposes only and are not included in this repository.)\n\nYou can also check out example web pages:\n\n- Check the effect in the lower left corner of [Mimi's Blog](https://zhangshuqiao.org)\n- [demo/demo.html](https://live2d-widget.pages.dev/demo/demo) to demonstrate basic functionality\n- [demo/login.html](https://live2d-widget.pages.dev/demo/login) to imitate the login interface of NPM\n\n## Usage\n\nIf 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:\n\n```html\n\u003cscript src=\"https://fastly.jsdelivr.net/npm/live2d-widgets@0/autoload.js\"\u003e\u003c/script\u003e\n```\n\nThe 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.  \nIf 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.\n\n**However, we strongly recommend configuring the widget yourself to make it more suitable for your website!**  \nIf you are interested in customizing the widget, please refer to the detailed instructions below.\n\n## Configuration\n\nYou can refer to the source code of `dist/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:\n\n| Option | Type | Default Value | Description |\n| ------ | ---- | ------------- | ----------- |\n| `waifuPath` | `string` | `https://fastly.jsdelivr.net/npm/live2d-widgets@0/waifu-tips.json` | Path to the widget resources, can be modified |\n| `apiPath` | `string` | `https://live2d.fghrsh.net/api/` | API path, optional |\n| `cdnPath` | `string` | `https://fastly.jsdelivr.net/gh/fghrsh/live2d_api/` | CDN path, optional |\n| `tools` | `string[]` | see `autoload.js` | Buttons of the loaded tools, optional |\n\nAmong 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.\n\n## Development\n\nIf 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:\n\n- `src` directory contains the TypeScript code for each component, e.g. the button and dialog box.\n- `build` directory contains files generated from the source code in `src` (please do not modify them directly!)\n- `dist` directory contains the files that can be directly used on web pages after packaging, including:\n  - `autoload.js` is used to automatically load other resources such as style sheets.\n  - `waifu-tips.js` is automatically generated by `build/waifu-tips.js` and it is not recommended to modify it directly.\n  - `waifu.css` is the style sheet for the widget.\n  - `waifu-tips.json` defines the triggering conditions (`selector`, CSS selector) and the displayed text when triggered (`text`).  \n    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.  \n    **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.**\n\nTo deploy the development testing environment of this project locally, you need to install Node.js and npm, then execute the following commands:\n\n```bash\ngit clone https://github.com/stevenjoezhang/live2d-widget.git\nnpm install\nnpm run build\n```\n\nThe 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.\n\n## Deploy\n\nAfter 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`.\n\n### Using jsDelivr CDN\n\nTo load forked repository via jsDelivr, the usage method becomes:\n\n```html\n\u003cscript src=\"https://fastly.jsdelivr.net/gh/username/live2d-widget@latest/autoload.js\"\u003e\u003c/script\u003e\n```\n\nReplace `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:\n- [Git Basics - Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)\n- [Managing releases in a repository](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)\n\n### Using Cloudflare Pages\n\nYou 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.\n\n### Self-host\n\nAlternatively, you can directly host these files on your server instead of loading them via CDN.\n\n- Clone the forked repository onto your server, or upload the local files to the website directory on the server using `ftp` or similar methods.\n- 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`.\n\nAfterwards, 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.\nIf 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:\n\n```\nhttps://example.com/path/to/live2d-widget/dist/live2d.min.js\n```\n\nthen modify the value of `live2d_path` to:\n\n```\nhttps://example.com/path/to/live2d-widget/dist/\n```\n\nMake sure to include the trailing `/` in the path.\nOnce done, add the following code to the interface where you want to add the live2d-widget:\n\n```html\n\u003cscript src=\"https://example.com/path/to/live2d-widget/autoload.js\"\u003e\u003c/script\u003e\n```\n\nThis will load the widget.\n\n## Thanks\n\n\u003ca href=\"https://www.browserstack.com/\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" height=\"80\" srcset=\"https://d98b8t1nnulk5.cloudfront.net/production/images/layout/logo-header.png?1469004780\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" height=\"80\" srcset=\"https://live.browserstack.com/images/opensource/browserstack-logo.svg\"\u003e\n    \u003cimg alt=\"BrowserStack Logo\" height=\"80\" src=\"https://live.browserstack.com/images/opensource/browserstack-logo.svg\"\u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n\n\u003e Thanks to [BrowserStack](https://www.browserstack.com/) for providing the infrastructure that allows us to test in real browsers!\n\n\u003ca href=\"https://www.jsdelivr.com\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" height=\"80\" srcset=\"https://raw.githubusercontent.com/jsdelivr/jsdelivr-media/master/white/svg/jsdelivr-logo-horizontal.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" height=\"80\" srcset=\"https://raw.githubusercontent.com/jsdelivr/jsdelivr-media/master/default/svg/jsdelivr-logo-horizontal.svg\"\u003e\n    \u003cimg alt=\"jsDelivr Logo\" height=\"80\" src=\"https://raw.githubusercontent.com/jsdelivr/jsdelivr-media/master/default/svg/jsdelivr-logo-horizontal.svg\"\u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n\n\u003e Thanks to jsDelivr for providing public CDN service.\n\nThe code is modified based on this blog post:  \nhttps://www.fghrsh.net/post/123.html\n\nThanks to [Hitokoto](https://hitokoto.cn) for providing the sentence API.\n\nWhen 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).\n\n## More\n\nFor more information, you can refer to the following links:  \nhttps://nocilol.me/archives/lab/add-dynamic-poster-girl-with-live2d-to-your-blog-02  \nhttps://github.com/xiazeyu/live2d-widget.js  \nhttps://github.com/summerscar/live2dDemo\n\nRegarding the backend API models:  \nhttps://github.com/xiazeyu/live2d-widget-models  \nhttps://github.com/xiaoski/live2d_models_collection\n\nIn addition to that, there are desktop versions available:  \nhttps://github.com/amorist/platelet  \nhttps://github.com/akiroz/Live2D-Widget  \nhttps://github.com/zenghongtu/PPet  \nhttps://github.com/LikeNeko/L2dPetForMac\n\nAnd also Wallpaper Engine:  \nhttps://github.com/guansss/nep-live2d\n\n## License\n\nReleased under the GNU General Public License v3  \nhttp://www.gnu.org/licenses/gpl-3.0.html\n\nThis 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.\n\nOfficial Live2D websites:  \nhttps://www.live2d.com/en/  \nhttps://live2d.github.io\n\nLive2D Cubism Core is provided under the Live2D Proprietary Software License.  \nhttps://www.live2d.com/eula/live2d-proprietary-software-license-agreement_en.html  \nLive2D Cubism Components are provided under the Live2D Open Software License.  \nhttp://www.live2d.com/eula/live2d-open-software-license-agreement_en.html\n\n\u003e The terms and conditions do prohibit modification, but obfuscating in `live2d.min.js` would not be considered illegal modification.\n\nhttps://community.live2d.com/discussion/140/webgl-developer-licence-and-javascript-question\n\n## Update Log\n\nOn 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:  \nhttps://www.fghrsh.net/post/170.html\n\nStarting from January 1, 2020, this project no longer depends on jQuery.\n\nStarting from November 1, 2022, this project no longer requires users to separately load Font Awesome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevenjoezhang%2Flive2d-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstevenjoezhang%2Flive2d-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevenjoezhang%2Flive2d-widget/lists"}