91 lines
2.9 KiB
TypeScript
91 lines
2.9 KiB
TypeScript
/**
|
||
* Zork LLM Engine
|
||
*
|
||
* Runs Zork I (or any Z-machine story file) as a headless subprocess via the
|
||
* `ifvms` CLI, and wraps every I/O exchange with OpenRouter LLM calls that
|
||
* translate free natural-language player input into parser commands and
|
||
* re-voice the Z-machine's raw output as polished narrative prose.
|
||
*
|
||
* Configuration (environment variables):
|
||
* ZORK_STORY_FILE – path to the .z5/.z8/.bin story file (default: ./data/z-code/zork1.bin)
|
||
* ZORK_MAX_RETRIES – maximum command retry attempts per turn (default: 3)
|
||
* ZORK_HISTORY_SIZE – player-facing outputs stored per room (default: 5)
|
||
* OPENROUTER_API_KEY, OPENROUTER_MODEL – required
|
||
*/
|
||
export interface ZorkSession {
|
||
characterDescription: string;
|
||
notes: string[];
|
||
recentParagraphs: string[];
|
||
rawTranscript: string[];
|
||
turnCount: number;
|
||
timeOfDay: string;
|
||
weather: string;
|
||
virtualInventory: string[];
|
||
/** roomName → last N player-facing output strings */
|
||
roomHistory: Record<string, string[]>;
|
||
currentRoom: string;
|
||
running: boolean;
|
||
}
|
||
/** Subset of the unified TurnResult protocol understood by the client. */
|
||
export interface ZorkTurnResult {
|
||
paragraphs: Array<{
|
||
text: string;
|
||
tags: unknown[];
|
||
}>;
|
||
choices: unknown[];
|
||
inputMode: 'text' | 'end';
|
||
gameState?: {
|
||
statusLine?: string;
|
||
};
|
||
}
|
||
export declare class ZorkLlmEngine {
|
||
private zork;
|
||
private session;
|
||
private prompts;
|
||
private llm;
|
||
private model;
|
||
private resolvedFallbackModel;
|
||
private llmCallCounter;
|
||
private maxRetries;
|
||
private historySize;
|
||
private storyPath;
|
||
private static readonly DEPRECATED_MODEL_REPLACEMENTS;
|
||
constructor();
|
||
private createCompletion;
|
||
private resolveFallbackModel;
|
||
isRunning(): boolean;
|
||
/**
|
||
* Start a new game: launch Zork, generate the player character, rewrite the
|
||
* intro text, and return the first TurnResult for the client.
|
||
*/
|
||
newGame(): Promise<ZorkTurnResult>;
|
||
/**
|
||
* Process player free-text input. Returns the next TurnResult.
|
||
*/
|
||
processInput(userInput: string): Promise<ZorkTurnResult>;
|
||
private runCommandPlan;
|
||
/**
|
||
* Save the current game state. Returns a JSON string suitable for storing
|
||
* in the socket's save-game slot map.
|
||
*/
|
||
saveGame(): Promise<string>;
|
||
/**
|
||
* Load a previously saved game. Returns the first TurnResult after restore.
|
||
*/
|
||
loadGame(savedJson: string): Promise<ZorkTurnResult>;
|
||
private runSingleCommandLoop;
|
||
private generateCharacter;
|
||
private rewriteText;
|
||
private translateCommand;
|
||
private evaluateOutput;
|
||
private executeTool;
|
||
private appendRecentParagraph;
|
||
private extractCommands;
|
||
private appendRawTranscript;
|
||
private advanceNarratorState;
|
||
private getDeterministicCommandPlan;
|
||
private appendRoomHistory;
|
||
private buildCommonVars;
|
||
private buildTurnResult;
|
||
}
|