Download engine.py from omfggame/omfgg-dev: direct link, hf CLI and curl.
- Browser
- Download file 6.86 kB
-
https://huggingface.co/spaces/omfggame/omfgg-dev/resolve/main/engine.py
- Command line
-
hf download hf://spaces/omfggame/omfgg-dev/engine.py
-
curl -L -o engine.py https://huggingface.co/spaces/omfggame/omfgg-dev/resolve/main/engine.py
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) | |
| 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) | |