How the Player Cooldown System Works in PHPDTS: `$coldtimeon` and `$rmcdtime` Explained

The player cooldown system in amarillonmc/phpdts uses a global boolean flag $coldtimeon to enable action throttling, while $rmcdtime dynamically calculates the remaining milliseconds a player must wait before their next command.

The battle-royale engine implements a global action cooldown mechanism to prevent command spam and regulate game pace. Two variables control this system: $coldtimeon acts as the master switch defined in configuration files, and $rmcdtime represents the real-time remaining cooldown calculated on each request. This architecture allows server administrators to toggle cooldowns globally or customize timings per ruleset.

Enabling the Cooldown System with $coldtimeon

The variable $coldtimeon serves as the primary toggle for the entire cooldown mechanism. Defined in gamedata/cache/gamecfg_1.php, this boolean flag determines whether player actions incur mandatory waiting periods.

When set to 1, the system enforces cooldowns on all player commands. When set to 0, actions execute instantly without delay. Each ruleset can maintain its own configuration, allowing different maps to run with distinct timing rules.

// File: gamedata/cache/gamecfg_1.php
$coldtimeon = 1;          // Enable cooldown system
$movecoldtime = 821;      // Base cooldown for movement (ms)
$searchcoldtime = 821;    // Base cooldown for searching (ms)
$itemusecoldtime = 821;   // Base cooldown for item usage (ms)

Ruleset-specific copies located in gamedata/ruleset/*/cache/gamecfg_1.php override these defaults, enabling per-map customization.

Calculating Action-Specific Cooldowns

When $coldtimeon is active, command.php assigns a base cooldown value ($cmdcdtime) based on the specific command executed. The processor examines the command type and selects the corresponding timing constant from the configuration.

// Inside command.php action handlers
if ($coldtimeon) {
    if ($command == 'move') {
        $cmdcdtime = $movecoldtime;
    } elseif ($command == 'search') {
        $cmdcdtime = $searchcoldtime;
    } elseif ($command == 'itemuse') {
        $cmdcdtime = $itemusecoldtime;
    }
}

After determining the cooldown duration, the system decomposes the millisecond value into seconds and milliseconds for storage.

$cdsec  = floor($cmdcdtime / 1000);   // Whole seconds component
$cdmsec = $cmdcdtime % 1000;          // Remaining milliseconds
$cdtime = $cmdcdtime;                 // Total milliseconds for reference

These values persist in the player status array ($psdata) and commit to the database, ensuring cooldowns survive page reloads.

Persisting and Computing Remaining Time ($rmcdtime)

On every request, game.php and command.php calculate $rmcdtime by comparing the stored deadline against the current server timestamp. The calculation reconstructs the absolute deadline ($cdover) in milliseconds since epoch.

// Calculation logic from game.php
$cdover = $psdata['cdsec'] * 1000 + $psdata['cdmsec'] + $psdata['cdtime'];
$nowmtime = $timestamp * 1000;  // Current time in milliseconds

if ($nowmtime >= $cdover) {
    $rmcdtime = 0;              // Cooldown expired
} else {
    $rmcdtime = $cdover - $nowmtime;  // Remaining milliseconds
}

If the current time exceeds the deadline, $rmcdtime becomes 0, indicating the player may act immediately. Otherwise, it contains the exact milliseconds remaining until the next valid action.

Displaying the Timer to Players

When $rmcdtime exceeds zero, the engine injects a JavaScript countdown into the game log. Both game.php and command.php append the timer HTML when the cooldown is active and the player is alive.

if ($hp > 0 && $coldtimeon && $showcoldtimer && $rmcdtime) {
    $log .= "行动冷却时间：<span id=\"timer\" class=\"yellow\">0.0</span>秒"
          . "<script type=\"text/javascript\">"
          . "demiSecTimerStarter($rmcdtime);"
          . "</script><br>";
}

The front-end function demiSecTimerStarter, defined in include/game.func.php, initializes a client-side countdown that updates the <span id="timer"> element every 500 milliseconds until $rmcdtime reaches zero.

Summary

• $coldtimeon acts as the master boolean switch in gamedata/cache/gamecfg_1.php, enabling or disabling the entire cooldown mechanism.
• command.php assigns action-specific base times ($movecoldtime, $searchcoldtime, etc.) to $cmdcdtime based on the executed command.
• Player status fields (cdsec, cdmsec, cdtime) store the cooldown deadline in the database across requests.
• $rmcdtime is calculated in game.php by subtracting the current timestamp from the stored deadline, yielding the remaining milliseconds.
• JavaScript injection via demiSecTimerStarter provides real-time visual feedback when cooldowns are active.

Frequently Asked Questions

Where is $coldtimeon defined in the PHPDTS codebase?

The variable is defined in gamedata/cache/gamecfg_1.php as a boolean integer. Ruleset-specific variants exist in gamedata/ruleset/*/cache/gamecfg_1.php, allowing different game modes to independently configure cooldown availability.

How does $rmcdtime calculate the remaining cooldown?

$rmcdtime derives from the stored deadline ($cdover) reconstructed from cdsec, cdmsec, and cdtime fields in the player status array. The formula $cdover - ($timestamp * 1000) yields the remaining milliseconds, clamped to zero if the deadline has passed.

Can different game rulesets have different cooldown settings?

Yes. Each ruleset maintains its own gamecfg_1.php in gamedata/ruleset/{rulename}/cache/. Administrators can set $coldtimeon = 1 for competitive modes while disabling it ($coldtimeon = 0) for casual or debug scenarios.

What happens if $coldtimeon is set to 0?

When disabled, command.php skips all cooldown assignments and checks. Player commands execute immediately without populating cdsec, cdmsec, or cdtime, effectively bypassing the $rmcdtime calculation and allowing instant successive actions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}