termquest 1.0.0__py3-none-any.whl

termquest/__init__.py

@@ -0,0 +1,68 @@
+from .entity import Entity
+from .ecs import Component, EventBus, Health, Inventory, Script, System, Transform
+from .physics import PhysicsBody
+from .timer import Timer
+from .hud import bar
+from .save import SaveManager
+from .animation import Animation, Animator
+from .backend import ConsoleBackend, WindowBackend
+from .buffer import Cell, ScreenBuffer
+from .camera import Camera
+from .color import Color
+from .engine import Game
+from .geometry import Rect, Vec2
+from .image import ImageTexture
+from .input import InputState
+from .scene import Scene, SceneManager
+from .sprite import Sprite
+from .story import Story, StoryNode, StoryChoice, StoryScene, StoryFormatError
+from .tilemap import Tile, TileMap
+from .ui import (Button, CheckBox, ChoiceMenu, DialogueBox, HBox, Label, Panel, ProgressBar, Slider, TextBox, Theme, Typewriter, UIElement, UIManager, VBox, Window)
+from .world import Layer, World
+
+__all__ = [
+    'Animation','Animator','Camera','Cell','ChoiceMenu','Color','ConsoleBackend',
+    'DialogueBox','Game','ImageTexture','InputState','Layer','Rect','Scene',
+    'SceneManager','ScreenBuffer','Sprite','Story','StoryChoice','StoryNode',
+    'StoryScene','StoryFormatError','Tile','TileMap','Typewriter','Vec2',
+    'WindowBackend','World',
+    "Entity", "Component", "EventBus", "Health", "Inventory", "Script", "System", "Transform",
+    "PhysicsBody",
+    "Timer",
+    "bar",
+    "SaveManager",
+    "Button", "CheckBox", "HBox", "Label", "Panel", "ProgressBar",
+    "Slider", "TextBox", "Theme", "UIElement", "UIManager", "VBox", "Window",
+]
+
+from .config import ProjectConfig
+from .resources import ResourceManager
+from .plugins import Plugin, PluginManager
+from .scaffolding import create_project
+from .doctor import Check, run_doctor
+
+__version__ = "1.0.0"
+__all__ += ["ProjectConfig", "ResourceManager", "Plugin", "PluginManager", "create_project", "Check", "run_doctor"]
+
+from .errors import (TermQuestError, ProjectConfigError, ResourceNotFoundError, SceneLoadError, PluginLoadError, InvalidComponentError)
+from .logging import configure_logging, logger
+from .profiler import Profiler
+from .validation import ValidationIssue, validate_project
+from .crash import write_crash_report
+__all__ += ["TermQuestError", "ProjectConfigError", "ResourceNotFoundError", "SceneLoadError", "PluginLoadError", "InvalidComponentError", "configure_logging", "logger", "Profiler", "ValidationIssue", "validate_project", "write_crash_report"]
+
+from .errors import NetworkError, PlatformSDKUnavailableError
+from .network import (Lobby, LobbyProvider, MultiplayerSession, NetworkEvent,
+                      NetworkEventType, Packet, Peer, Reliability, Transport)
+from .p2p import InMemoryP2PTransport
+from .lan import LanDiscovery, LanServer, UdpP2PTransport
+from .platform_network import (BridgeLobbyProvider, BridgeTransport,
+                               EOSLobbyProvider, EOSTransport,
+                               SteamLobbyProvider, SteamTransport)
+__all__ += [
+    "NetworkError", "PlatformSDKUnavailableError", "Lobby", "LobbyProvider",
+    "MultiplayerSession", "NetworkEvent", "NetworkEventType", "Packet", "Peer",
+    "Reliability", "Transport", "InMemoryP2PTransport", "LanDiscovery",
+    "LanServer", "UdpP2PTransport", "BridgeTransport", "BridgeLobbyProvider",
+    "SteamTransport", "SteamLobbyProvider", "EOSTransport", "EOSLobbyProvider",
+]

