From 125dbfc5923817b9ff622082df51f9e573057653 Mon Sep 17 00:00:00 2001
From: SikongJueluo <1822250894@qq.com>
Date: Wed, 12 Nov 2025 21:02:51 +0800
Subject: [PATCH] docs(areacontrol): update

---
 README.md              |  2 +-
 README_zh.md           |  2 +-
 docs/areacontrol_en.md | 15 +++++++++------
 docs/areacontrol_zh.md | 15 +++++++++------
 4 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 19ce37d..3869020 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ A powerful area management script that allows administrators to define a special
     - Automatically switches the game mode (e.g., from Survival to Adventure/Spectator) when a player enters/leaves the defined area.
     - Configurable whitelist to exempt certain players (like OPs) from the rules.
     - Sets a uniform item usage cooldown for all players within the zone.
-    - Provides a rich set of in-game commands to configure the zone's center, radius, target game mode, and more in real-time.
+    - Provides a rich set of in-game commands to configure the zone's boundaries, target game mode, and more in real-time.
 - **Design Philosophy**:
     - **High Performance**: Built with an event-driven architecture and a throttled checking mechanism to minimize impact on server performance.
     - **Persistence**: All configurations are saved automatically and persist through server restarts.
diff --git a/README_zh.md b/README_zh.md
index 645b75f..83aee21 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -14,7 +14,7 @@
     - 玩家进入/离开指定区域时，自动切换游戏模式（如冒险/旁观模式与生存模式的切换）。
     - 可配置的白名单，允许特定玩家（如OP）不受影响。
     - 为区域内玩家设置统一的物品使用冷却。
-    - 提供丰富的游戏内命令，用于实时配置区域中心、半径、目标模式等。
+    - 提供丰富的游戏内命令，用于实时配置区域边界、目标模式等。
 - **设计理念**:
     - **高性能**: 采用事件驱动和降频检查机制，最大限度地减少对服务器性能的影响。
     - **持久化**: 所有配置都会自动保存，服务器重启后不会丢失。
diff --git a/docs/areacontrol_en.md b/docs/areacontrol_en.md
index db2e9c7..858c1de 100644
--- a/docs/areacontrol_en.md
+++ b/docs/areacontrol_en.md
@@ -48,12 +48,15 @@ You can manage the script in-game using the `/areacontrol` command series. All c
 -   `/areacontrol toggleCooldown`
     -   **Function**: Enable or disable the item cooldown feature.
 
--   `/areacontrol setcenter`
-    -   **Function**: Set your current position as the center of the zone.
+-   `/areacontrol setCircularArea <radius>`
+    -   **Function**: Set your current position as the center of the zone and define its radius.
+    -   **Example**: `/areacontrol setCircularArea 100`
 
--   `/areacontrol setradius <radius>`
-    -   **Function**: Set the radius of the zone.
-    -   **Example**: `/areacontrol setradius 100`
+-   `/areacontrol setAreaPos1`
+    -   **Function**: Set the first corner of the area to your current position.
+
+-   `/areacontrol setAreaPos2`
+    -   **Function**: Set the second corner of the area to your current position, defining a rectangular zone.
 
 -   `/areacontrol setmode <adventure|spectator>`
     -   **Function**: Set the game mode players will be switched to upon entering the zone.
@@ -112,7 +115,7 @@ PlayerEvents.tick((event) => {
 #### State Caching and Boundary Detection
 To avoid unnecessary operations, the script uses state caching and fast boundary detection.
 
-1.  **Boundary Pre-calculation**: When `center` or `radius` changes, the script pre-calculates the area's `minX`, `maxX`, `minZ`, `maxZ` boundaries.
+1.  **Boundary Pre-calculation**: When the area is defined (either as a circular zone with `setCircularArea` or a rectangular zone with `setAreaPos1`/`setAreaPos2`), the script pre-calculates the area's `minX`, `maxX`, `minZ`, `maxZ` boundaries.
 2.  **Fast Detection**: When checking a player's position, it only needs to compare the player's X and Z coordinates with the pre-calculated boundaries, which is an efficient O(1) operation.
 3.  **State Caching**: A global object named `playerStates` caches whether each player is inside the area (as a boolean). The core logic, like switching game modes, is executed only when the player's current state differs from the cached state (i.e., the player has crossed the area boundary). The cache is then updated.
 
diff --git a/docs/areacontrol_zh.md b/docs/areacontrol_zh.md
index a3e8d0c..2c65f47 100644
--- a/docs/areacontrol_zh.md
+++ b/docs/areacontrol_zh.md
@@ -48,12 +48,15 @@
 -   `/areacontrol toggleCooldown`
     -   **功能**：启用或禁用物品冷却功能。
 
--   `/areacontrol setcenter`
-    -   **功能**：将您当前的位置设置为区域的中心点。
+-   `/areacontrol setCircularArea <半径>`
+    -   **功能**：将您当前的位置设置为区域的中心点，并定义其半径。
+    -   **示例**：`/areacontrol setCircularArea 100`
 
--   `/areacontrol setradius <半径>`
-    -   **功能**：设置区域的半径。
-    -   **示例**：`/areacontrol setradius 100`
+-   `/areacontrol setAreaPos1`
+    -   **功能**：将您当前的位置设置为区域的第一个角点。
+
+-   `/areacontrol setAreaPos2`
+    -   **功能**：将您当前的位置设置为区域的第二个角点，从而定义一个矩形区域。
 
 -   `/areacontrol setmode <adventure|spectator>`
     -   **功能**：设置玩家进入区域后切换到的游戏模式。
@@ -112,7 +115,7 @@ PlayerEvents.tick((event) => {
 #### 状态缓存与边界检测
 为避免不必要的操作，脚本采用状态缓存和快速边界检测。
 
-1.  **边界预计算**：当 `center` 或 `radius` 改变时，脚本会预先计算出区域的 `minX`, `maxX`, `minZ`, `maxZ` 边界。
+1.  **边界预计算**：当区域被定义时（无论是通过 `setCircularArea` 定义的圆形区域，还是通过 `setAreaPos1`/`setAreaPos2` 定义的矩形区域），脚本会预先计算出区域的 `minX`, `maxX`, `minZ`, `maxZ` 边界。
 2.  **快速检测**：在检查玩家位置时，只需将玩家的 X 和 Z 坐标与预计算的边界进行比较，这是一个 O(1) 的高效操作。
 3.  **状态缓存**：一个名为 `playerStates` 的全局对象缓存着每个玩家是否在区域内的布尔值。只有当玩家的当前状态与缓存状态不一致时（即玩家穿越了区域边界），脚本才会执行游戏模式切换等核心逻辑，并更新缓存。