truetype/dcc-rpg
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
dcc-rpg/docs/plans/2026-06-25-dcc-rpg-design.md
T

8.9 KiB
Raw Permalink Blame History

DCC RPG - Architettura Sistema Ibrido AI DM

Data: 2026-06-25
Pattern: Neon Scratch Lounge (Separazione Reasoning/Execution)
Gioco: Dungeon Crawl Classics - Regolamento Introduttivo
Avventura: La Tomba del Mago Guerriero (9 aree)

1. Visione

Sistema ibrido AI DM per DCC: un LLM gestisce narrativa e interpretazione azioni, mentre un motore deterministico (Step Functions + Lambda) esegue le meccaniche di gioco. Il giocatore interagisce via interfaccia testuale/web. Un umano può intervenire con DM-Override per derogare alle regole.

Target: On-premise (CPU-only), interfaccia web locale, nessuna dipendenza cloud.

2. Architettura

+------------------------------------------+
|              CLIENT (Web UI)              |
|      Chat testuale + pannello stato       |
+--------------------+---------------------+
                     | HTTP/WebSocket
+--------------------v---------------------+
|          LLM ORCHESTRATOR (Python)       |
|  - Mantiene contesto sessione            |
|  - Invia prompt: regole + stato + azione |
|  - Riceve: narrazione + tool calls       |
|  - Filtra tool contro allowlist          |
+--------------------+---------------------+
                     |
+--------------------v---------------------+
|         STATE MACHINE (Python)           |
|  Leggi stato -> Esegui tool -> Scrivi    |
|  Retry: 3 tentativi, backoff + jitter    |
|  Idempotenza: cache per turnId           |
|  Fallback: narrazione safe               |
+--------------------+---------------------+
                     |
+--------------------v---------------------+
|           APPROVED TOOLS (Python)        |
|  roll-dice | combat | ability-check      |
|  saving-throw | movement | spellcasting  |
|  update-inventory | award-xp | quest     |
|  dm-override                             |
+--------------------+---------------------+
                     |
+--------------------v---------------------+
|     STATO (SQLite / JSON locale)          |
|  Personaggi | Avventura | Turni | Quest   |
+------------------------------------------+

3. Stack Tecnologico (On-Premise)

Componente Tecnologia Motivo
LLM Ollama (gemma2:9b) On-premise, CPU-only, IT
Backend Python + FastAPI Leggero, on-premise
Frontend HTML+JS vanilla Semplice, no build
Stato SQLite Zero dipendenze
Tools Python functions Deterministici, testabili
Orchestratore State machine Python Equivalente NSL on-prem
Embedding nomic-embed-text (Ollama) Retrieval KB (opzionale)

Deviazioni NSL: Step Functions AWS e DynamoDB sostituiti da state machine Python + SQLite. Pattern architetturale (Separazione Reasoning/Execution) identico.

4. Flusso del Turno

1. INPUT GIOCATORE -> "Cerco nella stanza"
       |
2. LLM REASONING: analizza azione, consulta regole,
   decide tool da chiamare
   Output: narrazione + ["ability-check: cercare CD 12"]
       |
3. VALIDATE: filtra tool contro allowlist
       |
4. EXECUTE TOOLS (sequenziale/parallelo):
   - ability-check("cercare", CD 12, agilita)
   - Risultato: successo (15 >= 12), trova leva segreta
       |
5. PERSIST STATO: aggiorna SQLite
       |
6. LLM NARRATION: "Scorgi una lieve fessura nella parete
   nord. Sembra esserci una leva nascosta..."
       |
7. OUTPUT GIOCATORE -> messaggio di risposta

5. Approved Tools

5.1 roll-dice

  • Parametri: dado (d20, d%, d24), quantita (default 1), modificatore
  • Output: risultati numerici, successo/fallimento vs CD
  • Esempi: 1d20+2, 1d24 (catena dadi), 3d6, 1d100

5.2 combat

  • Sotto-operazioni:
    • initiative: 1d20 + Agilita, ordina creature
    • attack: d20 + mod vs CA, danni se colpito
    • mighty-deed: attacco + deed (guerriero)
    • sneak-attack: attacco furtivo (ladro)
    • critical-hit: tabella critici
    • fumble: tabella fallimenti critici

5.3 ability-check

  • Parametri: abilita, CD, caratteristica
  • Ladro: usa dado abilita + modificatore
  • Altri: d20 + modificatore caratteristica

5.4 saving-throw

  • Parametri: tipo (Tempra/Riflessi/Volonta), CD, bonus
  • Output: successo/fallimento, effetti

5.5 movement

  • Parametri: destinazione/area, modalita
  • Output: tempo, incontri, ostacoli

5.6 spellcasting

  • Parametri: incantesimo, livello, modificatori
  • Output: prova incantesimo, tabella, manifestazione, corruzione

5.7 update-inventory

  • Parametri: azione (aggiungi/rimuovi/equipaggia), oggetto, qta
  • Output: inventario aggiornato

5.8 award-xp

  • Parametri: PE (0-4), motivo
  • Output: PE totali, eventuale avanzamento livello

