# Implementazione Agente DRL Recurrent-SAC (SAC-GRU) Nativo per Robocode TankRoyale

 Bot nativo basato sull'algoritmo **Recurrent Soft Actor-Critic (SAC-GRU)** addestrato per combattere nell'ambiente **Robocode TankRoyale**.

Il bot deve connettersi direttamente al server WebSocket di TankRoyale tramite un'interfaccia client API nativa, senza l'uso di middleware o socket intermediari extra. Il sistema deve garantire il rispetto del limite rigido di **30 ms per turno** imposto dal simulatore, eseguendo l'inferenza e l'addestramento in modo concorrente all'interno dello stesso processo.

---

## 1. Architettura Multi-Thread e Concorrenza (30 ms Tick Constraint)

Per evitare il fenomeno degli "skipped turns", l'applicazione deve essere suddivisa in due thread principali coordinati nello stesso processo:

1. **Thread 1: Realtime Async Event Loop (WebSocket Client)**
   * Riceve i messaggi di evento dal server TankRoyale via WebSocket ad ogni tick.
   * Estragga e normalizza il vettore di stato a 17 dimensioni ($S_t$).
   * Esegue l'inferenza rapida dell'Actor ($< 2 \text{ ms}$) fornendo lo stato $S_t$ e lo stato nascosto corrente della GRU ($h_{t-1}$).
   * Mappa le azioni restituite e invia immediatamente il `BotIntent` al server WebSocket.
   * Invia la transizione $(S_t, A_t, R_t, S_{t+1}, D_t)$ a una coda/canale thread-safe (`Thread-safe Channel`).

2. **Thread 2: Background Trainer Thread (SAC-GRU Engine)**
   * Preleva le transizioni dal canale e le accumula in un **Sequential Replay Buffer**.
   * Quando il buffer contiene un numero sufficiente di esperienze, estrae mini-batch di sequenze temporali.
   * Esegue l'addestramento in background (Forward/Backward Pass dell'Actor, dei Dual Critic e dell'Alpha autotuning) sfruttando l'accelerazione hardware (GPU/CPU).
   * Aggiorna periodicamente i pesi della rete Actor usata dal Thread 1 in modo thread-safe (es. scambio atomico di puntatori o mutua esclusione leggera).

---

## 2. Specifiche dell'Ambiente DRL (POMDP)

### 2.1 Vettore di Stato ($S \in \mathbb{R}^{17}$, Normalizzato in $[-1, 1]$)

* `s[0]`: Posizione X propria ($X / \text{width}$)
* `s[1]`: Posizione Y propria ($Y / \text{height}$)
* `s[2]`: Orientamento scafo ($[-\pi, \pi] / \pi$)
* `s[3]`: Velocità lineare propria ($[-8, 8] / 8$)
* `s[4]`: Orientamento cannone ($[-\pi, \pi] / \pi$)
* `s[5]`: Orientamento radar ($[-\pi, \pi] / \pi$)
* `s[6]`: Temperatura del cannone ($[0, 3] / 3$)
* `s[7]`: Energia propria ($[0, 100] / 100$)
* `s[8]`: Distanza dal muro NORD ($(\text{height} - Y) / \text{height}$)
* `s[9]`: Distanza dal muro SUD ($Y / \text{height}$)
* `s[10]`: Distanza dal muro EST ($(\text{width} - X) / \text{width}$)
* `s[11]`: Distanza dal muro OVEST ($X / \text{width}$)
* `s[12]`: Ultima distanza rilevata del nemico ($[0, \text{max\_dist}] / \text{max\_dist}$)
* `s[13]`: Angolo relativo (bearing) del nemico ($[-\pi, \pi] / \pi$)
* `s[14]`: Orientamento del nemico ($[-\pi, \pi] / \pi$)
* `s[15]`: Velocità del nemico ($[-8, 8] / 8$)
* `s[16]`: Energia residua del nemico ($[0, 100] / 100$)

