Merge pull request #167 from m1sk9/docs/Update-v1-docsv1.0.0

docs: Update v1 Document

6 files changed, 483 insertions, 0 deletions

diff --git a/website/src/en/docs/features/admin.md b/website/src/en/docs/features/admin.md
new file mode 100644
index 0000000..c3a3d2f
--- /dev/null
+++ b/website/src/en/docs/features/admin.md
@@ -0,0 +1,74 @@
+---
+layout: doc
+---
+
+# Admin Features
+
+This page covers features intended for server administrators. These features are primarily available to players with OP permissions.
+
+## Plugin Status (`/lc status`)
+
+View an overview of the plugin's operational status.
+
+```
+/lc status
+```
+
+Displayed information:
+
+- Plugin version (with Git commit hash)
+- Health status (OK / Degraded)
+- Enabled/disabled state of each feature
+- Configuration values (debug mode, update checking, language)
+- Links to GitHub, Modrinth, and documentation
+
+## Spy Mode
+
+Players with the `lunaticchat.spy` permission (default: op) can view all direct messages sent and received on the server.
+
+- Spy players see the original message before romaji conversion
+- Hover text indicates the message is a spy message
+- Spy players themselves are not included in the normal sender/recipient list
+
+## Channel Bypass
+
+Players with the `lunaticchat.channelbypass` permission (default: op) can bypass the following channel restrictions.
+
+- Cannot be kicked or banned
+- Can delete channels even without being the owner
+
+## Update Notifications
+
+When `checkForUpdates` is `true` (default), the plugin checks for new versions at startup. Players with the `lunaticchat.noticeupdate` permission (default: op) receive an update notification when they join the server.
+
+```yaml
+# config.yml
+checkForUpdates: true
+```
+
+## Debug Mode
+
+Setting `debug` to `true` enables verbose plugin logging. This is useful for troubleshooting issues or submitting bug reports.
+
+```yaml
+# config.yml
+debug: true
+```
+
+## Language Setting
+
+You can change the language of messages displayed to players. Plugin logs and console output are not affected and remain in English only.
+
+```yaml
+# config.yml
+language: "ja"   # "en" or "ja"
+```
+
+## Admin Permissions Reference
+
+| Permission | Default | Description |
+|-----------|---------|-------------|
+| `lunaticchat.spy` | op | View all direct messages |
+| `lunaticchat.channelbypass` | op | Bypass channel restrictions |
+| `lunaticchat.noticeupdate` | op | Receive update notifications |
+| `lunaticchat.command.lcv.status` | op | Use the `/lcv status` command |
diff --git a/website/src/en/docs/features/channel-chat.md b/website/src/en/docs/features/channel-chat.md
new file mode 100644
index 0000000..68d216e
--- /dev/null
+++ b/website/src/en/docs/features/channel-chat.md
@@ -0,0 +1,92 @@
+---
+layout: doc
+---
+
+# Channel Chat
+
+Create channels to separate conversations by group. To use this feature, set `features.channelChat.enabled` to `true` in `config.yml`.
+
+## Creating a Channel
+
+```
+/lc channel create <channelId> <name> [description] [isPrivate]
+```
+
+- `channelId`: A unique identifier for the channel (alphanumeric, `_`, `-` only, 3-30 characters)
+- `name`: The display name of the channel
+- `description`: A description of the channel (optional)
+- `isPrivate`: Set to `true` to make the channel private (default: `false`)
+
+The creator automatically becomes the owner.
+
+## Joining and Leaving Channels
+
+```
+/lc channel join <channelId>    # Join a channel
+/lc channel leave               # Leave the active channel
+/lc channel switch <channelId>  # Switch the active channel
+```
+
+Joining a private channel requires an invitation from the owner or a moderator.
+
+## Active Channel
+
+Players can join multiple channels, but only one channel can be active at a time. Chat messages are sent to the active channel. Use `/lc channel switch` to change the active channel.
+
+```
+/lc channel status    # Display the current active channel and list of joined channels
+```
+
+## Roles and Permissions
+
+Channels have three roles.
+
+| Role | Permissions |
+|------|-------------|
+| **OWNER** | Delete the channel, manage moderators, transfer ownership, manage members |
+| **MODERATOR** | Invite, kick, ban/unban members |
+| **MEMBER** | Participate in chat, view channel information |
+
+### Moderator Management (Owner Only)
+
+```
+/lc channel mod <playerName>         # Grant/revoke moderator permissions
+/lc channel ownership <playerName>   # Transfer ownership
+```
+
+### Member Management (Owner / Moderator)
+
+```
+/lc channel invite <playerName>   # Invite a player
+/lc channel kick <playerName>     # Kick a player
+/lc channel ban <playerName>      # Ban a player
+/lc channel unban <playerName>    # Unban a player
+```
+
+## Limit Settings
+
+You can set channel limits in `config.yml` (set to `0` for unlimited).
+
+| Setting Key | Description |
+|-------------|-------------|
+| `maxChannelsPerServer` | Maximum number of channels per server |
+| `maxMembersPerChannel` | Maximum number of members per channel |
+| `maxMembershipPerPlayer` | Maximum number of channels a player can join |
+
+## Message Logging
+
+Channel messages can be logged in NDJSON format. Files are rotated daily, and a new file with a suffix is created when `maxFileSizeMB` is exceeded.
+
+```json
+{"timestamp":"2026-04-05T14:23:45.123Z","playerId":"550e8400-...","playerName":"Steve","channelId":"general","message":"Hello!"}
+```
+
+See the `features.channelChat.messageLogging` section on the [Configuration page](/en/docs/configuration) for logging settings.
+
+## Bypass Permission
+
+Players with the `lunaticchat.channelbypass` permission (default: op) are protected from kicks and bans, and can force-delete channels.
+
+## Message Format
+
+The display format for channel messages can be customized via `messageFormat.channelMessageFormat` in `config.yml`. See [Message Format](/en/docs/reference/message-format) for details.
diff --git a/website/src/en/docs/features/direct-message.md b/website/src/en/docs/features/direct-message.md
new file mode 100644
index 0000000..7a88ecd
--- /dev/null
+++ b/website/src/en/docs/features/direct-message.md
@@ -0,0 +1,52 @@
+---
+layout: doc
+---
+
+# Direct Message
+
+Send and receive private 1-on-1 messages between players.
+
+## Basic Usage
+
+### Sending a Message
+
+```
+/tell <player> <message>
+```
+
+Aliases: `/t`, `/msg`, `/m`, `/w`, `/whisper`
+
+Sends a direct message to the specified player. Clicking on a received message will auto-fill the reply command to the sender.
+
+### Quick Reply
+
+```
+/reply <message>
+```
+
+Alias: `/r`
+
+Replies to the last player who sent you a message. If there is no such player, the message is sent to the last player you messaged.
+
+To use quick reply, `features.quickReplies.enabled` must be `true` (default) in `config.yml`.
+
+## Notification Settings
+
+Players can individually control the sound notification when receiving direct messages.
+
+```
+/lc settings notice on     # Enable notifications
+/lc settings notice off    # Disable notifications
+```
+
+## Integration with Japanese Conversion
+
+When [Japanese Conversion](/en/docs/features/japanese-conversion) is enabled, direct message content is also automatically converted to Japanese. Conversion follows each player's `japanese` setting.
+
+## Spy Feature
+
+Players with the `lunaticchat.spy` permission (default: op) can view all direct messages on the server. Spy players see the original message before conversion.
+
+## Message Format
+
+The display format for direct messages can be customized via `messageFormat.directMessageFormat` in `config.yml`. See [Message Format](/en/docs/reference/message-format) for details.
diff --git a/website/src/en/docs/features/japanese-conversion.md b/website/src/en/docs/features/japanese-conversion.md
new file mode 100644
index 0000000..3bcd52b
--- /dev/null
+++ b/website/src/en/docs/features/japanese-conversion.md
@@ -0,0 +1,62 @@
+---
+layout: doc
+---
+
+# Japanese Conversion
+
+Automatically converts chat messages typed in romaji into Japanese. To use this feature, set `features.japaneseConversion.enabled` to `true` in `config.yml`.
+
+## How Conversion Works
+
+Conversion is performed in two stages.
+
+1. **Romaji to Hiragana**: The plugin's built-in Trie-based conversion engine converts romaji to hiragana
+2. **Hiragana to Kanji/Katakana**: The Google IME API converts hiragana into natural Japanese
+
+### Conversion Example
+
+```
+Input:       konnichiha sekai
+Stage 1:     こんにちは せかい
+Stage 2:     こんにちは 世界
+```
+
+## Conversion Targets
+
+- Normal chat
+- Direct messages (`/tell`, `/reply`)
+- Channel chat
+
+If the input is not valid romaji (e.g., contains English words), no conversion is performed and the message is sent as-is.
+
+## Player Settings
+
+Players can individually toggle conversion on or off.
+
+```
+/lc settings japanese on     # Enable conversion
+/lc settings japanese off    # Disable conversion
+```
+
+## Cache
+
+Conversion results are cached per word. When the same word is converted again, the result is retrieved from cache instead of calling the API. The cache is periodically saved to disk as a JSON file.
+
+| Setting Key | Default | Description |
+|-------------|---------|-------------|
+| `cache.maxEntries` | `500` | Maximum number of cache entries |
+| `cache.saveIntervalSeconds` | `300` | Interval for saving to disk (seconds) |
+| `cache.filePath` | `"conversion_cache.json"` | Path to the cache file |
+
+When the cache reaches its limit, the oldest 10% of entries are automatically removed.
+
+## API Settings
+
+Settings related to the connection to the Google IME API.
+
+| Setting Key | Default | Description |
+|-------------|---------|-------------|
+| `api.timeout` | `3000` | Request timeout (milliseconds) |
+| `api.retryAttempts` | `2` | Number of retry attempts on failure |
+
+If the API times out or fails, the message is sent in hiragana as-is.
diff --git a/website/src/en/docs/features/message-logging.md b/website/src/en/docs/features/message-logging.md
new file mode 100644
index 0000000..5e929bc
--- /dev/null
+++ b/website/src/en/docs/features/message-logging.md
@@ -0,0 +1,94 @@
+---
+layout: doc
+---
+
+# Message Logging
+
+Records channel chat messages in NDJSON (Newline Delimited JSON) format to files. This feature is available when channel chat is enabled and is turned on by default.
+
+## Configuration
+
+```yaml
+# config.yml
+features:
+  channelChat:
+    enabled: true
+    messageLogging:
+      enabled: true
+      retentionDays: 30
+      maxFileSizeMB: 100
+```
+
+| Setting Key | Default | Description |
+|-------------|---------|-------------|
+| `enabled` | `true` | Enable message logging |
+| `retentionDays` | `30` | Number of days to retain log files (`0` for unlimited retention) |
+| `maxFileSizeMB` | `100` | Maximum size of a single log file (MB) |
+
+## Log File Format
+
+Log files are saved in the `plugins/LunaticChat/logs/` directory. Each line is a single JSON object.
+
+### File Naming
+
+```
+channel-messages-YYYY-MM-dd.json
+```
+
+When the file size exceeds `maxFileSizeMB`, a new file with a suffix is created.
+
+```
+channel-messages-2026-04-05.json       # Base file
+channel-messages-2026-04-05-1.json     # On size overflow
+channel-messages-2026-04-05-2.json     # On further overflow
+```
+
+### Entry Format
+
+Each line has the following JSON structure.
+
+```json
+{
+  "timestamp": "2026-04-05T14:23:45.123Z",
+  "playerId": "550e8400-e29b-41d4-a716-446655440000",
+  "playerName": "Steve",
+  "channelId": "general",
+  "message": "Hello everyone!"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timestamp` | String | ISO 8601 timestamp (UTC) |
+| `playerId` | String | Player UUID |
+| `playerName` | String | Player display name |
+| `channelId` | String | ID of the channel the message was sent to |
+| `message` | String | Message content |
+
+## File Rotation
+
+- **Daily rotation**: A new file is created when the date changes
+- **Size rotation**: Switches to a suffixed file when `maxFileSizeMB` is exceeded
+- **Automatic cleanup**: Log files older than the number of days specified by `retentionDays` are automatically deleted (no deletion when set to `0`)
+
+## Usage Examples
+
+Since the format is NDJSON, you can easily filter and aggregate logs using tools like `jq`.
+
+### Extract Messages from a Specific Channel
+
+```bash
+jq 'select(.channelId == "general")' channel-messages-2026-04-05.json
+```
+
+### Extract Messages from a Specific Player
+
+```bash
+jq 'select(.playerName == "Steve")' channel-messages-2026-04-05.json
+```
+
+### Count Messages by Channel
+
+```bash
+jq -s 'group_by(.channelId) | map({channel: .[0].channelId, count: length})' channel-messages-2026-04-05.json
+```
diff --git a/website/src/en/docs/features/velocity.md b/website/src/en/docs/features/velocity.md
new file mode 100644
index 0000000..9241e80
--- /dev/null
+++ b/website/src/en/docs/features/velocity.md
@@ -0,0 +1,109 @@
+---
+layout: doc
+---
+
+# Velocity Integration
+
+Relays global chat across multiple Paper / Folia servers via a Velocity proxy.
+
+## Setup
+
+### 1. Install the Velocity Plugin
+
+Place `LunaticChat-<version>-velocity.jar` in the Velocity `plugins/` directory and restart the proxy.
+
+### 2. Paper-Side Configuration
+
+Set the following in each Paper server's `config.yml`.
+
+```yaml
+features:
+  velocityIntegration:
+    enabled: true
+    crossServerGlobalChat: true
+    serverName: "survival"    # Must match the server name in the Velocity configuration
+```
+
+### 3. Verify the Connection
+
+```
+/lcv status
+```
+
+You can check the connection status, protocol version, Velocity plugin version, and more (permission: `lunaticchat.command.lcv.status`, default: op).
+
+## Cross-Server Global Chat
+
+When `crossServerGlobalChat` is set to `true`, player chat messages are relayed via Velocity to all other Paper servers.
+
+### Message Flow
+
+1. A player sends a chat message
+2. The Paper server sends the message to Velocity
+3. Velocity relays the message to all servers except the sender's
+4. The message is displayed to players on each server
+
+### Message Deduplication
+
+Each message is assigned a unique ID, and a cache prevents the same message from being displayed more than once. The cache size can be configured with `messageDeduplicationCacheSize` (default: `100`).
+
+## Protocol Version
+
+Compatibility between Paper and Velocity is managed by protocol version. A handshake is performed upon connection, and incompatible versions are rejected.
+
+### Version Bump Rules
+
+| Level | Example Change | Compatibility | Deployment Order |
+|-------|---------------|---------------|-----------------|
+| PATCH (1.0.0 -> 1.0.1) | Adding optional fields, new sub-channels | Fully compatible (safe with `ignoreUnknownKeys=true`) | Any order, anytime |
+| MINOR (1.0.x -> 1.1.0) | Adding required fields, changing existing sub-channel semantics | Backward compatible within `MIN_SUPPORTED_MINOR` range | **Update Velocity first** -> then update each Paper server |
+| MAJOR (1.x.x -> 2.0.0) | Wire format changes, removing/renaming sub-channels | Incompatible | **Simultaneous deployment of all servers** |
+
+### Compatibility Check
+
+Compatibility is determined during the handshake using the following rules:
+
+- **MAJOR** versions must match
+- The remote **MINOR** must be at least `MIN_SUPPORTED_MINOR` and at most the local MINOR
+- **PATCH** does not affect the compatibility check
+
+#### Example: Velocity with protocol 1.2.0 and `MIN_SUPPORTED_MINOR=1`
+
+| Paper Protocol | Result |
+|---------------|--------|
+| 1.1.x | Connection OK |
+| 1.2.x | Connection OK |
+| 1.0.x | Rejected (older than `MIN_SUPPORTED_MINOR`) |
+| 1.3.x | Rejected (newer than Velocity) |
+| 2.0.x | Rejected (MAJOR mismatch) |
+
+### Operational Cycle
+
+1. **No protocol change** -> Paper / Velocity can be deployed independently
+2. **PATCH change** -> Deploy freely from either side
+3. **MINOR change** -> Update Velocity first and set `MIN_SUPPORTED_MINOR` to allow a grace period for older Paper servers. After all Paper servers are updated, raise `MIN_SUPPORTED_MINOR`
+4. **MAJOR change** -> Simultaneous update during a maintenance window
+
+## Connection States
+
+| State | Description |
+|-------|-------------|
+| `DISCONNECTED` | Not connected |
+| `HANDSHAKING` | Handshake in progress |
+| `CONNECTED` | Connected |
+| `FAILED` | Connection failed |
+
+The handshake timeout is 5 seconds. If the handshake times out, the state becomes `FAILED`.
+
+## Configuration Reference
+
+| Setting Key | Default | Description |
+|-------------|---------|-------------|
+| `enabled` | `false` | Enable Velocity integration |
+| `crossServerGlobalChat` | `false` | Enable cross-server global chat |
+| `serverName` | `"Unknown"` | Server name displayed in cross-server chat |
+| `messageDeduplicationCacheSize` | `100` | Size of the message deduplication cache |
+
+## Message Format
+
+The display format for cross-server chat can be customized via `messageFormat.crossServerGlobalChatFormat` in `config.yml`. See [Message Format](/en/docs/reference/message-format) for details.