improve live2d

docs/user-guide/live2d.md

@@ -1,21 +1,65 @@
 # Live2D 指南
 
 :::info 概览
-要往项目中添加新的 Live2D 模型，需要完成以下三个步骤:
+要往项目中添加新的 Live2D 模型，需要完成以下三到五个步骤:
 
-1. 将 Live2D 模型文件放置到 `live2d-models` 文件夹中
-2. 在 `model_dict.json` 文件中配置模型信息
-3. 在角色配置文件 (`conf.yaml` 或者 `characters` 目录下的角色设定文件) 中指定使用的 Live2D 模型
+1. 获取 Live2D 模型 (可跳过)
+2. 给你的 Live2D 模型配置预设的表情和动作 (可跳过)
+3. 将 Live2D 模型文件放置到 `live2d-models` 文件夹中
+4. 在 `model_dict.json` 文件中配置模型信息
+5. 在角色配置文件 (`conf.yaml` 或者 `characters` 目录下的角色设定文件) 中指定使用的 Live2D 模型
 :::
 
-## 1. 放置模型文件
+## 1. 获取 Live2D 模型
+
+:::warning 关于模型版本
+目前项目使用的 pixi-live2d-display-lipsyncpatch 仅支持 Cubism2/3/4 版本的模型，暂不支持最新的 Cubism5。如
+:::
+
+如果你已经拥有了合适的 Live2D 模型，可以直接跳过这一步。
+以下是一些获取 Live2D 模型的常见渠道（欢迎补充更多来源）:
+
+- [Booth](https://booth.pm/)
+- [Bilibili](https://www.bilibili.com/)
+- [Eikanya/Live2d-model](https://github.com/Eikanya/Live2d-model)
+
+## 2. 配置 Live2D 模型
+
+:::info
+Live2D 模型的配置文件是一个包含表情、动作等多个设置项的重要文件。由于配置方法多样且较为复杂，目前这部分的教程还没有正式开工。你可以选择:
+
+1. 通过查找网络资料来学习配置方法
+2. 先跳过这部分，等对 Live2D 模型配置有更深入了解后再回来设置
+3. 如果你有相关经验，非常欢迎通过 PR 或 Issue 来帮助我们完善这部分内容
+:::
+
+由于大多数 Live2D 模型是从游戏中提取或主要用于直播，它们的表情和动作可能并不完全适合本项目的使用场景。为了获得最佳的使用体验，建议你先查看模型的配置文件（`model.json` 或 `model3.json`），并根据需要进行适当的调整，获得更好的交互体验。
+
+你可以使用以下工具来查看和调整模型：
+- Vtuber Studio
+- Live2DViewerEx Studio 
+- Live2D Cubism Viewer
+
+
+1. 查看和测试模型的表情列表
+2. 预览所有可用的动作效果
+3. 添加 Idle（空闲）动作组
+4. 创建自定义动作组
+5. 添加新的表情
+6. 制作新的动作
+
+## 3. 放置模型文件
 
 将你的 Live2D 模型文件放在 `live2d-models` 文件夹中，如图中的 `xiao`。
 
 <img src={require('./img/live2d_p1.jpg').default} style={{width: '70%'}} />
 
 
-## 2. 添加模型配置
+## 4. 添加模型配置
+
+:::caution 注意
+在模型配置中，只有 `name`（模型标识）、`url`（模型路径）和 `kScale`（缩放比例）是必填项。其他配置项如 `emotionMap`（表情映射）和 `tapMotions`（触摸动作）是可选的，不填写这些配置项会导致模型失去表情变化和动作交互的功能。
+:::
 
 在项目根目录下的 `model_dict.json` 文件中添加模型配置。以下是一个完整的配置示例：
 
@@ -55,7 +99,7 @@
 }
 ```
 
-### 2.1 基础配置
+### 4.1 基础配置
 
 | 配置项        | 说明                           | 示例值                                        |
 | ------------- | ------------------------------ | --------------------------------------------- |
@@ -67,7 +111,7 @@
 - 本地路径以 `/live2d-models/` 开头，而非 `./live2d-models/` 开头。
 - 远程 URL 需要指向有效的 `.model.json` 或 `.model3.json` 文件，比如 `https://cdn.jsdelivr.net/gh/guansss/pixi-live2d-display/test/assets/shizuku/shizuku.model.json`
 
-### 2.2 显示配置
+### 4.2 显示配置
 
 | 配置项          | 说明             | 推荐值 |
 | --------------- | ---------------- | ------ |
@@ -84,7 +128,7 @@
 
 需要注意的是，当容器大小发生变化时(如调整窗口大小、折叠/展开侧边栏或底边栏、切换显示模式等)，Live2D 模型会重置到初始位置，但会保持当前的缩放大小不变。
 
-### 2.3 待机动作配置
+### 4.3 待机动作配置
 
 Live2D 模型的动作动画一般会被分成多个动作组 (Motion Groups)。每个动作组包含一系列相关的动作动画。在 model.json 文件中，这些动作组通常定义在 `motions` 或 `Motions` 字段下。
 
@@ -98,7 +142,7 @@ Live2D 模型的动作动画一般会被分成多个动作组 (Motion Groups)。
 如果你理解模型的动作结构，也可以配置自己待机的动作组。但除非你知道自己在做什么，否则建议保持 `idleMotionGroupName` 的默认值(`idle` 或 `Idle`)。
 :::
 
-### 2.4 表情配置
+### 4.4 表情配置
 
 `emotionMap` 定义了 AI 可用的表情映射。支持两种映射方式:
 1. 使用表情索引 (数字)
@@ -184,7 +228,7 @@ AI 会使用 `[emotion]` 格式在对话中触发表情变化，例如：
 4. 根据模型的表情特点，选择合适的情绪映射
 :::
 
-### 2.5 交互动作配置
+### 4.5 交互动作配置
 
 `tapMotions` 定义了模型与鼠标交互时的动作映射。当用户点击模型时，系统会根据点击区域和配置的权重随机触发对应的动作。
 
@@ -248,7 +292,7 @@ AI 会使用 `[emotion]` 格式在对话中触发表情变化，例如：
    }
    ```
 
-## 3. 修改角色配置
+## 5. 修改角色配置
 
 在角色配置文件中指定使用的 Live2D 模型。你可以:
 
@@ -263,4 +307,4 @@ AI 会使用 `[emotion]` 格式在对话中触发表情变化，例如：
 图中的其他配置字段说明:
 - `conf_name`: 这个名称会显示在前端界面的角色选择中，你可以理解为配置名称 / 角色名称，可以随便命名。
 - `conf_uid`: 这是角色配置的唯一标识符，请确保它的值是唯一的
-:::
+:::

i18n/en/docusaurus-plugin-content-docs/current/community/contact.md

@@ -2,5 +2,5 @@
 sidebar_position: 1
 ---
 
-# 参与讨论
+# Join the Discussion
 

i18n/en/docusaurus-plugin-content-docs/current/community/contribute.md

@@ -2,4 +2,4 @@
 sidebar_position: 2
 ---
 
-# 贡献指南
+# How to contribute

i18n/en/docusaurus-plugin-content-docs/current/user-guide/live2d.md

@@ -1,20 +1,64 @@
 # Live2D Guide
 
 :::info Overview
-To add a new Live2D model to your project, you need to complete the following three steps:
+To add a new Live2D model to your project, you need to complete three to five steps:
 
-1. Place the Live2D model files in the `live2d-models` folder
-2. Configure the model information in the `model_dict.json` file
-3. Specify the Live2D model to use in the character configuration file (`conf.yaml` or character setting files in the `characters` directory)
+1. Get a Live2D model (optional)
+2. Configure expressions and motions for your Live2D model (optional)
+3. Place the Live2D model files in the `live2d-models` folder
+4. Configure model information in the `model_dict.json` file
+5. Specify the Live2D model to use in the character configuration file (`conf.yaml` or character setting files in the `characters` directory)
 :::
 
-## 1. Place Model Files
+## 1. Get a Live2D Model
+
+:::warning About Model Version
+Currently, the project uses pixi-live2d-display-lipsyncpatch which only supports Cubism2/3/4 models and does not support the latest Cubism5.
+:::
+
+If you already have a suitable Live2D model, you can skip this step.
+Here are some common sources for obtaining Live2D models (feel free to add more sources):
+
+- [Booth](https://booth.pm/)
+- [Bilibili](https://www.bilibili.com/)
+- [Eikanya/Live2d-model](https://github.com/Eikanya/Live2d-model)
+
+## 2. Configure Live2D Model
+
+:::info
+The Live2D model configuration file is an important file containing multiple settings such as expressions and motions. Since the configuration methods are diverse and complex, this part of the tutorial is not yet formally started. You can choose to:
+
+1. Learn configuration methods by searching online resources
+2. Skip this part for now and come back when you have a deeper understanding of Live2D model configuration
+3. If you have relevant experience, you're very welcome to help us improve this content through PR or Issue
+:::
+
+Since most Live2D models are extracted from games or primarily used for streaming, their expressions and motions may not be entirely suitable for this project's use case. For the best user experience, it's recommended to first check the model's configuration file (`model.json` or `model3.json`) and make appropriate adjustments as needed to achieve better interaction.
+
+You can use the following tools to view and adjust models:
+- Vtuber Studio
+- Live2DViewerEx Studio 
+- Live2D Cubism Viewer
+
+You can:
+1. View and test the model's expression list
+2. Preview all available motion effects
+3. Add Idle motion groups
+4. Create custom motion groups
+5. Add new expressions
+6. Create new motions
+
+## 3. Place Model Files
 
 Put your Live2D model files in the `live2d-models` folder, as shown in the image with the `xiao` folder.
 
 <img src={require('./img/live2d_p1.jpg').default} style={{width: '70%'}} />
 
-## 2. Add Model Configuration
+## 4. Add Model Configuration
+
+:::caution Note
+In the model configuration, only `name` (model identifier), `url` (model path), and `kScale` (scaling ratio) are required fields. Other configuration items such as `emotionMap` (expression mapping) and `tapMotions` (touch actions) are optional - not filling in these configuration items will cause the model to lose expression changes and motion interaction functionality.
+:::
 
 Add the model configuration in the `model_dict.json` file in the project root directory. Here's a complete configuration example:
 
@@ -54,7 +98,7 @@ Add the model configuration in the `model_dict.json` file in the project root di
 }
 ```
 
-### 2.1 Basic Configuration
+### 4.1 Basic Configuration
 
 | Config Item   | Description                             | Example Value                                |
 | ------------- | --------------------------------------- | -------------------------------------------- |
@@ -66,7 +110,7 @@ Add the model configuration in the `model_dict.json` file in the project root di
 - Local paths should start with `/live2d-models/`, not `./live2d-models/`
 - Remote URLs should point to valid `.model.json` or `.model3.json` files, e.g., `https://cdn.jsdelivr.net/gh/guansss/pixi-live2d-display/test/assets/shizuku/shizuku.model.json`
 
-### 2.2 Display Configuration
+### 4.2 Display Configuration
 
 | Config Item     | Description                      | Recommended Value |
 | --------------- | -------------------------------- | ----------------- |
@@ -83,7 +127,7 @@ Add the model configuration in the `model_dict.json` file in the project root di
 
 Note that when the container size changes (e.g., resizing the window, collapsing/expanding sidebars or bottom bars, switching display modes, etc.), the Live2D model will reset to its initial position but maintain its current scale.
 
-### 2.3 Idle Motion Configuration
+### 4.3 Idle Motion Configuration
 
 Live2D model motion animations are generally divided into multiple motion groups. Each motion group contains a series of related motion animations. In the model.json file, these motion groups are usually defined under the `motions` or `Motions` field.
 
@@ -97,7 +141,7 @@ The specific motion group name needs to be based on the name in the model config
 If you understand the model's motion structure, you can also configure your own idle motion group. However, unless you know what you're doing, it's recommended to keep the default value of `idleMotionGroupName` (`idle` or `Idle`).
 :::
 
-### 2.4 Expression Configuration
+### 4.4 Expression Configuration
 
 `emotionMap` defines the expression mapping available to the AI. It supports two mapping methods:
 1. Using expression indices (numbers)
@@ -183,7 +227,7 @@ The expression will persist until:
 4. Choose appropriate emotion mappings based on the model's expression characteristics
 :::
 
-### 2.5 Interaction Motion Configuration
+### 4.5 Interaction Motion Configuration
 
 `tapMotions` defines the motion mapping for model interactions with the mouse. When a user clicks on the model, the system will randomly trigger a corresponding motion based on the clicked area and the configured weights.
 
@@ -247,7 +291,7 @@ The expression will persist until:
    }
    ```
 
-## 3. Modify Character Configuration
+## 5. Modify Character Configuration
 
 Specify the Live2D model to use in the character configuration file. You can: