omfgg-dev / models.py
Joe Rogers
Add narrative game engine and branching story app
a4a8504
Raw History Blame Contribute Delete
5.61 kB
"""
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"),
)