mudlet-ai-client/docs/API.md

API IPC Reference

Context Bridge

Tutte le API sono esposte tramite window.electronAPI:

// TypeScript declaration
interface ElectronAPI {
  // Telnet
  telnetConnect: (host: string, port: number) => Promise<boolean>;
  telnetDisconnect: () => Promise<void>;
  telnetSend: (data: string) => Promise<boolean>;
  telnetGetOutput: () => Promise<string>;
  onTelnetOutput: (callback: (data: string) => void) => void;

  // Ollama
  ollamaChat: (messages: OllamaMessage[], options?: OllamaOptions) => Promise<OllamaResponse>;
  ollamaGetModels: () => Promise<string[]>;
  ollamaIsAvailable: () => Promise<boolean>;

  // Autoplayer
  autoplayerConfigure: (config: AutoplayerConfig) => Promise<void>;
  autoplayerStart: () => Promise<void>;
  autoplayerStop: () => Promise<void>;
  autoplayerIsActive: () => Promise<boolean>;
  autoplayerExecuteAction: (action: string) => Promise<void>;
  onAutoplayerDecision: (callback: (decision: string) => void) => void;
  onAutoplayerAction: (callback: (action: string) => void) => void;
  onAutoplayerState: (callback: (state: GameState) => void) => void;
}

---

Telnet API

telnetConnect

Stabilisce connessione Telnet al server MUD.

const connected = await window.electronAPI.telnetConnect('172.24.19.225', 6666);

Params:

Param	Type	Description
host	string	Indirizzo server MUD
port	number	Porta Telnet

Returns: Promise<boolean> - true se connessione riuscita

Errors: Connection timeout, host unreachable

telnetDisconnect

Chiude connessione Telnet.

await window.electronAPI.telnetDisconnect();

telnetSend

Invia comando al server MUD.

const sent = await window.electronAPI.telnetSend('look\n');

Params:

Param	Type	Description
data	string	Comando da inviare (newline esclusa)

Returns: Promise<boolean> - true se invio riuscito

telnetGetOutput

Restituisce buffer output Telnet accumulato.

const output = await window.electronAPI.telnetGetOutput();

Returns: Promise<string> - Output completo con HTML colors

onTelnetOutput

Subscribe a nuovi output dal server.

window.electronAPI.onTelnetOutput((data) => {
  console.log('Nuovo output:', data);
});

Callback Params:

Param	Type	Description
data	string	Chunk output HTML

---

Ollama API

ollamaChat

Invia messaggi a Ollama e riceve risposta.

const response = await window.electronAPI.ollamaChat([
  { role: 'system', content: 'You are a MUD player' },
  { role: 'user', content: 'What should I do?' }
], {
  model: 'llama3.2',
  temperature: 0.7
});

Params:

Param	Type	Description
messages	OllamaMessage[]	Storico conversazione
options	OllamaOptions	Opzioni (opzionali)

OllamaMessage:

{
  role: 'user' | 'assistant' | 'system';
  content: string;
}

OllamaOptions:

{
  model?: string;        // Default: 'llama3.2'
  temperature?: number;  // Default: 0.7
}

Returns: Promise<OllamaResponse>

{
  model: string;
  response: string;
  done: boolean;
}

ollamaGetModels

Lista modelli disponibili sul server.

const models = await window.electronAPI.ollamaGetModels();
// ['llama3.2', 'llama3.1', 'mistral', ...]

Returns: Promise<string[]> - Nomi modelli

ollamaIsAvailable

Verifica se server Ollama raggiungibile.

const available = await window.electronAPI.ollamaIsAvailable();
// true se server risponde

Returns: Promise<boolean>

---

Autoplayer API

autoplayerConfigure

Configura comportamento autoplayer.

await window.electronAPI.autoplayerConfigure({
  model: 'llama3.2',
  systemPrompt: 'You are an explorer...',
  temperature: 0.7,
  autoSend: true
});

AutoplayerConfig:

{
  model: string;           // Model LLM
  systemPrompt: string;    // Personalità bot
  temperature?: number;    // Creatività (0.0-1.0)
  autoSend?: boolean;      // Auto-esegui azioni
}

autoplayerStart

Avvia loop autoplayer.

await window.electronAPI.autoplayerStart();

autoplayerStop

Ferma loop autoplayer.

await window.electronAPI.autoplayerStop();

autoplayerIsActive

Verifica se autoplayer in esecuzione.

const active = await window.electronAPI.autoplayerIsActive();

Returns: Promise<boolean>

autoplayerExecuteAction

Esegui azione manualmente (senza passare per decision engine).

await window.electronAPI.autoplayerExecuteAction('go north');

onAutoplayerDecision

Subscribe a decisioni LLM.

window.electronAPI.onAutoplayerDecision((decision) => {
  console.log('LLM decision:', decision);
});

Callback Params:

Param	Type	Description
decision	string	Risposta completa LLM

onAutoplayerAction

Subscribe ad azioni generate.

window.electronAPI.onAutoplayerAction((action) => {
  console.log('Action to execute:', action);
});

Callback Params:

Param	Type	Description
action	string	Comando da eseguire

onAutoplayerState

Subscribe a updates stato gioco parsato.

window.electronAPI.onAutoplayerState((state) => {
  console.log('Current location:', state.location);
  console.log('Exits:', state.exits);
});

GameState:

{
  location: string;      // Nome location corrente
  description: string;   // Descrizione stanza
  exits: string[];       // Uscite disponibili
  players: string[];     // Giocatori presenti
  objects: string[];     // Oggetti nella stanza
  health?: string;       // HP corrente
  mana?: string;         // Mana corrente
  prompt?: string;       // Prompt del gioco
}

---

Esempi Completi

Connessione e Game Loop

// 1. Connetti
const connected = await window.electronAPI.telnetConnect('172.24.19.225', 6666);
if (!connected) {
  console.error('Connessione fallita');
  return;
}

// 2. Subscribe output
window.electronAPI.onTelnetOutput((data) => {
  // Aggiorna UI
  setOutput(prev => prev + data);
});

// 3. Invia comando
await window.electronAPI.telnetSend('look\n');

Autoplayer Workflow

// 1. Configura
await window.electronAPI.autoplayerConfigure({
  model: 'llama3.2',
  systemPrompt: 'You are a helpful MUD player. Explore and interact naturally.',
  temperature: 0.7,
  autoSend: false  // Review manuale azioni
});

// 2. Subscribe decisioni
window.electronAPI.onAutoplayerAction((action) => {
  console.log('Pending action:', action);
  // Possibile review manuale qui
});

// 3. Avvia
await window.electronAPI.autoplayerStart();

// 4. Per fermare
await window.electronAPI.autoplayerStop();

Ollama Chat Diretta

// Test chat con Ollama
const response = await window.electronAPI.ollamaChat([
  { role: 'system', content: 'You are a fantasy game master.' },
  { role: 'user', content: 'Describe a dark forest.' }
], { temperature: 0.8 });

console.log(response.response);

---

Error Handling

try {
  await window.electronAPI.telnetConnect(host, port);
} catch (error) {
  console.error('Connection error:', error);
}

// Event-based errors
window.electronAPI.onTelnetOutput((data) => {
  // Gestisci errori in output
});

Note

• Tutte le chiamate IPC sono asincrone (Promise-based)
• Gli eventi devono essere sottoscritti una volta (non in useEffect ripetuti)
• Cleanup event listeners quando il componente unmount
• Utilizzare window.electronAPI solo dopo il mount del componente