termquest/animation.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from .sprite import Sprite
+
+@dataclass(slots=True)
+class Animation:
+    frames: list[Sprite]
+    fps: float = 8.0
+    loop: bool = True
+    playing: bool = True
+    _time: float = 0.0
+    _index: int = 0
+
+    def __post_init__(self):
+        if not self.frames: raise ValueError('Animation needs at least one frame.')
+        if self.fps <= 0: raise ValueError('fps must be positive.')
+
+    @property
+    def frame(self) -> Sprite:
+        return self.frames[self._index]
+
+    @property
+    def finished(self) -> bool:
+        return not self.loop and self._index == len(self.frames)-1 and not self.playing
+
+    def play(self, restart: bool = False) -> None:
+        if restart: self.reset()
+        self.playing = True
+
+    def pause(self) -> None: self.playing = False
+
+    def reset(self) -> None:
+        self._time=0.0; self._index=0
+
+    def update(self, dt: float) -> None:
+        if not self.playing or len(self.frames)==1: return
+        self._time += dt
+        step=1.0/self.fps
+        while self._time >= step:
+            self._time -= step
+            if self._index + 1 >= len(self.frames):
+                if self.loop: self._index=0
+                else:
+                    self._index=len(self.frames)-1; self.playing=False; break
+            else: self._index += 1
+
+@dataclass(slots=True)
+class Animator:
+    animations: dict[str, Animation] = field(default_factory=dict)
+    current_name: str | None = None
+
+    def add(self, name: str, animation: Animation) -> "Animator":
+        self.animations[name]=animation
+        if self.current_name is None: self.current_name=name
+        return self
+
+    def play(self, name: str, restart: bool = False) -> None:
+        if name not in self.animations: raise KeyError(name)
+        if name != self.current_name or restart:
+            self.current_name=name; self.animations[name].reset()
+        self.animations[name].play()
+
+    @property
+    def frame(self) -> Sprite:
+        if self.current_name is None: raise RuntimeError('Animator has no animation.')
+        return self.animations[self.current_name].frame
+
+    def update(self, dt: float) -> None:
+        if self.current_name is not None: self.animations[self.current_name].update(dt)

