RPG IDLE Game Engine

In un Idle RPG il gioco non si ferma quando il giocatore chiude l'app: combattimenti, viaggi e raccolta risorse proseguono in background. Al rientro, l'engine deve calcolare tutto ciò che è accaduto in base al tempo trascorso e restituire uno stato coerente — non approssimato, non mancante, ma esatto. Questo è il cuore del progetto.

Ogni personaggio ha statistiche, inventario, equipaggiamento e progressi che dipendono dagli eventi elaborati durante l'assenza. Le meccaniche sono nove: combattimenti, viaggi, livelli/XP, inventario, mercato con oggetti procedurali e sistema di affix, spedizioni, attributi personaggio, equipaggiamento. Ogni meccanica ha le sue regole, le sue formule, le sue tabelle.

L'engine è un progetto personale sviluppato come v1 completa: 15 endpoint REST, 25 tabelle PostgreSQL, deploy su VPS. Lo stack — Python con FastAPI — è stato scelto per le prestazioni e la gestione asincrona nativa, con driver PostgreSQL configurato in modalità async per tutta la catena di chiamate.

L'architettura segue il pattern N-Tier — API, Service, Repository, Database — con un Service per ogni feature. Le operazioni di scrittura usano il pattern Unit of Work: una richiesta, una transazione atomica. I dati critici — creazione personaggio, aggiornamento stato, combattimenti — sono protetti da transazioni PostgreSQL: tutto o niente.

L'architettura N-Tier separa chiaramente le responsabilità: routing e validazione nelle API, logica di gioco nei Service, accesso dati nei Repository. Ogni feature — combattimenti, inventario, mercato — ha il suo Service dedicato. Le scritture critiche usano il pattern Unit of Work: 1 richiesta = 1 transazione atomica su PostgreSQL con driver async. Se un passaggio fallisce, nulla viene persistito — coerenza ACID garantita sui dati di gioco.

La progressione offline è il cuore del sistema: al rientro del giocatore, l'engine calcola in un'unica operazione tutto il tempo trascorso — combattimenti, viaggi, risorse — e applica le conseguenze allo stato del personaggio. Nessuna simulazione continua in background, solo calcolo basato sui timestamp. La strategia è top-down: il Service principale orchestra i Service figli con una singola sessione DB, garantendo che creazione personaggio, inventario ed energia siano coerenti al 100%.

Il bilanciamento è basato su formule: progressione XP con curva esponenziale tipica degli idle game; statistiche totali additive (base + equipaggiamento); HP ed energia derivati da livello e attributi; nemici scalati dinamicamente al momento del combattimento in base a livello del personaggio e moltiplicatore di difficoltà (boss/elite); rarity tiers pesati dal comune (~50%) al leggendario (~1,5%); oggetti generati proceduralmente nel mercato con affix a curve ibride — logaritmica per i bonus, power curve per il valore base; prezzi di mercato calcolati da valore base, fattore livello, moltiplicatore rarità e margine.

Le API sono documentate con Scalar — scelto al posto della Swagger UI default di FastAPI per l'interfaccia più chiara — e testate con una suite di circa 20 test pytest, ancora in crescita. L'autenticazione avviene via API key. L'engine è deployato su VPS con Docker, con SQLAlchemy come ORM e Alembic per le migrazioni.

V1 completa e deployata: 15 endpoint REST, 25 tabelle PostgreSQL, 9 domini di gioco con bilanciamento a formule — engine funzionante su VPS con suite di test pytest in crescita.

Dati critici protetti da Unit of Work: creazione personaggio, combattimenti e aggiornamenti stato sono transazioni atomiche — se un passaggio fallisce, nulla viene persistito. Coerenza ACID garantita.

Stack scelto con consapevolezza: Python/FastAPI per l'async nativo con driver PostgreSQL async — motivazione tecnica documentata e giustificata, documentazione Scalar sempre aggiornata.