Create papermc-dev-docs.md

games/minecraft/develoment/server/yuemi-spigot/yuemi-spigot-docs.md

@@ -0,0 +1,264 @@
+```markdown
+# YueMi-Spigot Knowledge Base
+
+This knowledge base provides documentation for the YueMi-Spigot Minecraft server software.
+
+## Table of Contents
+
+- [Configuration](#configuration)
+- [Commands](#commands)
+- [Features](#features)
+
+## Configuration
+
+This section covers the various configuration options available in YueMi-Spigot.
+
+### Configuration Files
+
+The following configuration files are available:
+
+-   [Knockback Configuration](#knockback-configuration)
+-   [Mobs Configuration](#mobs-configuration)
+-   [Spawner Configuration](#spawner-configuration)
+-   [System Configuration](#system-configuration)
+-   [Theme Configuration](#theme-configuration)
+-   [World Configuration](#world-configuration)
+
+### Knockback Configuration
+
+Customize the Minecraft knockback mechanism.
+
+**Fields:**
+
+-   `friction`: Global friction applied post-knockback. Default: `2.0`
+-   `horizontal`: Base horizontal knockback multiplier. Default: `0.6`
+-   `vertical`: Base vertical knockback multiplier. Default: `0.35`
+-   `verticalLimit`: Maximum vertical velocity after knockback. Default: `0.4`
+-   `extraHorizontal`: Additional horizontal knockback during sprinting. Default: `0.425`
+-   `extraVertical`: Additional vertical knockback during sprinting. Default: `0.085`
+
+### Mobs Configuration
+
+Customize mob-related features.
+
+**Fields:**
+
+-   `entityCollisions`: Disables entity-to-entity collision calculations. Default: `false`
+-   `mobAI`: Disables AI pathfinding and logic for mobs. Default: `false`
+-   `Optimize-Mobs`: Enables various internal performance improvements. Default: `true`
+
+### Spawner Configuration
+
+Customize the custom spawner system.
+
+**Fields:**
+
+-   `Custom-Spawner-System`: Enables the optimized internal spawner logic. Default: `true`
+-   `NeedPlayersNearby`: Requires nearby players for spawners to activate. Default: `true`
+-   `SpawnerParticles`: Enables particle effects for active spawners. Default: `false`
+-   `SpawnRadius`: Radius around the spawner to place mobs. Default: `4`
+-   `PlayerAFKRadius`: Maximum distance for AFK detection. Default: `10`
+-   `SpawnDelay`: Delay before attempting to spawn again. Default: `20`
+-   `MinimumSpawnTicks`: Minimum interval (in ticks) between spawns. Default: `200`
+-   `MaximumSpawnTicks`: Maximum interval (in ticks) between spawns. Default: `600`
+-   `SpawnCount`: Number of mobs to attempt spawning each cycle. Default: `4`
+-   `MaxNearbyEntities`: Max number of similar entities before halting spawn. Default: `6`
+
+### System Configuration
+
+Explains the system mechanism.
+
+**Fields:**
+
+-   `useVirtualThread`: Controls whether YueMi-Spigot uses Java Virtual Threads (Project Loom) for its async scheduler. Default: `true`
+-   `licenseKeys`: Placeholder for licensing or authentication key.
+
+### Theme Configuration
+
+Customize the server's theme.
+
+**Fields:**
+
+-   `mainColor`: Primary accent color. Default: `&b`
+-   `secondaryColor`: Secondary/default text color. Default: `&f`
+-   `titleColor`: Color for UI titles and headers. Default: `&3&l`
+-   `spigotName`: The display name of your server fork. Default: `YueMi`
+
+### World Configuration
+
+Customize world-related features.
+
+**Fields:**
+
+-   `AllowSignColoring`: Allows players to color signs using color codes. Default: `true`
+-   `RightClickEditSign`: Right-clicking a sign allows for live editing. Default: `false`
+-   `BetterMending`: Enhances the behavior of Mending enchantment. Default: `true`
+-   `OptimizePrecipitation`: Optimize Detect Ice/Snow Chunks Logic. Default: `true`
+-   `OptimizeChunkHolders`: Cache Frequently Requested Chunk Holders. Default: `true`
+-   `OptimizeMinecarts`: Handle how minecarts hitbox ticking. Default: `true`
+-   `OptimizeSuffocation`: Handle suffocation mechanics. Default: `true`
+-   `entity-load-chunks`: Decide What entities can trigger load chunk events.
+    -   `tntLoadChunks`: Default: `false`
+    -   `fallingBlocksLoadChunks`: Default: `false`
+    -   `enderpearlsLoadChunks`: Default: `false`
+    -   `tridentsLoadChunks`: Default: `false`
+
+## Commands
+
+This section details the available commands in YueMi-Spigot.
+
+### Command Categories
+
+-   [Admin Commands](#admin-commands)
+-   [System Commands](#system-commands)
+
+### Admin Commands
+
+List and usage of admin commands.
+
+**Logs Command:**
+
+Upload `latest.log` or selected logs to McLo.gs API.
+
+| Command           | Description                     | Permissions        |
+|-------------------|---------------------------------|--------------------|
+| `/logs`          | Upload `latest.log`             | `yuemi.admin.logs` |
+| `/logs <filename>` | Upload selected logs            | `yuemi.admin.logs` |
+| `/logs list`     | List all available logs         | `yuemi.admin.logs` |
+
+**Set Max Slots Command:**
+
+Set the maximum number of players that can join the server.
+
+| Command       | Description                | Permissions          |
+|---------------|----------------------------|----------------------|
+| `/setslots`    | Set Server Max Player Slots | `yuemi.admin.setslots` |
+
+### System Commands
+
+List and usage of system commands.
+
+**Themes Command:**
+
+Set the theme colors and display name for the server's UI.  All subcommands require the `yuemi.system.theme` permission.
+
+| Command                      | Description                        | Permissions          |
+|------------------------------|------------------------------------|----------------------|
+| `/themes setmain <color>`     | Set the main color of the theme     | `yuemi.system.theme` |
+| `/themes setsecondary <color>`| Set the secondary color of the theme| `yuemi.system.theme` |
+| `/themes settitle <color>`   | Set the title color of the theme    | `yuemi.system.theme` |
+| `/themes setspigotname <name>`| Set the Spigot server name displayed in the UI | `yuemi.system.theme` |
+
+**Knockback Command:**
+
+Configure the server's knockback behavior. All subcommands require the `yuemi.system.knockback` permission.
+
+| Command                         | Description                                | Permissions             |
+|---------------------------------|--------------------------------------------|-------------------------|
+| `/knockback setfriction <value>`    | Set friction used in knockback calculations | `yuemi.system.knockback` |
+| `/knockback sethorizontal <value>` | Set horizontal knockback multiplier        | `yuemi.system.knockback` |
+| `/knockback setvertical <value>`  | Set vertical knockback multiplier          | `yuemi.system.knockback` |
+| `/knockback setverticallimit <value>`| Set vertical maximum knockback limit       | `yuemi.system.knockback` |
+| `/knockback setextrahorizontal <value>`| Set extra horizontal knockback component    | `yuemi.system.knockback` |
+| `/knockback setextravertical <value>`| Set extra vertical knockback component      | `yuemi.system.knockback` |
+
+## Features
+
+This section details the features of YueMi-Spigot.
+
+-   [Virtual Threads](#virtual-threads)
+-   [Plugins Grouping](#plugins-grouping)
+-   [Sign Coloring System](#sign-coloring-system)
+
+### Virtual Threads
+
+Explains the `system.useVirtualThreads` option and its trade-offs.
+
+**Comparison Table:**
+
+| Feature                      | Virtual Threads (YueMi)        | Thread Pool (Paper)        |
+|------------------------------|--------------------------------|----------------------------|
+| Minimum Threads Alive        | 0 (spawn on demand)            | 4 core threads kept alive |
+| Idle Thread Keep-Alive       | ~10s                           | ~30s                           |
+| Scaling Behavior             | Up to tens of thousands of tasks| Limited by physical threads |
+| Best For                     | I/O-bound tasks (DB, HTTP, disk)| Mixed workloads, stable under CPU load |
+| Memory Overhead per Thread   | Very low (KBs)                 | Higher (MBs)                 |
+| CPU-bound Workloads          | No real advantage               | Predictable & stable         |
+| Compatibility                | Newer (Java 21+, may expose plugin issues) | Mature and widely tested |
+| Resource Efficiency          | Very high                      | Moderate                     |
+
+**Pros of Virtual Threads:**
+
+-   Extremely lightweight; can handle massive concurrency.
+-   Great for async plugins that perform database, network, or file operations.
+-   Frees server owners from tuning thread pool sizes.
+
+**Trade-offs:**
+
+-   Still a newer JVM feature; some plugins may not be fully compatible.
+-   No performance boost for CPU-heavy async tasks.
+-   May reveal concurrency bugs in poorly written plugins.
+
+### Plugins Grouping
+
+YueMi Spigot provides an extended plugin loading system.  Supports multiple plugin directories using a wildcard folder system.
+
+**Plugin Folder Rules:**
+
+-   The main plugin directory `plugins/` must exist.
+-   The system also recognizes extra plugin directories: Any folder following the pattern `plugins-*` (e.g., `plugins-dev/`, `plugins-test/`, `plugins-extra/`).
+-   All directory names are case-insensitive but are normalized to lowercase internally.
+
+**Loading Order:**
+
+-   Scan for all directories matching `plugins/` and `plugins-*`.
+-   Normalize folder names to lowercase.
+-   Load plugins from each directory in that order.
+
+**Example Usage:**
+
+```
+plugins/
+plugins-test/
+plugins-libraries/
+plugins-mmosets/
+```
+
+**Use Cases:**
+
+-   Organized grouping: Group plugins by function (e.g., `plugins-minigames/`, `plugins-essentials/`).
+-   Safer testing.
+
+**Notes:**
+
+-   Plugins in different directories still share the same classloader rules as normal.
+-   Duplicate plugins across folders may cause conflicts.
+-   Always keep folder names lowercase for consistency.
+-   This feature is experimental; some plugins may not support it.
+
+### Sign Coloring System
+
+This page explains the sign coloring and formatting system in YueMi-Spigot, and how permissions control access to different styles.
+
+**Overview:**
+
+Players can customize the text on signs using the `&` character followed by a color or formatting code. YueMi-Spigot translates these into Minecraft's native section sign codes (`§`).
+
+Example: `&cHello &lWorld` becomes Hello (in red) and World (in bold).
+
+**Permission Nodes:**
+
+| Permission        | Description                                                                                                 |
+|-------------------|-------------------------------------------------------------------------------------------------------------|
+| `yuemi.sign.color`| Allows use of `&0` – `&f` color codes (black ➞ white, plus standard colors).                                  |
+| `yuemi.sign.style`| Allows use of `&l`, `&o`, `&m`, `&n` formatting codes (bold, italic, strikethrough, underline).                |
+| `yuemi.sign.magic`| Allows use of `&k` "magic" obfuscated text effect.                                                              |
+
+**Examples:**
+
+| Input Text   | Permission Required | Result                                   |
+|--------------|---------------------|------------------------------------------|
+| `&aWelcome`   | `yuemi.sign.color`  | Welcome                                  |
+| `&lBold Text` | `yuemi.sign.style`  | Bold Text                                |
+| `&kSecret`   | `yuemi.sign.magic`  | ▒▒▒▒▒▒ (random obfuscated characters) |
+```