termquest/backend.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+import os
+import sys
+from abc import ABC, abstractmethod
+from .buffer import ScreenBuffer
+from .input import InputState, ConsoleInputReader
+
+class Backend(ABC):
+    def __init__(self, width: int, height: int) -> None:
+        self.width = width
+        self.height = height
+
+    @abstractmethod
+    def open(self, input_state: InputState) -> None: ...
+
+    @abstractmethod
+    def poll(self, input_state: InputState) -> bool: ...
+
+    @abstractmethod
+    def present(self, screen: ScreenBuffer) -> None: ...
+
+    @abstractmethod
+    def close(self) -> None: ...
+
+class ConsoleBackend(Backend):
+    def __init__(self, width: int, height: int, title: str = "TermQuest") -> None:
+        super().__init__(width, height)
+        self.title = title
+        self._reader = None
+
+    def open(self, input_state: InputState) -> None:
+        if os.name == "nt":
+            os.system("")
+            os.system(f"title {self.title}")
+        self._reader = ConsoleInputReader(input_state)
+        self._reader.__enter__()
+        sys.stdout.write("\x1b[?25l\x1b[2J\x1b[H")
+        sys.stdout.flush()
+
+    def poll(self, input_state: InputState) -> bool:
+        assert self._reader is not None
+        self._reader.poll()
+        return True
+
+    def present(self, screen: ScreenBuffer) -> None:
+        out = ["\x1b[H"]
+        last_fg = last_bg = None
+        for y in range(screen.height):
+            for x in range(screen.width):
+                cell = screen.get(x, y)
+                if cell.fg != last_fg:
+                    out.append(f"\x1b[38;2;{cell.fg.r};{cell.fg.g};{cell.fg.b}m")
+                    last_fg = cell.fg
+                if cell.bg != last_bg:
+                    out.append(f"\x1b[48;2;{cell.bg.r};{cell.bg.g};{cell.bg.b}m")
+                    last_bg = cell.bg
+                out.append(cell.char)
+            if y != screen.height - 1:
+                out.append("\n")
+        out.append("\x1b[0m")
+        sys.stdout.write("".join(out))
+        sys.stdout.flush()
+
+    def close(self) -> None:
+        if self._reader is not None:
+            self._reader.__exit__(None, None, None)
+        sys.stdout.write("\x1b[0m\x1b[?25h\n")
+        sys.stdout.flush()
+
+class WindowBackend(Backend):
+    def __init__(
+        self,
+        width: int,
+        height: int,
+        title: str = "TermQuest",
+        font_family: str = "Consolas",
+        font_size: int = 18,
+    ) -> None:
+        super().__init__(width, height)
+        self.title = title
+        self.font_family = font_family
+        self.font_size = font_size
+        self.root = None
+        self.text = None
+        self._alive = True
+
+    def open(self, input_state: InputState) -> None:
+        import tkinter as tk
+        from tkinter import font
+
+        self.root = tk.Tk()
+        self.root.title(self.title)
+        self.root.resizable(False, False)
+
+        fixed = font.Font(family=self.font_family, size=self.font_size)
+        self.text = tk.Text(
+            self.root,
+            width=self.width,
+            height=self.height,
+            font=fixed,
+            wrap="none",
+            borderwidth=0,
+            highlightthickness=0,
+            state="disabled",
+            cursor="arrow",
+        )
+        self.text.pack()
+        self.text.tag_configure("_default", foreground="#ffffff", background="#000000")
+
+        def down(event):
+            key = event.keysym.lower()
+            aliases = {"return": "enter", "esc": "escape"}
+            input_state.feed_key_down(aliases.get(key, key))
+            if event.char and event.char.isprintable():
+                input_state.feed_text(event.char)
+            return "break"
+
+        def up(event):
+            key = event.keysym.lower()
+            aliases = {"return": "enter", "esc": "escape"}
+            input_state.feed_key_up(aliases.get(key, key))
+            return "break"
+
+        def close():
+            self._alive = False
+
+        self.root.bind("<KeyPress>", down)
+        self.root.bind("<KeyRelease>", up)
+        self.root.protocol("WM_DELETE_WINDOW", close)
+        self.root.focus_force()
+
+    def poll(self, input_state: InputState) -> bool:
+        if not self._alive or self.root is None:
+            return False
+        try:
+            self.root.update_idletasks()
+            self.root.update()
+            return True
+        except Exception:
+            return False
+
+    def present(self, screen: ScreenBuffer) -> None:
+        if self.text is None:
+            return
+
+        self.text.configure(state="normal")
+        self.text.delete("1.0", "end")
+
+        tag_cache = {}
+        for y in range(screen.height):
+            for x in range(screen.width):
+                cell = screen.get(x, y)
+                key = (cell.fg, cell.bg)
+                tag = tag_cache.get(key)
+                if tag is None:
+                    tag = f"c{len(tag_cache)}"
+                    tag_cache[key] = tag
+                    self.text.tag_configure(
+                        tag,
+                        foreground=f"#{cell.fg.r:02x}{cell.fg.g:02x}{cell.fg.b:02x}",
+                        background=f"#{cell.bg.r:02x}{cell.bg.g:02x}{cell.bg.b:02x}",
+                    )
+                self.text.insert("end", cell.char, tag)
+            if y != screen.height - 1:
+                self.text.insert("end", "\n")
+        self.text.configure(state="disabled")
+
+    def close(self) -> None:
+        if self.root is not None:
+            try:
+                self.root.destroy()
+            except Exception:
+                pass

