exp-runtime-engine 0.5.0__py3-none-any.whl

exp_runtime/episode_catalog.py

@@ -0,0 +1,171 @@
+"""Original episode categories retained in user-supplied native options files.
+
+Game profiles select the verified save envelopes; episode records share the
+same wire format. No original catalog ships with the app.
+"""
+from dataclasses import asdict, dataclass
+from pathlib import PurePosixPath
+import struct
+
+from .content import ContentError
+from .games import GAMES
+
+
+MAX_ENTRIES = 4096
+MAX_CATALOG_BYTES = 4 * 1024 * 1024
+
+
+def basename(filename):
+    # Catalog filenames identify records only. Never open their paths.
+    return PurePosixPath(filename.replace('\\', '/')).name.casefold()
+
+
+@dataclass(frozen=True)
+class CatalogEntry:
+    pack_id: int
+    episode_id: int
+    title: str
+    category: str
+    filename: str
+
+    @property
+    def key(self):
+        return self.pack_id, self.episode_id, self.title, basename(self.filename)
+
+    def validate(self):
+        if (any(type(value) is not int or not 0 <= value <= 65535
+                for value in (self.pack_id, self.episode_id))
+                or any(not isinstance(value, str) or len(value) > 32767 or '\0' in value
+                       for value in (self.title, self.category, self.filename))):
+            raise ContentError('Invalid episode catalog entry')
+
+
+class EpisodeCatalog:
+    def __init__(self, entries=()):
+        unique = {}
+        for entry in entries:
+            entry.validate()
+            unique[entry.key] = entry
+        if len(unique) > MAX_ENTRIES:
+            raise ContentError('Episode catalog contains too many entries')
+        self.entries = tuple(unique.values())
+        self.by_filename, self.by_title = {}, {}
+        for entry in self.entries:
+            if entry.filename:
+                self.by_filename.setdefault(basename(entry.filename), []).append(entry)
+            key = entry.pack_id, entry.episode_id, entry.title
+            self.by_title.setdefault(key, []).append(entry)
+
+    def merge(self, other):
+        return EpisodeCatalog((*self.entries, *other.entries))
+
+    @classmethod
+    def from_data(cls, data):
+        if not isinstance(data, list) or len(data) > MAX_ENTRIES:
+            raise ContentError('Invalid episode catalog in library')
+        try:
+            return cls(CatalogEntry(**entry) for entry in data)
+        except (TypeError, AttributeError) as error:
+            raise ContentError('Invalid episode catalog in library') from error
+
+    def to_data(self):
+        return [asdict(entry) for entry in self.entries]
+
+    def category(self, record):
+        names = {basename(name) for name in (record['name'], *record.get('aliases', []))}
+        candidates = [entry for name in names for entry in self.by_filename.get(name, ())]
+        if candidates:
+            # A catalog filename can recur in different downloads. Prefer the
+            # matching title; filenames still handle native synthetic IDs for
+            # the bundled Season 1 and novel entries.
+            candidates = [e for e in candidates if e.title == record['titles'][0]] or candidates
+        else:
+            candidates = self.by_title.get((record['pack_id'], record['episode_id'], record['titles'][0]), ())
+        categories = {e.category for e in candidates if e.category.strip()}
+        return next(iter(categories)) if len(categories) == 1 else None
+
+
+class _Reader:
+    def __init__(self, data, position):
+        self.data, self.position = data, position
+
+    def take(self, count):
+        end = self.position + count
+        if count < 0 or end > len(self.data):
+            raise ContentError('Truncated native episode catalog')
+        value = self.data[self.position:end]
+        self.position = end
+        return value
+
+    def integer(self, format):
+        return struct.unpack(format, self.take(struct.calcsize(format)))[0]
+
+    def boolean(self):
+        value = self.integer('B')
+        if value not in (0, 1):
+            raise ContentError('Invalid native catalog presence flag')
+        return bool(value)
+
+    def string(self):
+        raw = self.take(self.integer('>H'))
+        if len(raw) > 32767 or b'\0' in raw:
+            raise ContentError('Invalid native catalog string')
+        try:
+            return raw.decode('utf-8')
+        except UnicodeDecodeError:
+            # Legacy saves contain byte characters in some translated titles.
+            # EXP resource 1 remains strictly UTF-8; this is a different format.
+            return raw.decode('latin-1')
+
+    def entry(self):
+        if not self.boolean():
+            return None
+        pack, episode = self.integer('>H'), self.integer('>H')
+        titles = [self.string() for _ in range(5)]
+        categories = [self.string() for _ in range(5)]
+        filename = self.string()
+        self.integer('>i')  # Native download identifier, not a content hash.
+        return CatalogEntry(pack, episode, titles[0], categories[0], basename(filename))
+
+    def catalog(self, trailing_flags):
+        current = self.entry()
+        count = self.integer('>i')
+        if not 0 <= count <= MAX_ENTRIES:
+            raise ContentError('Invalid native catalog entry count')
+        entries = [self.entry() for _ in range(count)]
+        pairs = self.integer('>h')
+        if not 0 <= pairs <= MAX_ENTRIES:
+            raise ContentError('Invalid native string-pair count')
+        for _ in range(pairs * 2):
+            self.string()  # Discard native runtime/user strings.
+        for _ in range(trailing_flags):
+            self.boolean()
+        if self.position != len(self.data):
+            raise ContentError('Unsupported trailing native options data')
+        return EpisodeCatalog(e for e in [current, *entries] if e is not None)
+
+
+def read_options_catalog(data, *, game='shs'):
+    """Read categories only; never import native preferences or saved progress.
+
+    CoD retains the SHS signature but has its own version-17 envelope. Select
+    layouts by game, then validate all records, string pairs, flags and EOF;
+    never scan for a plausible entry or guess the game from this signature.
+    """
+    if game not in GAMES:
+        raise ContentError(f'Unknown catalog game: {game!r}')
+    profile = GAMES[game]
+    if len(data) > MAX_CATALOG_BYTES or len(data) < 16 or data[:12] != b'SHS_OPTIONS\0':
+        raise ContentError(f'Not a supported {profile.CATALOG_FILENAME} catalog')
+    version = struct.unpack_from('>i', data, 12)[0]
+    if version not in profile.CATALOG_LAYOUTS:
+        raise ContentError(f'Unsupported native options version: {version}')
+    results = []
+    for prefix, trailing_flags in profile.CATALOG_LAYOUTS[version]:
+        try:
+            results.append(_Reader(data, prefix).catalog(trailing_flags))
+        except ContentError:
+            continue
+    if len(results) != 1:
+        raise ContentError('Invalid or ambiguous native episode catalog')
+    return results[0]

