chore: gitignore binaries/artifacts, remove drafts and stale files
This commit is contained in:
@@ -1,98 +0,0 @@
|
||||
# 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$).
|
||||
Reference in New Issue
Block a user