termquest/buffer.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from .color import Color, BLACK, WHITE
+
+@dataclass(slots=True)
+class Cell:
+    char: str = " "
+    fg: Color = WHITE
+    bg: Color = BLACK
+
+    def __post_init__(self) -> None:
+        if len(self.char) != 1:
+            raise ValueError("A cell must contain exactly one character.")
+
+class ScreenBuffer:
+    def __init__(self, width: int, height: int) -> None:
+        if width <= 0 or height <= 0:
+            raise ValueError("Screen dimensions must be positive.")
+        self.width = width
+        self.height = height
+        self._cells = [Cell() for _ in range(width * height)]
+
+    def _index(self, x: int, y: int) -> int:
+        return y * self.width + x
+
+    def in_bounds(self, x: int, y: int) -> bool:
+        return 0 <= x < self.width and 0 <= y < self.height
+
+    def get(self, x: int, y: int) -> Cell:
+        if not self.in_bounds(x, y):
+            raise IndexError((x, y))
+        return self._cells[self._index(x, y)]
+
+    def put(
+        self,
+        x: int,
+        y: int,
+        char: str = " ",
+        fg: Color = WHITE,
+        bg: Color = BLACK,
+    ) -> None:
+        if self.in_bounds(x, y):
+            self._cells[self._index(x, y)] = Cell(char, fg, bg)
+
+    def clear(self, char: str = " ", fg: Color = WHITE, bg: Color = BLACK) -> None:
+        cell = Cell(char, fg, bg)
+        self._cells = [Cell(cell.char, cell.fg, cell.bg) for _ in self._cells]
+
+    def text(
+        self,
+        x: int,
+        y: int,
+        value: str,
+        fg: Color = WHITE,
+        bg: Color = BLACK,
+        wrap: bool = False,
+    ) -> None:
+        cx, cy = x, y
+        for ch in value:
+            if ch == "\n":
+                cx, cy = x, cy + 1
+                continue
+            if wrap and cx >= self.width:
+                cx, cy = 0, cy + 1
+            self.put(cx, cy, ch, fg, bg)
+            cx += 1
+
+    def fill_rect(
+        self,
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+        char: str = " ",
+        fg: Color = WHITE,
+        bg: Color = BLACK,
+    ) -> None:
+        for py in range(y, y + height):
+            for px in range(x, x + width):
+                self.put(px, py, char, fg, bg)
+
+    def box(
+        self,
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+        fg: Color = WHITE,
+        bg: Color = BLACK,
+    ) -> None:
+        if width < 2 or height < 2:
+            return
+        self.put(x, y, "┌", fg, bg)
+        self.put(x + width - 1, y, "┐", fg, bg)
+        self.put(x, y + height - 1, "└", fg, bg)
+        self.put(x + width - 1, y + height - 1, "┘", fg, bg)
+        for px in range(x + 1, x + width - 1):
+            self.put(px, y, "─", fg, bg)
+            self.put(px, y + height - 1, "─", fg, bg)
+        for py in range(y + 1, y + height - 1):
+            self.put(x, py, "│", fg, bg)
+            self.put(x + width - 1, py, "│", fg, bg)
+
+    def cells(self) -> list[Cell]:
+        return self._cells

termquest/camera.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+import random
+from dataclasses import dataclass
+from .geometry import Vec2
+
+@dataclass(slots=True)
+class Camera:
+    x: float = 0.0
+    y: float = 0.0
+    smoothing: float = 0.0
+    _target: object | None = None
+    _shake_time: float = 0.0
+    _shake_strength: float = 0.0
+    _offset: Vec2 = None
+
+    def __post_init__(self):
+        self._offset = Vec2()
+
+    def follow(self, target: object) -> None:
+        self._target = target
+
+    def unfollow(self) -> None:
+        self._target = None
+
+    def move(self, dx: float, dy: float) -> None:
+        self.x += dx
+        self.y += dy
+
+    def shake(self, strength: float = 1.0, duration: float = 0.2) -> None:
+        self._shake_strength = max(0.0, strength)
+        self._shake_time = max(0.0, duration)
+
+    def update(self, dt: float, viewport_width: int, viewport_height: int) -> None:
+        if self._target is not None:
+            tx = float(getattr(self._target, 'x', 0)) + float(getattr(self._target, 'width', 1)) / 2 - viewport_width / 2
+            ty = float(getattr(self._target, 'y', 0)) + float(getattr(self._target, 'height', 1)) / 2 - viewport_height / 2
+            if self.smoothing <= 0:
+                self.x, self.y = tx, ty
+            else:
+                alpha = min(1.0, self.smoothing * dt)
+                self.x += (tx - self.x) * alpha
+                self.y += (ty - self.y) * alpha
+        if self._shake_time > 0:
+            self._shake_time = max(0.0, self._shake_time - dt)
+            self._offset = Vec2(random.uniform(-1,1)*self._shake_strength, random.uniform(-1,1)*self._shake_strength)
+        else:
+            self._offset = Vec2()
+
+    def world_to_screen(self, x: float, y: float) -> tuple[int, int]:
+        return round(x - self.x + self._offset.x), round(y - self.y + self._offset.y)