exp_runtime/game_state.py

@@ -0,0 +1,9 @@
+"""Marker for saved dataclasses owned by an installed game adapter.
+
+The selected profile supplies concrete types for these fields. Saves never
+choose a Python class or module, and unsupported fields accept only None.
+"""
+
+
+class GameState:
+    pass

exp_runtime/games.py

@@ -0,0 +1,35 @@
+"""Installed game adapters; each owns its asset and host-service contracts."""
+from importlib import import_module
+from importlib.util import find_spec
+
+from .exp import ContentError
+
+
+class GameUnavailableError(ContentError):
+    """The requested game adapter has not been installed."""
+
+
+class GameRegistry(dict):
+    def __missing__(self, key):
+        if key in ('shs', 'cod'):
+            raise GameUnavailableError(
+                f'{key.upper()} support is not installed. Install "exp-runtime[{key}]".')
+        raise ContentError(f'Unknown game: {key!r}')
+
+
+GAMES = GameRegistry()
+for _key in ('shs', 'cod'):
+    # Test the package itself, so a missing dependency *inside* an installed
+    # adapter is reported instead of silently hiding a broken installation.
+    if find_spec(f'exp_runtime.{_key}') is not None:
+        _profile = import_module(f'exp_runtime.{_key}.profile')
+        GAMES[_profile.KEY] = _profile
+SHS_ANDROID = 'shs-android-1.0.9'
+SHS_IOS = 'shs-ios-assets-v1'
+COD_IOS = 'cod-ios-assets-v1'
+PROFILES = {SHS_ANDROID: ('shs', 'apk'), SHS_IOS: ('shs', 'ipa'), COD_IOS: ('cod', 'ipa')}
+
+
+def game_id(resources):
+    library = getattr(resources, 'library', resources)
+    return getattr(library, 'game_id', 'shs')

