omfgg-dev / engine.py
Joe Rogers
Add narrative game engine and branching story app
a4a8504
Raw History Blame Contribute Delete
6.86 kB
"""
Deterministic state management for branching narrative games.
"""
from __future__ import annotations
from typing import Dict, Optional
from datetime import datetime
from models import Choice, GameSpec, GameState, Scene
class GameEngineError(Exception):
"""Base error for the game engine."""
class InvalidChoiceError(GameEngineError):
"""Raised when a requested choice cannot be applied."""
class GameEngine:
"""
Provides deterministic state transitions for a branching narrative game.
"""
def __init__(self, game_spec: GameSpec, initial_state: Optional[GameState] = None):
self.game = game_spec
starting_stats = game_spec.metadata.get("starting_stats", {})
self.state = initial_state or GameState(
game_id=game_spec.id,
current_scene_id=game_spec.start_scene_id,
score=game_spec.metadata.get("starting_score", 0),
stats=starting_stats.copy() if isinstance(starting_stats, dict) else {},
)
# -- Basic helpers -----------------------------------------------------------------
def reset(self) -> None:
"""Reset the engine to the starting scene."""
self.state.current_scene_id = self.game.start_scene_id
self.state.score = self.game.metadata.get("starting_score", 0)
self.state.inventory = []
starting_stats = self.game.metadata.get("starting_stats", {})
self.state.stats = starting_stats.copy() if isinstance(starting_stats, dict) else {}
self.state.history = []
self.state.is_complete = False
self.state.ending_tag = None
def get_current_scene(self) -> Scene:
"""Return the active scene."""
try:
return self.game.scenes[self.state.current_scene_id]
except KeyError as exc:
raise GameEngineError(f"Scene '{self.state.current_scene_id}' missing from game spec") from exc
def get_choice(self, choice_id: str) -> Choice:
"""Return a choice by identifier within the current scene."""
for choice in self.get_current_scene().choices:
if choice.id == choice_id:
return choice
raise InvalidChoiceError(f"Choice '{choice_id}' not found in scene '{self.state.current_scene_id}'")
# -- Core transition logic ---------------------------------------------------------
def apply_choice(self, choice_id: str) -> Dict:
"""
Apply a player's choice and return an updated snapshot for UI rendering.
Returns:
dict: Snapshot including scene info, state values, and terminal data.
"""
current_scene = self.get_current_scene()
choice = self.get_choice(choice_id)
# Update score
self.state.score += choice.delta_score
# Update stats
if choice.stat_changes:
for stat, delta in choice.stat_changes.items():
self.state.stats[stat] = self.state.stats.get(stat, 0) + delta
# Loot handling
if choice.loot:
self.state.inventory.append(choice.loot)
# Record history (immutable entry to support UI timeline)
history_entry = {
"timestamp": datetime.utcnow().isoformat(),
"scene_id": current_scene.id,
"scene_title": current_scene.title,
"choice_id": choice.id,
"choice_label": choice.label,
"result_text": choice.result_text,
"delta_score": choice.delta_score,
"risk_level": choice.risk_level,
"loot": choice.loot,
"stat_changes": choice.stat_changes,
"next_scene_id": choice.next_scene_id,
}
self.state.history.append(history_entry)
# Determine next scene
next_scene_id = choice.next_scene_id
if next_scene_id:
if next_scene_id not in self.game.scenes:
raise GameEngineError(f"Scene '{next_scene_id}' referenced by choice '{choice.id}' is missing.")
self.state.current_scene_id = next_scene_id
next_scene = self.game.scenes[next_scene_id]
self.state.is_complete = bool(next_scene.is_terminal)
self.state.ending_tag = next_scene.ending_tag if next_scene.is_terminal else None
else:
# Remain on the current scene but mark completion
self.state.is_complete = True
self.state.ending_tag = current_scene.ending_tag
if self.state.is_complete and not next_scene_id:
# Preserve current scene for UI but ensure choices are disabled
self.state.current_scene_id = current_scene.id
self.state.history[-1]["ending_tag"] = self.state.ending_tag or current_scene.ending_tag
elif self.state.is_complete:
self.state.history[-1]["ending_tag"] = self.state.ending_tag
return self._build_snapshot(choice)
# -- Snapshot logic ----------------------------------------------------------------
def _build_snapshot(self, last_choice: Optional[Choice] = None) -> Dict:
"""
Build a comprehensive state snapshot for UI rendering.
"""
scene: Optional[Scene]
if self.state.current_scene_id and self.state.current_scene_id in self.game.scenes:
scene = self.game.scenes[self.state.current_scene_id]
else:
scene = None
game_over = self.state.is_complete or (scene.is_terminal if scene else True)
ending_tag = self.state.ending_tag or (scene.ending_tag if scene and scene.is_terminal else None)
scene_payload = None
if scene:
scene_payload = scene.to_dict()
if game_over:
# Do not expose further choices once the game is complete
scene_payload["choices"] = []
return {
"scene": scene_payload,
"game_over": game_over,
"ending_tag": ending_tag,
"last_choice": last_choice.to_dict() if last_choice else None,
"state": self.state.to_dict(),
"metadata": self.game.metadata,
}
# -- Serialization helpers ---------------------------------------------------------
def to_dict(self) -> Dict:
"""Serialize engine contents for persistence."""
return {
"game": self.game.to_dict(),
"state": self.state.to_dict(),
}
def snapshot(self) -> Dict:
"""Return the current engine snapshot without applying a choice."""
return self._build_snapshot(None)
@staticmethod
def from_dict(payload: Dict) -> "GameEngine":
"""Restore a `GameEngine` instance from persisted data."""
game_spec = GameSpec.from_dict(payload["game"])
game_state = GameState.from_dict(payload["state"])
return GameEngine(game_spec, game_state)