termquest/cli.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+import argparse, os, platform, runpy, shutil, subprocess, sys, time
+from pathlib import Path
+from .doctor import run_doctor
+from .plugins import PluginManager
+from .scaffolding import create_project
+from .validation import validate_project
+VERSION="1.0.0"
+
+def parser() -> argparse.ArgumentParser:
+    p=argparse.ArgumentParser(prog="termquest",description="TermQuest developer tools")
+    p.add_argument("--version",action="version",version=f"TermQuest {VERSION}")
+    commands=p.add_subparsers(dest="command")
+    new=commands.add_parser("new"); new.add_argument("name"); new.add_argument("--destination",default="."); new.add_argument("--force",action="store_true")
+    run=commands.add_parser("run"); run.add_argument("path",nargs="?",default=".")
+    doctor=commands.add_parser("doctor"); doctor.add_argument("path",nargs="?",default=".")
+    test=commands.add_parser("test"); test.add_argument("path",nargs="?",default=".")
+    clean=commands.add_parser("clean"); clean.add_argument("path",nargs="?",default=".")
+    validate=commands.add_parser("validate"); validate.add_argument("path",nargs="?",default=".")
+    plugins=commands.add_parser("list-plugins"); plugins.add_argument("path",nargs="?",default=".")
+    bench=commands.add_parser("benchmark"); bench.add_argument("--iterations",type=int,default=100000)
+    network=commands.add_parser("network-info")
+    network.add_argument("--backend", choices=("lan","p2p","steam","eos","all"), default="all")
+    commands.add_parser("info"); commands.add_parser("version")
+    return p
+
+def main(argv: list[str] | None = None) -> int:
+    args=parser().parse_args(argv)
+    if args.command=="new":
+        try: target=create_project(args.name,args.destination,force=args.force)
+        except FileExistsError as exc: print(f"error: {exc}",file=sys.stderr); return 2
+        print(f"Created TermQuest project: {target}"); return 0
+    if args.command=="run":
+        root=Path(args.path).resolve(); main_file=root/"main.py"
+        if not main_file.exists(): print(f"error: {main_file} not found",file=sys.stderr); return 2
+        old=Path.cwd(); sys.path.insert(0,str(root))
+        try: os.chdir(root); runpy.run_path(str(main_file),run_name="__main__")
+        finally: os.chdir(old); sys.path.pop(0)
+        return 0
+    if args.command=="doctor":
+        checks=run_doctor(args.path)
+        for c in checks: print(f"[{'OK' if c.ok else 'FAIL'}] {c.name}: {c.detail}")
+        return 0 if all(c.ok or c.name in {"Pillow","UTF-8"} for c in checks) else 1
+    if args.command=="test": return subprocess.call([sys.executable,"-m","pytest",str(Path(args.path)/"tests")])
+    if args.command=="clean":
+        removed=0
+        for name in ("__pycache__",".pytest_cache"):
+            for path in Path(args.path).rglob(name):
+                if path.is_dir(): shutil.rmtree(path); removed+=1
+        print(f"Removed {removed} cache directories."); return 0
+    if args.command=="validate":
+        issues=validate_project(args.path)
+        if not issues: print("Project validation passed."); return 0
+        for issue in issues: print(f"[{issue.level.upper()}] {issue.path}: {issue.message}")
+        return 1 if any(i.level=="error" for i in issues) else 0
+    if args.command=="list-plugins":
+        manager=PluginManager(Path(args.path)/"plugins")
+        paths=manager.discover()
+        if not paths: print("No plugins found.")
+        else:
+            for path in paths: print(path.stem)
+        return 0
+    if args.command=="benchmark":
+        start=time.perf_counter(); total=0
+        for i in range(args.iterations): total += i
+        elapsed=time.perf_counter()-start
+        print(f"{args.iterations} iterations in {elapsed*1000:.3f} ms ({total})"); return 0
+    if args.command=="info":
+        print(f"TermQuest {VERSION}")
+        print(f"Python {platform.python_version()}")
+        print(platform.platform()); return 0
+    if args.command=="network-info":
+        backends = {
+            "lan": "Built-in UDP discovery + direct UDP transport",
+            "p2p": "Built-in in-memory/direct peer transport APIs",
+            "steam": "Bridge adapter for Steamworks Networking Messages/Sockets and Lobbies",
+            "eos": "Bridge adapter for EOS P2P and Lobbies",
+        }
+        for name, detail in backends.items():
+            if args.backend in ("all", name): print(f"{name}: {detail}")
+        return 0
+    if args.command=="version": print(f"TermQuest {VERSION}"); return 0
+    parser().print_help(); return 0
+
+if __name__=="__main__": raise SystemExit(main())