exp_runtime/ios_fonts.py

@@ -0,0 +1,228 @@
+"""Local font faces used by the iOS app; no font data is distributed.
+
+The IPA bundles Pajama Hip (505) and MonoNumerals (504). Its other fonts are
+system faces, looked up by SHSEngine::initFonts at 0003c440. Desktop glyph
+rasterization uses FreeType/Pillow, not the original CoreGraphics renderer.
+See docs/IPA.md for the resulting fidelity limits.
+"""
+from dataclasses import dataclass
+import base64
+from io import BytesIO
+import json
+import os
+import logging
+from pathlib import Path
+import re
+import struct
+import subprocess
+import sys
+
+from PIL import Image, ImageDraw, ImageFont
+
+from .fonts import BitmapFont, FontError, Glyph
+
+
+@dataclass(frozen=True)
+class IOSFont(BitmapFont):
+    cap_height: float
+    descent: float
+
+
+def _design_metrics(font, source, index):
+    """Read SFNT units, as CSFont uses CGFont metrics before rasterization.
+
+    Older supplied/system faces have no OS/2 cap-height field. CoreGraphics
+    averages the H/O tops for these faces; measure at the font's design size
+    without point-size rounding (verified against local CGFont metrics).
+    Pillow still owns font decoding, including glyph selection and advances.
+    """
+    data = source.getvalue() if isinstance(source, BytesIO) else Path(source).read_bytes()
+    try:
+        offset = struct.unpack_from('>I', data, 12 + index * 4)[0] if data[:4] == b'ttcf' else 0
+        count = struct.unpack_from('>H', data, offset + 4)[0]
+        tables = {}
+        for n in range(count):
+            tag, _, start, length = struct.unpack_from('>4sIII', data, offset + 12 + n * 16)
+            if start + length > len(data):
+                raise ValueError('Truncated font table')
+            tables[tag] = data[start:start + length]
+        units = struct.unpack_from('>H', tables[b'head'], 18)[0]
+        if not 16 <= units <= 16384:
+            raise ValueError('Invalid font units per em')
+        design = font.font_variant(size=units)
+        cap = 0
+        os2 = tables.get(b'OS/2', b'')
+        if len(os2) >= 90 and struct.unpack_from('>H', os2)[0] >= 2:
+            cap = struct.unpack_from('>h', os2, 88)[0]
+        if cap <= 0:
+            cap = sum(-design.getbbox(c, anchor='ls')[1] for c in 'HO') // 2
+        descent = -struct.unpack_from('>h', tables[b'hhea'], 6)[0]
+        return design, units, cap, descent
+    except (KeyError, struct.error, ValueError) as error:
+        raise FontError(f'Cannot read IPA font metrics: {error}') from error
+
+
+@dataclass(frozen=True)
+class FontFace:
+    family: str
+    style: str
+    filenames: tuple[str, ...]
+
+
+FACES = {
+    'PajamaHip': FontFace('Pajama Hip', 'Regular', ('PajamaHip.ttf', 'Pajama Hip.ttf')),
+    'ArialRoundedMTBold': FontFace('Arial Rounded MT Bold', 'Regular',
+                                  ('Arial Rounded Bold.ttf', 'ARLRDBD.TTF')),
+    'ArialMT': FontFace('Arial', 'Regular', ('Arial.ttf', 'arial.ttf')),
+    'TrebuchetMS_Bold': FontFace('Trebuchet MS', 'Bold', ('Trebuchet MS Bold.ttf', 'trebucbd.ttf')),
+    'TrebuchetMS_Italic': FontFace('Trebuchet MS', 'Italic', ('Trebuchet MS Italic.ttf', 'trebucit.ttf')),
+    'VerdanaBoldItalic': FontFace('Verdana', 'Bold Italic', ('Verdana Bold Italic.ttf', 'verdanaz.ttf')),
+}
+
+
+def _font_directories():
+    paths = [Path('/System/Library/Fonts/Supplemental'), Path('/System/Library/Fonts'),
+             Path('/Library/Fonts'), Path.home() / 'Library/Fonts',
+             Path('/usr/share/fonts/truetype/msttcorefonts'),
+             Path('/usr/share/fonts/truetype/msttcorefonts-installer'),
+             Path.home() / '.fonts', Path.home() / '.local/share/fonts']
+    if os.environ.get('WINDIR'):
+        paths.append(Path(os.environ['WINDIR']) / 'Fonts')
+    if os.environ.get('LOCALAPPDATA'):
+        paths.append(Path(os.environ['LOCALAPPDATA']) / 'Microsoft/Windows/Fonts')
+    return paths
+
+
+def _candidates(face):
+    wanted = {name.casefold() for name in face.filenames}
+    for directory in _font_directories():
+        try:
+            for path in sorted(directory.iterdir()):
+                if path.name.casefold() in wanted and path.is_file():
+                    yield path, 0
+        except OSError:
+            continue
+    # Fontconfig supports arbitrary Linux/user font locations. Its result can
+    # be a substitute, so resolve_face verifies the actual face before use.
+    try:
+        result = subprocess.run(['fc-match', '-f', '%{file}\n%{index}\n',
+                                 f'{face.family}:style={face.style}'],
+                                capture_output=True, text=True, timeout=5, check=True)
+        lines = result.stdout.splitlines()
+        if len(lines) == 2 and lines[1].isdigit():
+            yield Path(lines[0]), int(lines[1])
+    except (OSError, subprocess.SubprocessError, UnicodeError):
+        pass
+
+
+def resolve_face(face):
+    """Prefer the original face, then use the platform's default UI font."""
+    for path, index in _candidates(face):
+        try:
+            font = ImageFont.truetype(str(path), 16, index=index, layout_engine=ImageFont.Layout.BASIC)
+            if tuple(part.casefold() for part in font.getname()) == (face.family.casefold(), face.style.casefold()):
+                return path, index
+        except (OSError, ValueError):
+            continue
+    for path, index in _system_default(face):
+        try:
+            font = ImageFont.truetype(str(path), 16, index=index, layout_engine=ImageFont.Layout.BASIC)
+        except (OSError, ValueError):
+            continue
+        logging.warning('IPA font %s (%s) is unavailable; using system font %s (%s)',
+                        face.family, face.style, *font.getname())
+        return path, index
+    raise FontError(f'No usable system font is installed for {face.family} ({face.style}). '
+                    'Install a system UI font, then reopen the library. '
+                    'IPA asset import does not require fonts.')
+
+
+def _system_default(face):
+    if sys.platform == 'darwin':
+        for filename in (('SFNSItalic.ttf', 'SFNS.ttf') if face.style == 'Italic' else
+                         ('SFNS.ttf', 'SFNSDisplay.ttf')):
+            yield Path('/System/Library/Fonts') / filename, 0
+    elif sys.platform == 'win32':
+        directory = Path(os.environ.get('WINDIR', 'C:/Windows')) / 'Fonts'
+        filename = {'Bold': 'segoeuib.ttf', 'Italic': 'segoeuii.ttf'}.get(face.style, 'segoeui.ttf')
+        yield directory / filename, 0
+        yield directory / 'segoeui.ttf', 0
+    else:
+        # Ask fontconfig for its configured generic sans family. Here a
+        # substitution is intentional: this is the user's requested fallback.
+        generic = FontFace('sans-serif', face.style, ())
+        yield from _candidates(generic)
+
+
+def render_font(library, name):
+    """Return a text-layout font and RGBA atlas, cached only in this library."""
+    cache = getattr(library, '_ios_fonts', None)
+    if cache is None:
+        library._ios_fonts = cache = {}
+    if name in cache:
+        return cache[name]
+    color, stroke, source, index = (255, 255, 255, 255), 0, None, 0
+    if name in ('PajamaHip24', 'PajamaHip26', 'PajamaHip266', 'PajamaHipG26', 'PajamaHipY26', 'PajamaHipS26'):
+        from .games import GAMES, game_id
+        size = 24 if name == 'PajamaHip24' else 26
+        face, bundled = GAMES[game_id(library)].NAME_FONT
+        if bundled in library.base_members:
+            source = BytesIO(library.read_asset(bundled))
+        color = (*GAMES[game_id(library)].NAME_COLORS[name], 255)
+        stroke = 0 if size == 24 else 2
+    else:
+        match = re.fullmatch(r'(ArialRoundedMTBold|ArialMT|TrebuchetMS_Bold|TrebuchetMS_Italic)(11|14|15|16|20|22|28|30)', name)
+        if match is None:
+            raise FontError(f'Unsupported IPA font role: {name}')
+        face, size = match[1], int(match[2])
+    if sys.platform == 'ios':
+        # The host looks up the original system face, then the system default.
+        # Layout roles, colors and glyph history stay in this shared module.
+        import exp_platform
+        request = dict(operation='atlas', face=face, size=size, color=color, stroke=stroke)
+        if source is not None:
+            request['data'] = base64.b64encode(source.getvalue()).decode('ascii')
+        native = json.loads(exp_platform.font(json.dumps(request)))
+        glyphs = {values[0]: Glyph(*values) for values in native['glyphs']}
+        glyphs[202] = Glyph(202, 0, 0, 0, 0, 0, 0, glyphs[32].advance)
+        atlas = Image.open(BytesIO(base64.b64decode(native['png']))).convert('RGBA')
+        result = IOSFont(name, size, size, name + '.png', glyphs, {}, native['cap'], native['descent']), atlas
+        cache[name] = result
+        return result
+    if source is None:
+        sources = getattr(library, '_ios_font_sources', None)
+        if sources is None:
+            library._ios_font_sources = sources = {}
+        if face not in sources:
+            sources[face] = resolve_face(FACES[face])
+        path, index = sources[face]
+        source = str(path)
+    try:
+        # BASIC disables shaping across byte glyphs, matching KiWi's
+        # individual-character path.
+        font = ImageFont.truetype(source, size, index=index, layout_engine=ImageFont.Layout.BASIC)
+    except (OSError, ValueError) as error:
+        raise FontError(f'Cannot open IPA font {name}: {error}') from error
+    design, units, cap, descent = _design_metrics(font, source, index)
+    glyphs = {}
+    cell = (size + stroke * 2) * 3
+    atlas = Image.new('RGBA', (cell * 16, cell * 16))
+    draw = ImageDraw.Draw(atlas)
+    for code in range(32, 256):
+        if 127 <= code < 160:
+            continue
+        char = chr(code)
+        left, top, right, bottom = font.getbbox(char, anchor='ls', stroke_width=stroke)
+        x, y = code % 16 * cell, code // 16 * cell
+        if right - left > cell or bottom - top > cell:
+            raise FontError(f'IPA glyph exceeds its atlas cell: {name} U+{code:04X}')
+        draw.text((x - left, y - top), char, font=font, anchor='ls', fill=color,
+                  stroke_width=stroke, stroke_fill=(255, 255, 255, 255))
+        glyphs[code] = Glyph(code, x, y, right - left, bottom - top,
+                             left, size + top, design.getlength(char) * size / units)
+    # SHS text is byte-oriented. 0xCA is a nonbreaking space in CSFontInfo.
+    glyphs[202] = Glyph(202, 0, 0, 0, 0, 0, 0, glyphs[32].advance)
+    result = IOSFont(name, size, size, name + '.png', glyphs, {},
+                     cap * size / units, descent * size / units), atlas
+    cache[name] = result
+    return result