5.9 update-quest

  • Parametri: quest ID, stato (attiva/completata/fallita)
  • Output: log quest aggiornato

5.10 dm-override (solo DM)

  • Parametri: modifica (set-pf, forza-risultato, ignora-regola)
  • Output: stato modificato

6. Stato del Gioco (SQLite Schema)

CREATE TABLE campaign (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    turn_id INTEGER DEFAULT 0,
    current_area TEXT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

CREATE TABLE characters (
    id TEXT PRIMARY KEY,
    campaign_id TEXT REFERENCES campaign(id),
    name TEXT NOT NULL, player TEXT,
    level INTEGER DEFAULT 0, xp INTEGER DEFAULT 0,
    class TEXT, alignment TEXT,
    occupation TEXT,
    str INTEGER, agi INTEGER, con INTEGER,
    int INTEGER, sag INTEGER, car INTEGER, lck INTEGER,
    hp_current INTEGER, hp_max INTEGER,
    ac INTEGER, equipment TEXT, inventory TEXT,
    active_effects TEXT, is_alive BOOLEAN DEFAULT 1
);

CREATE TABLE adventure_state (
    id TEXT PRIMARY KEY,
    campaign_id TEXT REFERENCES campaign(id),
    area_id TEXT NOT NULL, area_name TEXT NOT NULL,
    visited BOOLEAN DEFAULT 0,
    npc_status TEXT, notes TEXT
);

CREATE TABLE quest_log (
    id TEXT PRIMARY KEY,
    campaign_id TEXT REFERENCES campaign(id),
    quest_name TEXT NOT NULL,
    status TEXT DEFAULT 'active',
    description TEXT, objectives TEXT
);

CREATE TABLE turn_log (
    id TEXT PRIMARY KEY,
    campaign_id TEXT REFERENCES campaign(id),
    turn_id INTEGER NOT NULL,
    player_action TEXT, narrative TEXT,
    tools_called TEXT, results TEXT,
    created_at TIMESTAMP
);

7. Knowledge Base

7.1 Contesto System Prompt

Il prompt system del LLM contiene:

  1. Regole fondamentali: d20, catena dadi, CD/CA
  2. Approved Tools: descrizione e parametri
  3. Mappa avventura: aree, CD, statistiche mostri
  4. Regole classe: Dado Cimento, abilita ladro, ecc.
  5. Tabelle critici/fumble
  6. Allineamento e deta

7.2 Retrieval (opzionale)

Embedding con nomic-embed-text su Ollama per retrieval regole specifiche.

8. DM-Override

8.1 Operazioni

  • Modifica diretta stato (PF, statistiche, equip)
  • Forzatura risultati (successo/fallimento automatico)
  • Deroga regole (es. ignora caduta)
  • Spawn NPC e mostri
  • Rewind turno

8.2 Accesso

  • Pulsante "DM Mode" nell'interfaccia
  • Comando testuale /dm
  • LLM puo richiedere override: "Situazione non coperta. DM?"

8.3 Logging

Ogni override registrato in turn_log con flag is_dm_override.

9. Mappa Avventura (Area Graph)

[Foresta (quest driade)]
        |
   [1.1 Portale]
        |
   [1.2 Sala Guardiano]  -- statua lanciafiamme
        |
   [1.3 Sala Monumentale]
        |
   [1.4 Sala Visioni] --- [1.5 Sepoltura Capo]
        |                       |
   [1.6 Vasca Osservazione] ----+
        |                       |
   [1.7 Stanza Strategia] ------+
        |
   [1.8 Esercito Terracotta]
        |
   [1.9 Sala Tesoro]

10. Idempotenza e Retry

10.1 Idempotenza

cache_key = campaign_id:turn_id:tool_name:args_hash
if cache_key in result_cache:
    return result_cache[cache_key]
result = execute_tool(args)
result_cache[cache_key] = result  # TTL: 3600s
return result

10.2 Retry

max_attempts: 3
backoff_base: 2      # esponenziale
jitter: full          # random 0..interval
interval_seconds: 2

10.3 Safe Fallback

Se tutti i retry falliscono: narrazione safe. "Un'esitazione perplessa attanaglia l'ambiente mentre le forze arcane si riassestano..." Nessuna perdita di stato. Turno recuperabile.

11. Sicurezza e Robustezza

  • Tool allowlist: LLM non puo chiamare funzioni non autorizzate
  • Validazione input: ogni tool valida i parametri ricevuti
  • DM-Override loggato: trail audit per ogni modifica manuale
  • Backup SQLite: copia del database a ogni sessione
  • Niente dipendenze cloud: tutto on-premise su Proxmox

12. Prossimi Step Implementativi

  1. Setup progetto Python (FastAPI + SQLite + state machine)
  2. Implementazione Approved Tools (10 funzioni core)
  3. Integrazione Ollama (gemma2:9b per narrazione IT)
  4. Prompt engineering: system context + tool calling
  5. Interfaccia web (chat + pannello stato personaggi)
  6. DM-Override: pulsante e comandi
  7. Mappatura avventura: 9 aree + quest driade
  8. Test: run-through completo dell'avventura
  9. Documentazione utente
Reference in new issue View Git Blame Copy Permalink