termquest/color.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True)
+class Color:
+    r: int
+    g: int
+    b: int
+
+    def __post_init__(self) -> None:
+        for value in (self.r, self.g, self.b):
+            if not 0 <= value <= 255:
+                raise ValueError("RGB values must be between 0 and 255.")
+
+    @classmethod
+    def from_hex(cls, value: str) -> "Color":
+        value = value.strip().lstrip("#")
+        if len(value) != 6:
+            raise ValueError("Expected a 6-digit hex color.")
+        return cls(*(int(value[i:i+2], 16) for i in (0, 2, 4)))
+
+    @staticmethod
+    def lerp(a: "Color", b: "Color", t: float) -> "Color":
+        t = max(0.0, min(1.0, t))
+        return Color(
+            round(a.r + (b.r - a.r) * t),
+            round(a.g + (b.g - a.g) * t),
+            round(a.b + (b.b - a.b) * t),
+        )
+
+BLACK = Color(0, 0, 0)
+WHITE = Color(255, 255, 255)

termquest/config.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+import tomllib
+
+@dataclass(slots=True)
+class ProjectConfig:
+    title: str = "TermQuest Game"
+    width: int = 80
+    height: int = 30
+    fps: int = 30
+    backend: str = "console"
+    start_scene: str = "main"
+
+    @classmethod
+    def load(cls, path: str | Path = "termquest.toml") -> "ProjectConfig":
+        file = Path(path)
+        if not file.exists():
+            return cls()
+        with file.open("rb") as stream:
+            values = tomllib.load(stream).get("game", {})
+        defaults = cls()
+        return cls(
+            title=str(values.get("title", defaults.title)),
+            width=int(values.get("width", defaults.width)),
+            height=int(values.get("height", defaults.height)),
+            fps=int(values.get("fps", defaults.fps)),
+            backend=str(values.get("backend", defaults.backend)),
+            start_scene=str(values.get("start_scene", defaults.start_scene)),
+        )

termquest/crash.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+from datetime import datetime
+from pathlib import Path
+import platform, sys, traceback
+
+def write_crash_report(exc: BaseException, directory: str | Path = "crash_reports", **context: object) -> Path:
+    directory = Path(directory)
+    directory.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    path = directory / f"crash-{stamp}.txt"
+    lines = [
+        "TermQuest crash report",
+        f"Python: {sys.version}",
+        f"Platform: {platform.platform()}",
+        f"Exception: {type(exc).__name__}: {exc}",
+    ]
+    for key, value in context.items():
+        lines.append(f"{key}: {value}")
+    lines.extend(["", "Traceback:", "".join(traceback.format_exception(exc))])
+    path.write_text("\n".join(lines), encoding="utf-8")
+    return path