exp_runtime/launcher.py

@@ -0,0 +1,92 @@
+"""Per-game library locations, with read-only discovery of legacy SHS paths."""
+import json
+import os
+from pathlib import Path
+import sys
+import tempfile
+
+from .games import GAMES
+
+
+def user_data_directory() -> Path:
+    if sys.platform == 'ios':
+        return Path.home() / 'Documents' / 'EXP Runtime'
+    if sys.platform == 'darwin':
+        root = Path.home() / 'Library' / 'Application Support'
+    elif sys.platform == 'win32':
+        root = Path(os.environ.get('LOCALAPPDATA', Path.home() / 'AppData' / 'Local'))
+    else:
+        root = Path(os.environ.get('XDG_DATA_HOME', Path.home() / '.local' / 'share'))
+    return root / 'EXP Runtime'
+
+
+def library_locations():
+    root = user_data_directory()
+    locations = {}
+    for directory in (root.with_name('SHS Runtime'), root):
+        try:
+            data = json.loads((directory / 'launcher.json').read_text(encoding='utf-8'))
+            if not isinstance(data, dict):
+                continue
+            if data.get('version') == 1:
+                entries = {'shs': data.get('library')}
+            elif data.get('version') == 2 and isinstance(data.get('libraries'), dict):
+                entries = data['libraries']
+            else:
+                continue
+            for game, path in entries.items():
+                if game not in GAMES or not isinstance(path, str):
+                    continue
+                candidate = Path(path)
+                if sys.platform == 'ios':
+                    if candidate.is_absolute() or '..' in candidate.parts:
+                        continue
+                    candidate = root / candidate
+                if candidate.is_absolute():
+                    locations[game] = candidate
+        except (OSError, ValueError):
+            continue
+    return locations
+
+
+def default_library(game='shs') -> Path:
+    if game not in GAMES:
+        raise ValueError(f'Unknown game: {game}')
+    locations = library_locations()
+    if game in locations:
+        return locations[game]
+    root = user_data_directory()
+    if game == 'shs' and sys.platform != 'ios':
+        # Preserve both source-checkout and installed-app libraries in place.
+        if not getattr(sys, 'frozen', False) and Path('.shs-library/library.json').is_file():
+            return Path('.shs-library').resolve()
+        for candidate in (root / 'library', root.with_name('SHS Runtime') / 'library'):
+            if (candidate / 'library.json').is_file():
+                return candidate
+    return root / 'libraries' / game
+
+
+def remember_library(directory, game='shs'):
+    if game not in GAMES:
+        raise ValueError(f'Unknown game: {game}')
+    locations = library_locations()
+    locations[game] = Path(directory).resolve()
+    root = user_data_directory()
+    root.mkdir(parents=True, exist_ok=True)
+    if sys.platform == 'ios':
+        # Documents move with the app container. Store paths relative to the
+        # shared library root, never the current installation's UUID.
+        locations = {key: path.resolve().relative_to(root.resolve()).as_posix() for key, path in locations.items()}
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', dir=root,
+                                         prefix='.launcher-', delete=False) as stream:
+            temporary = Path(stream.name)
+            json.dump(dict(version=2, libraries={key: str(path) for key, path in locations.items()}), stream)
+            stream.write('\n')
+            stream.flush()
+            os.fsync(stream.fileno())
+        temporary.replace(root / 'launcher.json')
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)

