{"id":48155143,"url":"https://github.com/valaxyjs/valaxy-addon-live2d","last_synced_at":"2026-04-04T17:16:46.932Z","repository":{"id":223946266,"uuid":"761600141","full_name":"valaxyjs/valaxy-addon-live2d","owner":"valaxyjs","description":"在 valaxy 集成 live2d 看板娘","archived":false,"fork":false,"pushed_at":"2025-07-15T09:48:00.000Z","size":415,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-21T11:44:04.442Z","etag":null,"topics":["live2d","valaxy","valaxy-addon"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/valaxyjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-02-22T06:10:05.000Z","updated_at":"2025-07-15T09:48:04.000Z","dependencies_parsed_at":"2024-06-25T17:05:46.911Z","dependency_job_id":"13268bd9-ec95-4af7-91cd-e20840fa7cbc","html_url":"https://github.com/valaxyjs/valaxy-addon-live2d","commit_stats":null,"previous_names":["valaxyjs/valaxy-addon-live2d"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/valaxyjs/valaxy-addon-live2d","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valaxyjs%2Fvalaxy-addon-live2d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valaxyjs%2Fvalaxy-addon-live2d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valaxyjs%2Fvalaxy-addon-live2d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valaxyjs%2Fvalaxy-addon-live2d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valaxyjs","download_url":"https://codeload.github.com/valaxyjs/valaxy-addon-live2d/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valaxyjs%2Fvalaxy-addon-live2d/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31407644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["live2d","valaxy","valaxy-addon"],"created_at":"2026-04-04T17:16:46.218Z","updated_at":"2026-04-04T17:16:46.919Z","avatar_url":"https://github.com/valaxyjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003evalaxy-addon-live2d\u003c/h1\u003e\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n\n**valaxy-addon-live2d** 是专为 Valaxy 设计的 live2d 看板娘组件。该插件基于 [pixi-live2d-display](https://github.com/guansss/pixi-live2d-display) 和 [pixi.js](https://pixijs.com/) 对 [live2d-widget](https://github.com/stevenjoezhang/live2d-widget) 进行了重构和增强，提供了更多功能和更好的模块化支持\n\n## 安装插件\n\n```bash\npnpm add valaxy-addon-live2d\n```\n\n## 基础配置\n\n在默认情况下，插件包含一些默认 `live2DCollection` 配置，详情请参见 [live2DCollection](https://github.com/valaxyjs/valaxy-addon-live2d/tree/main/constants/live2dCollection.ts)\n\n```ts\nimport { defineValaxyConfig } from 'valaxy'\nimport { addonLive2d } from 'valaxy-addon-live2d'\n\nexport default defineValaxyConfig({\n  addons: [\n    addonLive2d()\n  ],\n})\n```\n\n## 配置示例\n\n您可以选择覆盖或自定义配置。在 `live2DCollection` 中，相同模型名字会被覆盖。以下是一个简单的自定义配置示例：\n\n```ts\nimport { defineValaxyConfig } from 'valaxy'\nimport { addonLive2d } from 'valaxy-addon-live2d'\n\nexport default defineValaxyConfig({\n  addons: [\n    addonLive2d({\n      enableLive2D: ['XiaoYun', 'Tia', 'Pio'],\n      live2DCollection: {\n        XiaoYun: {\n          message: '来自云游君的小云 ~',\n          models: ['https://cdn.jsdelivr.net/npm/@yunyoujun/live2d@latest/小云.model3.json'],\n        },\n        // https://github.com/fghrsh/live2d_api\n        Tia: {\n          message: '来自 Potion Maker 的 Tia 酱 ~',\n          models: 'https://cdn.jsdelivr.net/gh/fghrsh/live2d_api/model/Potion-Maker/Tia/index.json',\n        },\n        Pio: {\n          message: '来自 Potion Maker 的 Pio 酱 ~',\n          models: 'https://cdn.jsdelivr.net/gh/fghrsh/live2d_api/model/Potion-Maker/Pio/index.json',\n        },\n      },\n    })\n  ],\n})\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e完整配置示例\u003c/summary\u003e\u003cbr\u003e\n\n```ts\nimport { defineValaxyConfig } from 'valaxy'\nimport { addonLive2d } from 'valaxy-addon-live2d'\n\nexport default defineValaxyConfig({\n  addons: [\n    addonLive2d({\n      enableLive2D: ['Tia', 'Pio', 'Type95', 'HK416'],\n      widthLimit: 290,\n      live2DCollection: {\n        Type95: {\n          models: [\n            'https://registry.npmmirror.com/weblive2d/latest/files/model/95type/95type_3702/normal/index.json',\n            'https://registry.npmmirror.com/weblive2d/latest/files/model/95type/95type_3702/destroy/index.json',\n          ],\n        },\n        HK416: {\n          models: [\n            'https://registry.npmmirror.com/weblive2d/latest/files/model/HK416/HK416_3401/destroy/index.json',\n            'https://registry.npmmirror.com/weblive2d/latest/files/model/HK416/HK416_3401/normal/index.json',\n            'https://registry.npmmirror.com/weblive2d/latest/files/model/HK416/HK416_805/normal/index.json',\n            'https://registry.npmmirror.com/weblive2d/latest/files/model/HK416/HK416_805/destroy/index.json',\n          ],\n        },\n      },\n      tools: {\n        hitokoto: {\n          visible: true,\n        },\n        asteroids: {\n          visible: true,\n        },\n      },\n      skipHello: true,\n    }),\n  ]\n})\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n## 配置 / Options\n\n### Live2dOptions\n\n| 属性名            | 类型                                                       | 默认值                                        | 说明                                                   |\n| ----------------- | ---------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------ |\n| live2DCollection  | `Live2DCollection`                                         | ---                                           | 追加 Live2D 模型集合, 根据名字进行分组                 |\n| enableLive2D      | `string[]` \\| `'all'`                                      | `'all'`                                       | 启用的 Live2D，根据名字进行选择，设置 'all' 为全部启用 |\n| live2dTips        | `Live2dTips`                                               | ---                                           | 自定义 tips, 相同配置字段会覆盖默认配置                |\n| widthLimit        | `number`                                                   | `250`                                         | 设置模型的宽度，高度将根据模型比例自动适配             |\n| safetyMargin      | `boolean`                                                  | `50`                                          | 设置安全边距，防止模型部分超出显示范围                 |\n| randomCharacter   | `boolean`                                                  | `false`                                       | 切换角色时是否进行随机选择                             |\n| randomSkin        | `boolean`                                                  | `false`                                       | 切换皮肤时是否进行随机选择                             |\n| skipHello         | `boolean`                                                  | `false`                                       | 是否禁用在控制台输出 PixiJS 的欢迎消息                 |\n| hideOnScreenSizes | `number` \\| `string` \\| `false`                            | `640`                                         | 隐藏 Live2D 响应式范围, 为 false 则不进行隐藏          |\n| tools             | `Partial\u003cRecord\u003cLive2DToolId, Partial\u003cLive2DToolConfig\u003e\u003e\u003e` | 隐藏 Live2D 响应式范围, 为 false 则不进行隐藏 |\n| debugger          | `boolean`                                                  | `false`                                       | 是否开启调试模式                                       |\n| defaultVisibility | `boolean`                                                  | `true`                                        | Live2D 默认显示状态                                    |\n| cookieExpires     | `number`                                                   | `7`                                           | Cookie 过期时间（天）                                  |\n\n### Live2D\n\n`Live2DCollection` 由多个 `Live2D` 实例组成， 如下是 `Live2D` 的配置\n\n| 属性名  | 类型                   | 默认值 | 说明                                                                                       |\n| ------- | ---------------------- | ------ | ------------------------------------------------------------------------------------------ |\n| message | `string`               | ---    | 模型加载时显示的消息                                                                       |\n| models  | `string` \\| `string[]` | ---    | 模型链接地址，当类型为 `string` 时表示单个模型链接，当类型为 `string[]` 时表示多个模型链接 |\n\n\u003e [!IMPORTANT]\n\u003e 当 models 为 string[] 时，无论 textures 数量多少，都会视为一个皮肤组。部分 Live2D 通过多个 model.json 区分皮肤以实现兼容。若 CDN 前缀为 \u003chttps://cdn.jsdelivr.net\u003e 将自动获取 github 地址补充完整 textures 列表（因多数 model.json 仅含一个 textures 项）。私有部署需手动补全 textures 配置。\n\n### Live2DToolConfig\n\n`tools` 属性用于配置 Live2D 的工具栏选项\n\n| 属性名  | 类型                                                                                                                  | 默认值 | 说明                                                              |\n| ------- | --------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------- |\n| id      | `'hitokoto'` \\| `'asteroids'` \\| `'switch-model'` \\| `'switch-texture'` \\| `'photo'` \\| `'info'` \\| `'quit'`          | ---    | 工具的唯一标识符                                                  |\n| visible | `boolean`                                                                                                             | `true` | 工具是否可见                                                      |\n| action  | `'showHitokoto'` \\| `'switchCharacter'` \\| `'switchSkin'` \\| `'captureFrame'` \\| `'toggleVisibility'` \\| `() =\u003e void` | ---    | 工具触发的动作，可以是内置动作或自定义函数                        |\n| normal  | `Live2DToolStateConfig`                                                                                               | ---    | Live2D 可见状态下的工具样式配置                                   |\n| hidden  | `Live2DToolStateConfig`                                                                                               | ---    | Live2D 隐藏状态下的工具样式配置（仅对 toggleVisibility 动作有效） |\n\n### Live2DToolStateConfig\n\n工具状态样式配置：\n\n| 属性名  | 类型     | 默认值 | 说明                     |\n| ------- | -------- | ------ | ------------------------ |\n| label   | `string` | ---    | 工具显示的文本标签       |\n| bgColor | `string` | ---    | 工具的背景颜色（CSS 值） |\n\n### 预定义工具列表\n\n以下是可用的工具 ID 及其对应的默认行为：\n\n| 工具 ID          | 默认动作           | 说明                                     |\n| ---------------- | ------------------ | ---------------------------------------- |\n| `hitokoto`       | `showHitokoto`     | 一言 (需安装 valaxy-addon-hitokoto 插件) |\n| `asteroids`      | -                  | 小飞机游戏                               |\n| `switch-model`   | `switchCharacter`  | 切换角色模型                             |\n| `switch-texture` | `switchSkin`       | 切换皮肤                                 |\n| `photo`          | `captureFrame`     | Live2D 截图                              |\n| `info`           | -                  | 项目地址                                 |\n| `quit`           | `toggleVisibility` | 隐藏/显示 Live2D 模型                    |\n\n## TODO\n\n- [x] 优化 Live2D 拍照工具，防止人物闪烁\n- [x] 兼容 `valaxy-addon-hitokoto` 一言插件\n- [ ] 为单个人物提供独立的 tips 配置\n- [x] 优化人物交互的 tips\n\u003c!-- - [ ] 支持更多的 CDN 纹理地址 url 生成 --\u003e\n- [ ] 添加默认人物交互，并增加是否禁用默认交互的配置项\n\u003c!-- - [ ] 为单个人物配置画布偏移量，防止部分模型偏移 --\u003e\n- [ ] 添加更多工具样式\n- [x] 完善工具列表的更多配置项\n- [ ] 添加 Live2D 模型声音配置\n\n## 其他\n\n参考或借鉴如下项目\n\n- [Live2D Widget](https://github.com/stevenjoezhang/live2d-widget)\n- [live2d](https://github.com/Fog-Forest/live2d)\n- [live2d-viewer-web](https://github.com/guansss/live2d-viewer-web)\n\n相关资源：\n\n- [Live2D API](https://github.com/fghrsh/live2d_api)\n- [live2d-widget-models](https://github.com/evrstr/live2d-widget-models)\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/valaxy-addon-live2d?style=flat\u0026colorA=18181B\u0026colorB=9333ea\n[npm-version-href]: https://npmjs.com/package/valaxy-addon-live2d\n[npm-downloads-src]: https://img.shields.io/npm/dm/valaxy-addon-live2d.svg?style=flat\u0026colorA=18181B\u0026colorB=9333ea\n[npm-downloads-href]: https://npm.chart.dev/valaxy-addon-live2d\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalaxyjs%2Fvalaxy-addon-live2d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvalaxyjs%2Fvalaxy-addon-live2d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalaxyjs%2Fvalaxy-addon-live2d/lists"}