### 2.2 Vettore delle Azioni Continuo ($A \in \mathbb{R}^4$, Output $[-1, 1]$)

* `a[0]`: Rotazione scafo $\rightarrow$ Mappato su $[-10^\circ, +10^\circ]$ per tick.
* `a[1]`: Traslazione $\rightarrow$ Mappato su $[-8, +8]$ px/tick.
* `a[2]`: Rotazione cannone $\rightarrow$ Mappato su $[-20^\circ, +20^\circ]$ per tick.
* `a[3]`: Potenza di sparo $\rightarrow$ $\text{ReLU}(a_3) \times 3.0$ (Spara solo se $> 0.1$).

### 2.3 Reward Function

$$R_t = R_{\text{danno\_inflitto}} - R_{\text{danno\_subito}} + R_{\text{vittoria/sconfitta}} - R_{\text{muri}} - R_{\text{sparo\_vuoto}}$$

* Danno inflitto: $+ (4p + 2(p - 1))$ con $p \le 3$.
* Danno subito: $- (4p_{\text{nemico}} + 2(p_{\text{nemico}} - 1))$.
* Muri: $-5.0$ per tick di impatto.
* Sparo a vuoto: $-0.1 \times p$.
* Vittoria/Sconfitta: $+20.0$ / $-10.0$.

---

## 3. Modelli Neurali e Meccanismi di Addestramento

Tutte le reti devono integrare una cella ricorsiva **GRU (Gated Recurrent Unit)** per gestire la parziale osservabilità dell'arena (radar in rotazione):

* **Recurrent Actor Network $\pi_\phi(a_t | s_{:t}, h_{t-1})$:**
  * Feature Extractor: Linear/Dense ($17 \rightarrow 128$) + Attivazione
  * Memory: GRU Layer (Input: $128$, Hidden: $128$)
  * Heads: Linear/Dense ($128 \rightarrow 64$) $\rightarrow$ Outputs: $\mu \in \mathbb{R}^4$ e $\log \sigma \in \mathbb{R}^4$ (Clamped $[-20, 2]$)
  * Sampling: Reparameterization Trick con squashing $\tanh$.

* **Recurrent Dual-Critic Networks $Q_{\theta_1, \theta_2}(s_{:t}, a_{:t}, h_{t-1})$:**
  * Fusion: Concatenazione di Stato e Azione ($17 + 4 = 21$)
  * Feature Extractor: Linear/Dense ($21 \rightarrow 128$) + Attivazione
  * Memory: GRU Layer (Input: $128$, Hidden: $128$)
  * Q-Head: Linear/Dense ($128 \rightarrow 64$) $\rightarrow$ Output Q-Value scalare.

* **Sequential Replay Buffer & Burn-in Strategy:**
  * Campionamento di sequenze temporali contigue di lunghezza $L = 24$.
  * **Burn-in ($L_{\text{burn}} = 8$ step):** I primi 8 step vengono usati unicamente per aggiornare lo stato nascosto $h$ della GRU, senza calcolo di loss o backpropagation.
  * **Training ($L_{\text{train}} = 16$ step):** I successivi 16 step calcolano le loss dell'Actor, dei Critic e l'autotuning del parametro di temperatura $\alpha$ (con target $H_{\text{target}} = -4.0$).

---

## 4. Requisiti di Strutturazione del Codice

Fornisci il codice sorgente completo, modulare e pronto all'uso articolato nelle seguenti componenti:

1. **Model Definitions:** Classi/Strutture per Actor, Critic e Target Networks basate su GRU.
2. **Sequential Replay Buffer:** Struttura dati thread-safe con supporto per estrazione di sequenze e gestione Burn-in.
3. **SAC-GRU Trainer Engine:** Algoritmo di aggiornamento, calcolo loss, gradient clipping ($1.0$) e soft update ($\tau = 0.005$).