""" Core data models for the branching narrative system. These dataclasses describe the structured content generated by the narrative composer and manipulated by the engine / UI. """ from __future__ import annotations from dataclasses import dataclass, field from typing import Any, Dict, List, Optional @dataclass class Choice: """ A single choice offered to the player within a scene. """ id: str label: str result_text: str next_scene_id: Optional[str] delta_score: int = 0 risk_level: str = "safe" # safe | risky | chaotic loot: Optional[Dict[str, Any]] = None stat_changes: Optional[Dict[str, int]] = None @staticmethod def from_dict(data: Dict[str, Any]) -> "Choice": """Create a `Choice` object from a dictionary payload.""" return Choice( id=data["id"], label=data.get("label", ""), result_text=data.get("result_text", ""), next_scene_id=data.get("next_scene_id"), delta_score=int(data.get("delta_score", 0)), risk_level=data.get("risk_level", "safe"), loot=data.get("loot"), stat_changes=data.get("stat_changes"), ) def to_dict(self) -> Dict[str, Any]: """Serialize the choice back into a JSON-friendly dict.""" return { "id": self.id, "label": self.label, "result_text": self.result_text, "next_scene_id": self.next_scene_id, "delta_score": self.delta_score, "risk_level": self.risk_level, "loot": self.loot, "stat_changes": self.stat_changes, } @dataclass class Scene: """ A single narrative scene containing story text and available choices. """ id: str title: str body: str choices: List[Choice] is_terminal: bool = False ending_tag: Optional[str] = None # win | lose | weird | etc. emoji: Optional[str] = None # optional flair for UI @staticmethod def from_dict(data: Dict[str, Any]) -> "Scene": """Create a `Scene` object from a dictionary payload.""" return Scene( id=data["id"], title=data.get("title", ""), body=data.get("body", ""), choices=[Choice.from_dict(choice) for choice in data.get("choices", [])], is_terminal=bool(data.get("is_terminal", False)), ending_tag=data.get("ending_tag"), emoji=data.get("emoji"), ) def to_dict(self) -> Dict[str, Any]: """Serialize the scene back into a JSON-friendly dict.""" return { "id": self.id, "title": self.title, "body": self.body, "choices": [choice.to_dict() for choice in self.choices], "is_terminal": self.is_terminal, "ending_tag": self.ending_tag, "emoji": self.emoji, } @dataclass class GameSpec: """ Full branching narrative specification generated by the composer. """ id: str title: str mode: str start_scene_id: str scenes: Dict[str, Scene] metadata: Dict[str, Any] = field(default_factory=dict) @staticmethod def from_dict(data: Dict[str, Any]) -> "GameSpec": """Create a `GameSpec` from a dictionary payload.""" scenes_payload = data.get("scenes", {}) return GameSpec( id=data["id"], title=data.get("title", "Untitled Adventure"), mode=data.get("mode", "Unknown"), start_scene_id=data.get("start_scene_id"), scenes={scene_id: Scene.from_dict(scene) for scene_id, scene in scenes_payload.items()}, metadata=data.get("metadata", {}), ) def to_dict(self) -> Dict[str, Any]: """Serialize the `GameSpec` into a JSON-friendly dict.""" return { "id": self.id, "title": self.title, "mode": self.mode, "start_scene_id": self.start_scene_id, "scenes": {scene_id: scene.to_dict() for scene_id, scene in self.scenes.items()}, "metadata": self.metadata, } @dataclass class GameState: """ Mutable state that tracks the player's progress within a `GameSpec`. """ game_id: str current_scene_id: str score: int = 0 inventory: List[Dict[str, Any]] = field(default_factory=list) stats: Dict[str, int] = field(default_factory=dict) history: List[Dict[str, Any]] = field(default_factory=list) is_complete: bool = False ending_tag: Optional[str] = None def to_dict(self) -> Dict[str, Any]: """Serialize the current state into a JSON-friendly dict.""" return { "game_id": self.game_id, "current_scene_id": self.current_scene_id, "score": self.score, "inventory": self.inventory, "stats": self.stats, "history": self.history, "is_complete": self.is_complete, "ending_tag": self.ending_tag, } @staticmethod def from_dict(data: Dict[str, Any]) -> "GameState": """Rehydrate a `GameState` from a dictionary payload.""" return GameState( game_id=data["game_id"], current_scene_id=data.get("current_scene_id"), score=int(data.get("score", 0)), inventory=data.get("inventory", []), stats=data.get("stats", {}), history=data.get("history", []), is_complete=bool(data.get("is_complete", False)), ending_tag=data.get("ending_tag"), )