kubejs-utils/docs/areacontrol_en.md

areacontrol.js Script Documentation

1. Overview

AreaControl is a powerful area management tool for Minecraft servers, implemented via KubeJS. It allows administrators to define a special zone in the game world and apply specific rules to players who enter it, such as automatically switching game modes or restricting item usage.

The core design philosophy of this script is high performance and ease of use. It employs an event-driven architecture and various optimization techniques to provide stable and reliable functionality without sacrificing server performance. This document will provide a comprehensive guide from installation and usage to technical implementation.

2. Features

• Automatic Mode Switching: Automatically switches players to Adventure or Spectator mode upon entering a specified area, and back to Survival mode upon leaving.
• Flexible Whitelist: Administrators can add players to a whitelist via commands, exempting them from game mode changes. OPs are exempt by default, but this is configurable.
• Item Cooldown System: Sets a uniform item usage cooldown for all players within the zone. This feature depends on the event_register.js script.
• Real-time Toggling: Administrators can globally enable or disable all features with a single command, without restarting the server.
• High-Performance Design:
  • Event-Driven: Logic is triggered only on player login, logout, or movement, with no unnecessary polling.
  • Throttled Checks: Player position checks are throttled (defaulting to once every 3 seconds) to reduce server load, and the frequency is configurable.
  • State Caching: Core operations are executed only when a player crosses the area boundary, avoiding redundant calculations.
• Configuration Persistence: All settings (like the zone's center, radius, and whitelist) are saved automatically and persist through server restarts.
• Rich Management Commands: Provides a complete set of commands for real-time adjustment of all script parameters.

3. User Guide

This section is for server administrators, guiding you on how to install and use AreaControl.

3.1. Installation

1. Ensure your Minecraft server has the KubeJS Mod installed correctly.
2. Place the areacontrol.js script file in the server's kubejs/server_scripts/ directory.
3. (Optional) If you need to enable the Item Cooldown feature, make sure event_register.js is also installed in the kubejs/startup_scripts/ directory.
4. Restart the server or run /kubejs reload server_scripts in-game.

The script will initialize automatically upon loading.

3.2. Management Commands

You can manage the script in-game using the /areacontrol command series. All commands require administrator privileges (level 2 or higher).

• /areacontrol status

  • Function: View all current configurations and the running status of the script.

• /areacontrol toggle

  • Function: Globally enable or disable the script. When disabled, all players inside the zone will be returned to Survival mode.

• /areacontrol toggleIncludingOPs

  • Function: Toggle whether to include administrators (OPs) in the game mode management.

• /areacontrol toggleCooldown

  • Function: Enable or disable the item cooldown feature.

• /areacontrol setCircularArea <radius>

  • Function: Set your current position as the center of the zone and define its radius.
  • Example: /areacontrol setCircularArea 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.
  • Example: /areacontrol setmode spectator

• /areacontrol setcooldown <ticks>

  • Function: Set the item cooldown time in game ticks (20 ticks = 1 second).
  • Example: /areacontrol setcooldown 200 (sets a 10-second cooldown)

• /areacontrol setcheckfrequency <ticks>

  • Function: Set the frequency for checking player positions, in game ticks. A lower value is more responsive but has a higher performance cost.
  • Example: /areacontrol setcheckfrequency 40 (checks every 2 seconds)

• /areacontrol whitelist <add|remove|list> [playerName]

  • Function: Manage the whitelist. Whitelisted players are not affected by game mode changes.
  • add <playerName>: Add a player to the whitelist.
  • remove <playerName>: Remove a player from the whitelist.
  • list: List all players on the whitelist.

• /areacontrol reload

  • Function: Reload the configuration from storage.

• /areacontrol help

  • Function: Display a list of all available commands in-game.

4. Technical Implementation

This section is for developers who want to understand how it works or perform secondary development.

4.1. Script and Environment

This project is written in JavaScript and uses JSDoc comments for type hinting to enhance code readability and maintainability. No compilation step is required for development.

• Source File: kubejs/server_scripts/areacontrol.js
• Configuration File: The script's configuration is stored via KubeJS's persistent data API, typically located at saves/<world_name>/server_data/areacontrol_config.json. Manual editing of this file is not recommended.

4.2. Core Design

Event-Driven Architecture

The script avoids high-cost tick polling and instead listens for specific player events to trigger logic.

• PlayerEvents.loggedIn: When a player logs in, their position is checked and their state is initialized.
• PlayerEvents.loggedOut: When a player logs out, their cached data is cleared to prevent memory leaks.
• PlayerEvents.tick: Used with throttling. By default, it checks the player's position once every 3 seconds (60 ticks), with an adjustable frequency.

// Example: Throttled player position check
PlayerEvents.tick((event) => {
    const { player } = event;
    // Use player.age and configurable frequency for modulo operation
    if (player.age % config.checkFrequency === 0) {
        checkPlayerAreaStatus(player);
    }
});

State Caching and Boundary Detection

To avoid unnecessary operations, the script uses state caching and fast boundary detection.

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.

// playerStates caches the current state of players
let playerStates = {}; // { [playerUuid]: boolean }

function checkPlayerAreaStatus(player) {
    // ...
    const isCurrentlyInArea = isPositionInArea(pos.x, pos.z);
    const cachedState = playerStates[player.stringUuid];

    // Only perform actions when the state changes
    if (cachedState !== isCurrentlyInArea) {
        if (isCurrentlyInArea) {
            handlePlayerEnterArea(player);
        } else if (cachedState === true) {
            handlePlayerLeaveArea(player);
        }
        // Update the cache
        playerStates[player.stringUuid] = isCurrentlyInArea;
    }
}

4.3. Interaction with event_register.js

The item cooldown feature of areacontrol.js is an optional module that relies on the global event bus eventBus provided by event_register.js.

• Check on Startup: The script checks if global['eventBus'] exists during initialization.
• Graceful Degradation: If eventBus is not defined, the enableCooldown setting is forcibly set to false, and all cooldown-related features (including commands) become unavailable.
• Event Listening: If eventBus exists, the script registers a listener for the LivingEntityUseItemEvent$Finish event. When a player in the area finishes using an item, this listener is triggered and adds a cooldown to the item based on the cooldownSecs configuration.

This design allows areacontrol.js to run standalone (without item cooldowns) or in conjunction with event_register.js to provide richer functionality, achieving decoupling between modules.