exp_runtime/loading.py

@@ -0,0 +1,37 @@
+"""Service 91's application overlay and host execution gate.
+
+FUN_0008e7d0 accumulates active milliseconds; FUN_0009ea70 clears the
+overlay only once the counter is strictly greater than 3000.
+"""
+from dataclasses import dataclass
+
+from .vm import KiwiVM, VMError, VMStop
+
+
+def loading_waits(vm: KiwiVM, request: VMStop) -> bool:
+    """Read the dispatcher's first frame slot, even for a zero-word call.
+
+    FUN_0009fe3c reads stack[SP - argc] without checking argc. With no
+    arguments this is retained backing at SP, not an implicit zero. Unknown
+    backing must still stop explicitly through read_word().
+    """
+    return bool(request.args[0] if request.args else vm.read_word(vm.stack_base + vm.sp))
+
+
+@dataclass
+class LoadingScreen:
+    blocking: bool
+    elapsed_ms: int = 0
+
+    def tick(self, elapsed_ms: int) -> bool:
+        self.elapsed_ms = min(3001, self.elapsed_ms + elapsed_ms)
+        return self.elapsed_ms > 3000
+
+    @property
+    def frame(self):
+        # FUN_0008952c: five common-pack frames, 500 ms each, repeated.
+        return 23 + (self.elapsed_ms // 500) % 5
+
+    def validate(self):
+        if type(self.blocking) is not bool or type(self.elapsed_ms) is not int or not 0 <= self.elapsed_ms <= 3000:
+            raise VMError('Invalid loading-screen state')