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

exp_runtime/menu.py

@@ -0,0 +1,177 @@
+"""Main-menu contracts and original APK string/glyph resources.
+
+No game artwork, glyphs, or episode metadata are embedded in the engine.
+Native evidence and deliberate desktop adaptations: docs/MAIN_MENU.md.
+"""
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import tempfile
+
+from .content import is_bundled
+from .languages import TITLE_LANGUAGES, episode_title
+from .games import GAMES, game_id
+from .launcher import default_library, remember_library
+from .runtime import SaveError, Session
+from .menu_assets import MenuFont, MenuStrings
+from .ui_assets import Rect
+
+
+EPISODE_HEADER_HEIGHT = 24
+EPISODE_ROW_HEIGHT = 42
+
+
+@dataclass(frozen=True)
+class EpisodeSection:
+    key: str
+    title: str
+    episodes: tuple[dict, ...]
+
+
+def group_episodes(records, catalog, *, mega_label, novel_label, saved_label, saved=()):
+    """Native category headers with one consolidated section per category.
+
+    EXP IDs do not determine category names. Keep unidentified loose episodes
+    in numeric pack sections until the user supplies their original catalog.
+    """
+    from .episode_catalog import basename
+    groups = {}
+    for record in records:
+        label = catalog.category(record)
+        if label is None and is_bundled(record):
+            label = novel_label if basename(record['name']) == 'novel_bonus_content.exp' else mega_label
+        key = f'category:{label.casefold()}' if label is not None else f'pack:{record["pack_id"]}'
+        label = label if label is not None else f'Pack {record["pack_id"]}'
+        if key not in groups:
+            groups[key] = (label, [])
+        groups[key][1].append(record)
+    sections = [EpisodeSection(key, label, tuple(episodes)) for key, (label, episodes) in groups.items()]
+    sections.sort(key=lambda section: (
+        section.title.casefold() != mega_label.casefold(),
+        min((e['pack_id'], e['episode_id']) for e in section.episodes), section.key))
+    resumed = tuple(e for e in records if e['id'] in saved)
+    if resumed:
+        sections.insert(0, EpisodeSection('saved', saved_label, resumed))
+    return sections
+
+
+
+class MenuState:
+    """Per-library preferences and selection; saves remain content-bound.
+
+    Automatic checkpoints have their own file, preserving the player's F5
+    slot. Resume uses the newer of those two saves and validates it on load.
+    """
+    def __init__(self, library):
+        self.library = library
+        self.path = library.directory / 'player.json'
+        self.music = self.sound = True
+        self.choice_hints = False
+        self.order = 'episode'
+        self.title_language = 'en'
+        self.selected = None
+        self.warning = ''
+        if self.path.exists():
+            try:
+                data = json.loads(self.path.read_text(encoding='utf-8'))
+                if (not isinstance(data, dict) or data.get('version') != 1
+                        or type(data.get('music')) is not bool or type(data.get('sound')) is not bool
+                        or type(data.get('choice_hints', False)) is not bool
+                        or not isinstance(data.get('selected'), (str, type(None)))
+                        or data.get('order', 'episode') not in ('episode', 'title')
+                        or data.get('title_language', 'en') not in TITLE_LANGUAGES):
+                    raise ValueError('Invalid player preferences')
+                self.music, self.sound, self.selected = data['music'], data['sound'], data['selected']
+                self.order = data.get('order', 'episode')
+                self.title_language = data.get('title_language', 'en')
+                self.choice_hints = data.get('choice_hints', False)
+            except (ValueError, OSError) as error:
+                self.warning = f'Could not read preferences: {error}'
+        ids = {e['id'] for e in library.episodes}
+        if self.selected not in ids:
+            saved = [(self.resume_path(e['id']), e['id']) for e in library.episodes]
+            saved = [(p.stat().st_mtime_ns, key) for p, key in saved if p]
+            preferred = GAMES[game_id(library)].DEFAULT_EPISODE
+            default = next((e for e in library.episodes if (e.get('pack_id'), e.get('episode_id')) == preferred),
+                           library.episodes[0])
+            self.selected = max(saved)[1] if saved else default['id']
+
+    def title(self, record):
+        return episode_title(record, self.title_language)
+
+    def save_path(self, episode, *, automatic=False):
+        # Never use an arbitrary selector as part of a host path.
+        record = self.library.select(episode)
+        suffix = '.shs-auto.json' if automatic else '.shs-save.json'
+        return self.library.directory / 'saves' / (record['id'] + suffix)
+
+    def resume_path(self, episode):
+        paths = [self.save_path(episode, automatic=auto) for auto in (False, True)]
+        path = max((p for p in paths if p.is_file()), key=lambda p: p.stat().st_mtime_ns, default=None)
+        if path is not None:
+            try:
+                if path.stat().st_size > 8 * 1024 * 1024:
+                    return path  # Session.load reports the existing size limit.
+                saved = json.loads(path.read_text(encoding='utf-8'))
+                pending = saved.get('pending') if isinstance(saved, dict) else None
+                if isinstance(pending, dict) and pending.get('name') == 'episode_exit':
+                    # A validated terminal checkpoint masks older progress.
+                    # Keep the manual slot available for an explicit load.
+                    session = Session.from_snapshot(self.library.open_episode(episode), saved)
+                    if session.episode_exited:
+                        return None
+            except (SaveError, OSError, ValueError, AttributeError):
+                # Invalid saves remain resumable so loading reports the error;
+                # a malformed completion marker must not discard progress.
+                pass
+        return path
+
+    def persist(self):
+        data = dict(version=1, selected=self.selected, music=self.music, sound=self.sound,
+                    order=self.order, title_language=self.title_language, choice_hints=self.choice_hints)
+        temporary = None
+        try:
+            with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', dir=self.library.directory,
+                                             prefix='.player-', delete=False) as stream:
+                temporary = Path(stream.name)
+                json.dump(data, stream)
+                stream.write('\n')
+                stream.flush()
+                os.fsync(stream.fileno())
+            temporary.replace(self.path)
+        finally:
+            if temporary is not None:
+                temporary.unlink(missing_ok=True)
+
+    def session(self, episode, *, resume=True):
+        resources = self.library.open_episode(episode)
+        path = self.resume_path(episode) if resume else None
+        session = Session.load(resources, path) if path else Session(resources)
+        self.selected = resources.record['id']
+        self.persist()
+        return session
+
+    def checkpoint(self, session):
+        path = session.save(self.save_path(session.resources.record['id'], automatic=True))
+        self.selected = session.resources.record['id']
+        self.persist()
+        return path
+
+
+def main_button_rects(bank):
+    """000df488 + 00147df8: native four-item vertical menu, 5px gaps.
+
+    The background is layout 74; live buttons are layout 75 (184x28),
+    independently positioned over it. The fourth uses the paid/ad-free width.
+    """
+    group = bank.rectangle(74, 0)
+    button = bank.rectangle(75, 0)
+    widths = (button.width, button.width, button.width, 155)
+    total_height = button.height * 4 + 15
+    top = 480 - (group.height // 2 + 5) - total_height / 2
+    travel = int(button.width * 2.6)
+    offsets = (-50, -5, 2, -35)
+    return tuple(Rect(round(-group.width / 2 - w + offsets[i] + travel - 20 * i - w / 2),
+                      round(top + i * (button.height + 5)), w, button.height)
+                 for i, w in enumerate(widths))

exp_runtime/message_panel.py

@@ -0,0 +1,36 @@
+"""Service 33's raw-text message panel and native acknowledgement gate."""
+from dataclasses import dataclass
+
+from .vm import VMError
+
+
+@dataclass
+class MessagePanel:
+    title: str
+    text: str
+    argument: int
+    elapsed_ms: int = 0
+
+    @property
+    def ready(self):
+        return self.elapsed_ms == 1000
+
+    @property
+    def countdown(self):
+        # FUN_000aca28 uses +900, rather than rounding up with +999.
+        return (1000 - self.elapsed_ms + 900) // 1000
+
+    def tick(self, elapsed_ms):
+        self.elapsed_ms = min(1000, self.elapsed_ms + elapsed_ms)
+
+    def validate(self):
+        if (type(self.argument) is not int or not -32768 <= self.argument <= 32767
+                or type(self.elapsed_ms) is not int or not 0 <= self.elapsed_ms <= 1000):
+            raise VMError('Invalid message-panel argument or clock')
+        for value in (self.title, self.text):
+            if not isinstance(value, str) or '\0' in value:
+                raise VMError('Invalid message-panel text')
+            try:
+                value.encode('latin-1')
+            except UnicodeEncodeError:
+                raise VMError('Message-panel text must be Latin-1') from None

exp_runtime/minigames.py

@@ -0,0 +1,76 @@
+"""Shared timed word-game rules; see docs/MINIGAMES.md."""
+from dataclasses import dataclass, field
+
+
+@dataclass
+class WordGame:
+    good: list[str]
+    bad: list[str]
+    duration_ms: int
+    refresh_ms: int
+    remaining_ms: int
+    refresh_remaining_ms: int
+    options: list[str] = field(default_factory=list)
+    weights: list[int] = field(default_factory=list)
+    score: int = 0
+    round: int = 0
+    entry_ms: int = 400
+    animation_ms: int = 0
+    last_delta: int = 0
+
+    def deal(self, random):
+        """FUN_000af010: rejection sampling, then exactly twenty pair swaps."""
+        if len(self.good) < 2 or len(self.bad) < 3:
+            raise ValueError('Word game needs at least two good and three bad entries')
+        first, second = random.below(len(self.good)), random.below(len(self.bad))
+        third = random.below(len(self.bad))
+        while third == second:
+            third = random.below(len(self.bad))
+        good_fourth = random.next() & 1 == 0
+        pool, excluded = (self.good, (first,)) if good_fourth else (self.bad, (second, third))
+        fourth = random.below(len(pool))
+        while fourth in excluded:
+            fourth = random.below(len(pool))
+        self.options = [self.good[first], self.bad[second], self.bad[third], pool[fourth]]
+        self.weights = [1, -1, -1, 1 if good_fourth else -1]
+        for _ in range(20):
+            a, b = random.below(4), random.below(4)
+            self.options[a], self.options[b] = self.options[b], self.options[a]
+            self.weights[a], self.weights[b] = self.weights[b], self.weights[a]
+        self.refresh_remaining_ms = self.refresh_ms
+        self.round += 1
+
+    def pick(self, index, random):
+        if type(index) is not int or not 0 <= index < 4:
+            raise ValueError('Choose a word by its zero-based index (0–3)')
+        if self.entry_ms:
+            return False  # Native transition input gate, FUN_000afee8.
+        self.last_delta = self.weights[index]
+        self.score = max(0, self.score + self.last_delta)
+        self.deal(random)
+        self.animation_ms = 200  # New labels slide in; native input stays live.
+        return True
+
+    def tick(self, elapsed_ms):
+        self.entry_ms = max(0, self.entry_ms - elapsed_ms)
+        self.animation_ms = max(0, self.animation_ms - elapsed_ms)
+        self.remaining_ms -= elapsed_ms
+        self.refresh_remaining_ms -= elapsed_ms
+        # FUN_000ae4f4 uses a strict negative comparison. The refresh counter
+        # is stored/subtracted, but has no expiry action in this Android build.
+        return self.duration_ms > 0 and self.remaining_ms < 0
+
+    def validate(self):
+        if (len(self.good) < 2 or len(self.bad) < 3 or self.duration_ms <= 0
+                or self.duration_ms > 32767 or not -32768 <= self.refresh_ms <= 32767
+                or not 0 <= self.remaining_ms <= self.duration_ms
+                or not self.refresh_ms - self.duration_ms <= self.refresh_remaining_ms <= self.refresh_ms
+                or len(self.options) != 4 or len(self.weights) != 4
+                or sum(w == 1 for w in self.weights) not in (1, 2)
+                or any(w not in (-1, 1) for w in self.weights)
+                or any(s not in (self.good if w == 1 else self.bad)
+                       for s, w in zip(self.options, self.weights))
+                or self.round < 1 or not 0 <= self.score < self.round
+                or not 0 <= self.entry_ms <= 400 or not 0 <= self.animation_ms <= 200
+                or self.last_delta not in (-1, 0, 1)):
+            raise ValueError('Invalid saved word game')

exp_runtime/randomness.py

@@ -0,0 +1,61 @@
+"""Native random streams and pipe-delimited option parsing.
+
+Evidence and argument schemas: docs/MINIGAMES.md. Random permutations are
+part of saved gameplay state, never recomputed by a renderer.
+"""
+from dataclasses import dataclass, field
+from time import process_time_ns
+
+
+RAND48_INITIAL = 0x1234ABCD330E
+RAND48_MASK = (1 << 48) - 1
+
+
+@dataclass
+class Random48:
+    """The libc lrand48 stream for word choices, separate from services 4/27."""
+    state: int = RAND48_INITIAL
+
+    def next(self):
+        self.state = (self.state * 0x5DEECE66D + 0xB) & RAND48_MASK
+        return self.state >> 17
+
+    def below(self, bound):
+        if bound <= 0:
+            raise ValueError('Random selection needs a positive bound')
+        return self.next() % bound
+
+
+@dataclass
+class NativeRandom:
+    """0004c248 / 00126fa8 / 00122554: CPU-clock seed and 32-bit LCG.
+
+    The returned word includes bits from the full multiplication, before
+    truncating the stored state. This is not the usual ANSI rand() result.
+    """
+    state: int = field(default_factory=lambda: (process_time_ns() // 1000) & 0xffffffff)
+
+    def next(self):
+        product = self.state * 0x41c64e6d + 0x3039
+        self.state = product & 0xffffffff
+        value = (product >> 16) & 0xffffffff
+        return abs(value if value < 0x80000000 else value - 0x100000000)
+
+    def below(self, bound):
+        if bound <= 0:
+            raise ValueError('Random selection needs a positive bound')
+        return self.next() % bound
+
+    def signed_below(self, bound):
+        value, negative = self.below(bound), self.next() & 1
+        return -value if negative else value
+
+
+def pipe_list(text):
+    result = text.split('|')
+    # The native parser preserves a blank final field, including whitespace.
+    if not result[-1].strip():
+        result[-1] = ''
+    return result
+
+

exp_runtime/rar.py

@@ -0,0 +1,145 @@
+"""Bounded RAR4/RAR5 reading through libarchive, without external commands.
+
+Apple platforms use the OS library. Desktop builds for Windows/Linux bundle
+libarchive; source checkouts can use a locally installed copy. Only the RAR
+decoders are enabled, and archive member paths are never used as output paths.
+"""
+import ctypes as c
+from functools import lru_cache
+import os
+from pathlib import Path
+import sys
+
+
+class RarError(ValueError):
+    pass
+
+
+def _library_candidates():
+    if sys.platform in ('darwin', 'ios'):
+        yield '/usr/lib/libarchive.2.dylib'
+        return
+    name = 'archive.dll' if sys.platform == 'win32' else 'libarchive.so.13'
+    if bundle := getattr(sys, '_MEIPASS', None):
+        yield str(Path(bundle) / name)
+    else:
+        # The decoder is built at the workspace root, while this module lives
+        # in a component package. Locate the owning build helper instead of
+        # assuming a fixed source depth or using the caller's working directory.
+        # Installed wheels need no build tools and fall through to the system
+        # library. Frozen apps must not borrow a surrounding checkout's decoder.
+        for root in Path(__file__).resolve().parents:
+            if (root / 'tools/build_rar.py').is_file():
+                yield str(root / 'build/rar/install' / ('bin' if sys.platform == 'win32' else 'lib') / name)
+                break
+    from ctypes.util import find_library
+    if system := find_library('archive'):
+        yield system
+
+
+@lru_cache(maxsize=1)
+def library():
+    for path in _library_candidates():
+        try:
+            lib = c.CDLL(path)
+            signatures = {
+                'archive_read_new': (c.c_void_p, []),
+                'archive_read_support_format_rar': (c.c_int, [c.c_void_p]),
+                'archive_read_support_format_rar5': (c.c_int, [c.c_void_p]),
+                'archive_read_open_filename': (c.c_int, [c.c_void_p, c.c_char_p, c.c_size_t]),
+                'archive_read_next_header': (c.c_int, [c.c_void_p, c.POINTER(c.c_void_p)]),
+                'archive_read_data': (c.c_ssize_t, [c.c_void_p, c.c_void_p, c.c_size_t]),
+                'archive_read_data_skip': (c.c_int, [c.c_void_p]),
+                'archive_read_free': (c.c_int, [c.c_void_p]),
+                'archive_error_string': (c.c_char_p, [c.c_void_p]),
+                'archive_entry_pathname_utf8': (c.c_char_p, [c.c_void_p]),
+                'archive_entry_size': (c.c_int64, [c.c_void_p]),
+                'archive_entry_filetype': (c.c_uint, [c.c_void_p]),
+                'archive_entry_symlink': (c.c_char_p, [c.c_void_p]),
+                'archive_entry_hardlink': (c.c_char_p, [c.c_void_p]),
+                'archive_entry_is_encrypted': (c.c_int, [c.c_void_p]),
+            }
+            if sys.platform == 'win32':
+                signatures['archive_read_open_filename_w'] = (c.c_int, [c.c_void_p, c.c_wchar_p, c.c_size_t])
+            for name, (result, args) in signatures.items():
+                function = getattr(lib, name)
+                function.restype, function.argtypes = result, args
+            return lib
+        except (OSError, AttributeError):
+            continue
+    raise RarError('RAR support needs libarchive with RAR5 support. Install libarchive or use an '
+                   'EXP Runtime desktop download. You can also import the extracted EXP files.')
+
+
+class RarReader:
+    """Single-pass archive. Read or skip each member before advancing."""
+    def __init__(self, path):
+        self.lib, self.handle = library(), None
+        with Path(path).open('rb') as stream:
+            magic = stream.read(8)
+        if not (magic.startswith(b'Rar!\x1a\x07\x00') or magic == b'Rar!\x1a\x07\x01\x00'):
+            raise RarError('Invalid RAR signature')
+        self.handle = self.lib.archive_read_new()
+        if not self.handle:
+            raise RarError('Cannot allocate the RAR reader')
+        try:
+            self.check(self.lib.archive_read_support_format_rar(self.handle))
+            self.check(self.lib.archive_read_support_format_rar5(self.handle))
+            if sys.platform == 'win32':
+                self.check(self.lib.archive_read_open_filename_w(self.handle, str(Path(path)), 65536))
+            else:
+                self.check(self.lib.archive_read_open_filename(self.handle, os.fsencode(path), 65536))
+        except BaseException:
+            self.close()
+            raise
+
+    def check(self, status):
+        if status < 0:
+            raw = self.lib.archive_error_string(self.handle)
+            raise RarError(raw.decode('utf-8', 'replace') if raw else 'Invalid or unsupported RAR archive')
+        return status
+
+    def __iter__(self):
+        while True:
+            entry = c.c_void_p()
+            status = self.check(self.lib.archive_read_next_header(self.handle, c.byref(entry)))
+            if status == 1:  # ARCHIVE_EOF
+                return
+            raw = self.lib.archive_entry_pathname_utf8(entry)
+            if raw is None:
+                raise RarError('RAR member has an invalid filename')
+            try:
+                name = raw.decode('utf-8')
+            except UnicodeDecodeError as error:
+                raise RarError('RAR member has an invalid filename') from error
+            yield dict(name=name, size=self.lib.archive_entry_size(entry),
+                       mode=self.lib.archive_entry_filetype(entry),
+                       link=bool(self.lib.archive_entry_symlink(entry) or self.lib.archive_entry_hardlink(entry)),
+                       encrypted=bool(self.lib.archive_entry_is_encrypted(entry)))
+
+    def skip(self):
+        self.check(self.lib.archive_read_data_skip(self.handle))
+
+    def copy_to(self, destination, size):
+        buffer, total = c.create_string_buffer(65536), 0
+        while True:
+            count = self.check(self.lib.archive_read_data(self.handle, buffer, len(buffer)))
+            if count == 0:
+                break
+            total += count
+            if total > size:
+                raise RarError('RAR member exceeds its declared size')
+            destination.write(buffer.raw[:count])
+        if total != size:
+            raise RarError('RAR member is truncated')
+
+    def close(self):
+        if self.handle:
+            self.lib.archive_read_free(self.handle)
+            self.handle = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()

exp_runtime/relationships.py

@@ -0,0 +1,131 @@
+"""NPC relationship icon selection and native portrait-child actions.
+
+Evidence: FUN_000ab048, FUN_000a90f0, FUN_0009ce2c, FUN_0009caf4.
+Asset bytes remain in the player's APK. Drawing never writes relationship state.
+"""
+from dataclasses import dataclass
+import math
+
+from .games import GAMES
+
+FLASH_ASSETS = {asset: flash for game in GAMES.values() for asset, flash in game.RELATIONSHIP_FLASH.items()}
+LOSS_ASSETS = {asset: loss for game in GAMES.values() for asset, loss in game.RELATIONSHIP_LOSS.items()}
+
+
+def fraction(elapsed, duration):
+    return min(1.0, max(0.0, elapsed / duration))
+
+
+@dataclass(frozen=True)
+class RelationshipChange:
+    character_id: int
+    asset_id: int
+    count: int
+    previous_asset: int
+    previous_count: int
+
+    @property
+    def changed(self):
+        return self.previous_count != -1 and (self.asset_id, self.count) != (self.previous_asset, self.previous_count)
+
+    @property
+    def loss(self):
+        return self.asset_id >= 0 and self.changed and self.asset_id == self.previous_asset and self.count < self.previous_count
+
+    @property
+    def gain_from(self):
+        if (self.asset_id < 0 or not self.changed or self.loss
+                or (self.character_id == 45 and self.asset_id in GAMES['shs'].RELATIONSHIP_ASSETS)):
+            return None
+        return self.previous_count if self.asset_id == self.previous_asset else 0
+
+    @property
+    def extra_delay_ms(self):
+        if self.loss:
+            return 600
+        first = self.gain_from
+        return 0 if first is None else 300 + 200 * (self.count - first - 1)
+
+    @property
+    def sound(self):
+        # CoD has no verified mapping to SHS's feedback sound IDs.
+        if self.asset_id in GAMES['shs'].RELATIONSHIP_ASSETS:
+            from .shs.relationships import sound
+            return sound(self)
+        return None
+
+    def validate(self):
+        if (not 0 < self.character_id <= 32767 or (self.asset_id != -1 and self.asset_id not in FLASH_ASSETS)
+                or not 1 <= self.count <= 4 or not -32768 <= self.previous_asset <= 32767
+                or not -1 <= self.previous_count <= 4):
+            raise ValueError('Invalid relationship indicator state')
+
+
+@dataclass(frozen=True)
+class IndicatorPose:
+    asset_id: int
+    x: float
+    y: float
+    rotation: float
+    flash_asset: int = -1
+    flash_scale: float = 0.0
+    flash_alpha: int = 0
+
+
+@dataclass
+class RelationshipAnimation:
+    change: RelationshipChange
+    delay_ms: int
+    elapsed_ms: int = 0
+
+    @property
+    def duration_ms(self):
+        first = self.change.gain_from
+        if first is not None:
+            return self.delay_ms + 200 * (self.change.count - first - 1) + max(800, self.change.extra_delay_ms)
+        return max(self.delay_ms, 2000 if self.change.loss else 0)
+
+    def tick(self, elapsed_ms):
+        self.elapsed_ms = min(self.duration_ms, self.elapsed_ms + elapsed_ms)
+
+    def settle(self):
+        self.elapsed_ms = self.duration_ms
+
+    def poses(self):
+        change = self.change
+        if change.asset_id < 0 or self.elapsed_ms < self.delay_ms:
+            return ()
+        count = change.previous_count if change.loss else change.count
+        first, result = change.gain_from, []
+        for index in range(count):
+            asset, angle = change.asset_id, 195 + 20 * index
+            drop, flash_asset, flash_scale, flash_alpha = 0.0, -1, 0.0, 0
+            if index >= change.count:
+                if self.elapsed_ms >= 2000:
+                    continue
+                asset = LOSS_ASSETS[asset]
+                # Parent MoveTo(0,-500) starts after one second, independent
+                # of the incoming portrait's visibility delay.
+                drop = 500 * fraction(self.elapsed_ms - 1000, 1000)
+            elif first is not None and index >= first:
+                age = self.elapsed_ms - self.delay_ms - 200 * (index - first)
+                if age < 0:
+                    continue
+                # RotateTo uses the shortest arc (00146a88), not a 195° spin.
+                angle = (angle - 360) * fraction(age, change.extra_delay_ms)
+                flash_asset = FLASH_ASSETS[asset]
+                burst = fraction(age - 300, 500)
+                flash_scale, flash_alpha = .5 + 1.5 * burst, int(200 * (1 - burst))
+            x, y = ((61, 16), (62, 17), (62, 18), (64, 19))[index]
+            radians = math.radians(angle)
+            # Cocos rotates clockwise in GL coordinates. Convert to top Y.
+            px = x * math.cos(radians) + y * math.sin(radians)
+            py = x * math.sin(radians) - y * math.cos(radians) + drop
+            result.append(IndicatorPose(asset, px, py, angle - 190 - 20 * index,
+                                        flash_asset, flash_scale, flash_alpha))
+        return tuple(result)
+
+    def validate(self):
+        self.change.validate()
+        if not 0 <= self.delay_ms <= 850 or not 0 <= self.elapsed_ms <= self.duration_ms:
+            raise ValueError('Invalid relationship animation clock')