Configurable immunity timer (openfrontio#2763)

## Description:

Resolve discussions about stalled PR
openfrontio#2460

<img width="724" height="348" alt="image"
src="https://github.com/user-attachments/assets/c2c9fa79-cace-431a-9ca4-b3656612fa9d"
/>

Changes:
- Added a `Player::canAttackPlayer(other)` function to determine whether
a player can be attacked.
- This function is now used in most places where a fight can occur:
    - AttackExecution (land attacks)
    - Naval invasion
    - Warship fight
- Nukes can't be thrown during the truce
- Immunity only affect human players. Nations and bot will fight as
usual, and can be fought against.
- The immunity timer uses minutes in the modal window.

UI:

- The immunity phase is displayed with a timer bar at the top. This is
from the original PR, to be discussed if it's not deemed visible enough:

<img width="632" height="215" alt="image"
src="https://github.com/user-attachments/assets/f5ab9aa0-bd4f-4503-b8d6-b40b121fba65"
/>


## Please complete the following:

- [x] I have added screenshots for all UI updates
- [x] I process any text displayed to the user through translateText()
and I've added it to the en.json file
- [x] I have added relevant tests to the test directory
- [x] I confirm I have thoroughly tested these changes and take full
responsibility for any bugs introduced

## Please put your Discord username so you can be contacted if a bug or
regression is found:

IngloriousTom

---------

Co-authored-by: newyearnewphil <git@nynp.dev>

Author: DevelopingTom

index.html

@@ -451,6 +451,7 @@
     <settings-modal></settings-modal>
     <player-panel></player-panel>
     <spawn-timer></spawn-timer>
+    <immunity-timer></immunity-timer>
     <help-modal></help-modal>
     <game-info-modal></game-info-modal>
     <dark-mode-button></dark-mode-button>

resources/lang/debug.json

@@ -145,6 +145,7 @@
     "options_title": "host_modal.options_title",
     "bots": "host_modal.bots",
     "bots_disabled": "host_modal.bots_disabled",
+    "player_immunity_duration": "host_modal.player_immunity_duration",
     "disable_nations": "host_modal.disable_nations",
     "instant_build": "host_modal.instant_build",
     "random_spawn": "host_modal.random_spawn",

resources/lang/en.json

@@ -307,6 +307,7 @@
     "options_title": "Options",
     "bots": "Bots: ",
     "bots_disabled": "Disabled",
+    "player_immunity_duration": "PVP immunity duration (minutes)",
     "nations": "Nations: ",
     "disable_nations": "Disable Nations",
     "max_timer": "Game length (minutes)",

src/client/HostLobbyModal.ts

@@ -45,6 +45,8 @@ export class HostLobbyModal extends LitElement {
   @state() private gameMode: GameMode = GameMode.FFA;
   @state() private teamCount: TeamCountConfig = 2;
   @state() private bots: number = 400;
+  @state() private spawnImmunity: boolean = false;
+  @state() private spawnImmunityDurationMinutes: number | undefined = undefined;
   @state() private infiniteGold: boolean = false;
   @state() private donateGold: boolean = false;
   @state() private infiniteTroops: boolean = false;
@@ -514,7 +516,7 @@ export class HostLobbyModal extends LitElement {
                             id="end-timer-value"
                             min="0"
                             max="120"
-                            .value=${String(this.maxTimerValue ?? "")}
+                            .value=${String(this.maxTimerValue ?? 0)}
                             style="width: 60px; color: black; text-align: right; border-radius: 8px;"
                             @input=${this.handleMaxTimerValueChanges}
                             @keydown=${this.handleMaxTimerValueKeyDown}
@@ -524,6 +526,47 @@ export class HostLobbyModal extends LitElement {
                     ${translateText("host_modal.max_timer")}
                   </div>
                 </label>
+
+                <label
+                  for="spawn-immunity"
+                  class="option-card  ${this.spawnImmunity ? "selected" : ""}"
+                >
+                  <div class="checkbox-icon"></div>
+                  <input
+                    type="checkbox"
+                    id="spawn-immunity"
+                    @change=${(e: Event) => {
+                      const checked = (e.target as HTMLInputElement).checked;
+                      if (!checked) {
+                        this.spawnImmunityDurationMinutes = undefined;
+                      }
+                      this.spawnImmunity = checked;
+                      this.putGameConfig();
+                    }}
+                    .checked=${this.spawnImmunity}
+                  />
+                    ${
+                      this.spawnImmunity === false
+                        ? ""
+                        : html`<input
+                            type="number"
+                            id="spawn-immunity-duration"
+                            min="0"
+                            max="120"
+                            step="1"
+                            .value=${String(
+                              this.spawnImmunityDurationMinutes ?? 0,
+                            )}
+                            style="width: 60px; color: black; text-align: right; border-radius: 8px;"
+                            @input=${this.handleSpawnImmunityDurationInput}
+                            @keydown=${this.handleSpawnImmunityDurationKeyDown}
+                          />`
+                    }
+                  <div class="option-card-title">
+                    <span>${translateText("host_modal.player_immunity_duration")}</span>
+                  </div>
+                </label>
+                
                 <hr style="width: 100%; border-top: 1px solid #444; margin: 16px 0;" />
 
                 <!-- Individual disables for structures/weapons -->
@@ -691,6 +734,23 @@ export class HostLobbyModal extends LitElement {
     this.putGameConfig();
   }
 
+  private handleSpawnImmunityDurationKeyDown(e: KeyboardEvent) {
+    if (["-", "+", "e", "E"].includes(e.key)) {
+      e.preventDefault();
+    }
+  }
+
+  private handleSpawnImmunityDurationInput(e: Event) {
+    const input = e.target as HTMLInputElement;
+    input.value = input.value.replace(/[eE+-]/g, "");
+    const value = parseInt(input.value, 10);
+    if (Number.isNaN(value) || value < 0 || value > 120) {
+      return;
+    }
+    this.spawnImmunityDurationMinutes = value;
+    this.putGameConfig();
+  }
+
   private handleRandomSpawnChange(e: Event) {
     this.randomSpawn = Boolean((e.target as HTMLInputElement).checked);
     this.putGameConfig();
@@ -757,6 +817,9 @@ export class HostLobbyModal extends LitElement {
   }
 
   private async putGameConfig() {
+    const spawnImmunityTicks = this.spawnImmunityDurationMinutes
+      ? this.spawnImmunityDurationMinutes * 60 * 10
+      : 0;
     this.dispatchEvent(
       new CustomEvent("update-game-config", {
         detail: {
@@ -775,6 +838,9 @@ export class HostLobbyModal extends LitElement {
             randomSpawn: this.randomSpawn,
             gameMode: this.gameMode,
             disabledUnits: this.disabledUnits,
+            spawnImmunityDuration: this.spawnImmunity
+              ? spawnImmunityTicks
+              : undefined,
             playerTeams: this.teamCount,
             ...(this.gameMode === GameMode.Team &&
             this.teamCount === HumansVsNations

src/client/graphics/GameRenderer.ts

@@ -18,6 +18,7 @@ import { FxLayer } from "./layers/FxLayer";
 import { GameLeftSidebar } from "./layers/GameLeftSidebar";
 import { GameRightSidebar } from "./layers/GameRightSidebar";
 import { HeadsUpMessage } from "./layers/HeadsUpMessage";
+import { ImmunityTimer } from "./layers/ImmunityTimer";
 import { Layer } from "./layers/Layer";
 import { Leaderboard } from "./layers/Leaderboard";
 import { MainRadialMenu } from "./layers/MainRadialMenu";
@@ -234,6 +235,14 @@ export function createRenderer(
   spawnTimer.game = game;
   spawnTimer.transformHandler = transformHandler;
 
+  const immunityTimer = document.querySelector(
+    "immunity-timer",
+  ) as ImmunityTimer;
+  if (!(immunityTimer instanceof ImmunityTimer)) {
+    console.error("immunity timer not found");
+  }
+  immunityTimer.game = game;
+
   // When updating these layers please be mindful of the order.
   // Try to group layers by the return value of shouldTransform.
   // Not grouping the layers may cause excessive calls to context.save() and context.restore().
@@ -262,6 +271,7 @@ export function createRenderer(
       playerPanel,
     ),
     spawnTimer,
+    immunityTimer,
     leaderboard,
     gameLeftSidebar,
     unitDisplay,

src/client/graphics/layers/ImmunityTimer.ts

@@ -0,0 +1,93 @@
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+import { GameMode } from "../../../core/game/Game";
+import { GameView } from "../../../core/game/GameView";
+import { Layer } from "./Layer";
+
+@customElement("immunity-timer")
+export class ImmunityTimer extends LitElement implements Layer {
+  public game: GameView;
+
+  private isVisible = false;
+  private isActive = false;
+  private progressRatio = 0;
+
+  createRenderRoot() {
+    this.style.position = "fixed";
+    this.style.top = "0";
+    this.style.left = "0";
+    this.style.width = "100%";
+    this.style.height = "7px";
+    this.style.zIndex = "1000";
+    this.style.pointerEvents = "none";
+    return this;
+  }
+
+  init() {
+    this.isVisible = true;
+  }
+
+  tick() {
+    if (!this.game || !this.isVisible) {
+      return;
+    }
+
+    const showTeamOwnershipBar =
+      this.game.config().gameConfig().gameMode === GameMode.Team &&
+      !this.game.inSpawnPhase();
+
+    this.style.top = showTeamOwnershipBar ? "7px" : "0px";
+
+    const immunityDuration = this.game.config().spawnImmunityDuration();
+    const spawnPhaseTurns = this.game.config().numSpawnPhaseTurns();
+
+    if (immunityDuration <= 5 * 10 || this.game.inSpawnPhase()) {
+      this.setInactive();
+      return;
+    }
+
+    const immunityEnd = spawnPhaseTurns + immunityDuration;
+    const ticks = this.game.ticks();
+
+    if (ticks >= immunityEnd || ticks < spawnPhaseTurns) {
+      this.setInactive();
+      return;
+    }
+
+    const elapsedTicks = Math.max(0, ticks - spawnPhaseTurns);
+    this.progressRatio = Math.min(
+      1,
+      Math.max(0, elapsedTicks / immunityDuration),
+    );
+    this.isActive = true;
+    this.requestUpdate();
+  }
+
+  private setInactive() {
+    if (this.isActive) {
+      this.isActive = false;
+      this.requestUpdate();
+    }
+  }
+
+  shouldTransform(): boolean {
+    return false;
+  }
+
+  render() {
+    if (!this.isVisible || !this.isActive) {
+      return html``;
+    }
+
+    const widthPercent = this.progressRatio * 100;
+
+    return html`
+      <div class="w-full h-full flex z-[999]">
+        <div
+          class="h-full transition-all duration-100 ease-in-out"
+          style="width: ${widthPercent}%; background-color: rgba(255, 165, 0, 0.9);"
+        ></div>
+      </div>
+    `;
+  }
+}

src/core/Schemas.ts

@@ -179,6 +179,7 @@ export const GameConfigSchema = z.object({
   randomSpawn: z.boolean(),
   maxPlayers: z.number().optional(),
   maxTimerValue: z.number().int().min(1).max(120).optional(),
+  spawnImmunityDuration: z.number().int().min(0).optional(), // In ticks
   disabledUnits: z.enum(UnitType).array().optional(),
   playerTeams: TeamCountConfigSchema.optional(),
 });

src/core/configuration/DefaultConfig.ts

@@ -246,7 +246,7 @@ export class DefaultConfig implements Config {
     return 30 * 10; // 30 seconds
   }
   spawnImmunityDuration(): Tick {
-    return 5 * 10;
+    return this._gameConfig.spawnImmunityDuration ?? 5 * 10; // default to 5 seconds
   }
 
   gameConfig(): GameConfig {

src/core/execution/AttackExecution.ts

@@ -92,16 +92,9 @@ export class AttackExecution implements Execution {
       }
     }
 
-    if (this.target.isPlayer()) {
-      if (
-        this.mg.config().numSpawnPhaseTurns() +
-          this.mg.config().spawnImmunityDuration() >
-        this.mg.ticks()
-      ) {
-        console.warn("cannot attack player during immunity phase");
-        this.active = false;
-        return;
-      }
+    if (this.target.isPlayer() && !this._owner.canAttackPlayer(this.target)) {
+      this.active = false;
+      return;
     }
 
     this.startTroops ??= this.mg

src/core/execution/TransportShipExecution.ts

@@ -93,6 +93,10 @@ export class TransportShipExecution implements Execution {
     } else {
       this.target = mg.player(this.targetID);
     }
+    if (this.target.isPlayer() && !this.attacker.canAttackPlayer(this.target)) {
+      this.active = false;
+      return;
+    }
 
     this.startTroops ??= this.mg
       .config()