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

> Discover how PHPDTS implements player cooldowns using $coldtimeon for action throttling and $rmcdtime for dynamic wait time calculation, streamlining command execution.

- Repository: [Nemo Ma/phpdts](https://github.com/amarillonmc/phpdts)
- Tags: deep-dive
- Published: 2026-02-24

---

**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`](https://github.com/amarillonmc/phpdts/blob/main/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.

```php
// 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`](https://github.com/amarillonmc/phpdts/blob/main/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.

```php
// 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.

```php
$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`](https://github.com/amarillonmc/phpdts/blob/main/game.php) and [`command.php`](https://github.com/amarillonmc/phpdts/blob/main/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.

```php
// 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`](https://github.com/amarillonmc/phpdts/blob/main/game.php) and [`command.php`](https://github.com/amarillonmc/phpdts/blob/main/command.php) append the timer HTML when the cooldown is active and the player is alive.

```php
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`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/gamedata/cache/gamecfg_1.php), enabling or disabling the entire cooldown mechanism.
- **[`command.php`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/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.