exp-runtime-engine 0.5.0__tar.gz

exp_runtime_engine-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Josh Mcdaniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

exp_runtime_engine-0.5.0/MANIFEST.in

@@ -0,0 +1,4 @@
+# Only authored component source, metadata and license.
+global-exclude *
+include LICENSE README.md pyproject.toml MANIFEST.in
+recursive-include src/exp_runtime *.py

exp_runtime_engine-0.5.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: exp-runtime-engine
+Version: 0.5.0
+Summary: Headless KiWi VM, sessions, content libraries and saves
+License: MIT License
+        
+        Copyright (c) 2025 Josh Mcdaniel
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: exp-runtime-formats==0.5.0
+Provides-Extra: fonts
+Requires-Dist: Pillow>=10; extra == "fonts"
+Dynamic: license-file
+
+# EXP Runtime — engine
+
+Headless KiWi VM, sessions, content libraries and saves. This is a component of the single
+[EXP Runtime project](https://github.com/joshrmcdaniel/exp-runtime), maintained
+and released together with its other wheels. Python imports use the shared
+`exp_runtime` namespace.
+
+Install `exp-runtime[tools]` for file tools, `exp-runtime[engine,shs]` or
+`exp-runtime[engine,cod]` for a headless game, or `exp-runtime[player]` for
+the desktop player with both games. Individual component wheels also support
+selective installs. See the project's `docs/SDK.md` for APIs and examples.
+
+No original game content is included. Users supply their own game files.
+The inherited MIT license and attribution are included in LICENSE; see
+[provenance](https://github.com/joshrmcdaniel/exp-runtime/blob/main/docs/PROVENANCE.md).

exp_runtime_engine-0.5.0/README.md

@@ -0,0 +1,15 @@
+# EXP Runtime — engine
+
+Headless KiWi VM, sessions, content libraries and saves. This is a component of the single
+[EXP Runtime project](https://github.com/joshrmcdaniel/exp-runtime), maintained
+and released together with its other wheels. Python imports use the shared
+`exp_runtime` namespace.
+
+Install `exp-runtime[tools]` for file tools, `exp-runtime[engine,shs]` or
+`exp-runtime[engine,cod]` for a headless game, or `exp-runtime[player]` for
+the desktop player with both games. Individual component wheels also support
+selective installs. See the project's `docs/SDK.md` for APIs and examples.
+
+No original game content is included. Users supply their own game files.
+The inherited MIT license and attribution are included in LICENSE; see
+[provenance](https://github.com/joshrmcdaniel/exp-runtime/blob/main/docs/PROVENANCE.md).

exp_runtime_engine-0.5.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools >= 61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "exp-runtime-engine"
+version = "0.5.0"
+description = "Headless KiWi VM, sessions, content libraries and saves"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10"
+dependencies = ["exp-runtime-formats==0.5.0"]
+
+[project.optional-dependencies]
+fonts = ["Pillow>=10"]
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["exp_runtime", "exp_runtime.*"]
+namespaces = true

exp_runtime_engine-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

exp_runtime_engine-0.5.0/src/exp_runtime/audio.py

@@ -0,0 +1,13 @@
+"""Music playback routing, separate from exact script resource lookups."""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class MusicCue:
+    asset_id: int
+    start_ms: int = 0
+
+
+def music_cue(resource_id: int, *, game: str = 'shs') -> MusicCue:
+    from .games import GAMES
+    return GAMES[game].MUSIC_CUE(resource_id)

exp_runtime_engine-0.5.0/src/exp_runtime/background.py

@@ -0,0 +1,58 @@
+"""Native location alignment, independent of image decoding and drawing.
+
+Android 0007b790/00136364 move node 1000 linearly over 250 ms. SHS and
+CoD iOS use the same left/center/right targets. Store the fraction of the
+image's horizontal overflow so saves and headless execution need no pixels.
+"""
+from dataclasses import dataclass
+
+
+PAN_MS = 250
+
+
+@dataclass
+class BackgroundPan:
+    automatic: bool = True
+    alignment: int = 0  # Only consulted after service 97 supplies a value.
+    start: float = 0.5
+    target: float = 0.5
+    elapsed_ms: int = PAN_MS
+
+    @property
+    def position(self):
+        return self.start + (self.target - self.start) * (self.elapsed_ms / PAN_MS)
+
+    def center(self):
+        """A replacement background node starts at (160,180)."""
+        self.start = self.target = 0.5
+        self.elapsed_ms = PAN_MS
+
+    def align(self, alignment):
+        if not self.automatic:
+            alignment = self.alignment
+        self.start = self.position
+        # Native switch defaults to the node's current position.
+        self.target = {1: 0.0, 2: 0.5, 3: 1.0}.get(alignment, self.start)
+        self.elapsed_ms = 0
+
+    def dialogue(self, presentation):
+        if presentation in (1, 2):
+            self.align(1 if presentation == 1 else 3)
+
+    def configure(self, automatic, alignment):
+        """Service 97 also immediately requests its supplied alignment."""
+        self.automatic, self.alignment = automatic, alignment
+        self.align(alignment)
+
+    def tick(self, elapsed_ms):
+        self.elapsed_ms = min(PAN_MS, self.elapsed_ms + elapsed_ms)
+
+    def origin(self, width, height):
+        # Do not scale or clamp small images: native targets use their width.
+        return int((320 - width) * self.position), 180 - height // 2
+
+    def validate(self):
+        if (not -32768 <= self.alignment <= 32767
+                or not 0.0 <= self.start <= 1.0 or not 0.0 <= self.target <= 1.0
+                or not 0 <= self.elapsed_ms <= PAN_MS):
+            raise ValueError('Invalid background pan state')

exp_runtime_engine-0.5.0/src/exp_runtime/character_picker.py

@@ -0,0 +1,92 @@
+"""Service 78's five-position portrait selector (native UI type 5)."""
+from dataclasses import dataclass
+import math
+
+
+# DAT_0025b830, converted from GL to top-left 320 x 480 coordinates.
+POSITIONS = ((160, 275), (52, 241), (115, 170), (206, 170), (269, 241))
+SWAP_MS = 50
+
+
+@dataclass
+class PortraitMotion:
+    start: tuple[float, float, float]
+    end: tuple[float, float, float]
+    elapsed_ms: int = SWAP_MS
+    opacity: int = 255
+
+    @property
+    def pose(self):
+        t = self.elapsed_ms / SWAP_MS
+        return tuple(a + (b - a) * t for a, b in zip(self.start, self.end))
+
+
+@dataclass
+class CharacterPicker:
+    characters: list[int]
+    order: list[int]
+    portraits: list[PortraitMotion]
+
+    @classmethod
+    def start(cls, characters):
+        if not 1 <= len(characters) <= 5:
+            raise ValueError('Character selection requires 1 to 5 character IDs')
+        portraits = []
+        for slot in range(len(characters)):
+            x, y = POSITIONS[slot]
+            pose = (float(x), float(y), 1.0 if slot == 0 else 0.6)
+            portraits.append(PortraitMotion(pose, pose, opacity=255 if slot == 0 else 91))
+        return cls(list(characters), list(range(len(characters))), portraits)
+
+    @property
+    def selected(self):
+        return self.order[0]
+
+    def select(self, index):
+        """Select an original array index, without completing the VM call."""
+        if type(index) is not int or not 0 <= index < len(self.characters):
+            raise ValueError('Select a portrait by its original zero-based index')
+        slot = self.order.index(index)
+        if slot == 0:
+            return False
+        previous = self.order[0]
+        self.order[0], self.order[slot] = index, previous
+        incoming, outgoing = self.portraits[index], self.portraits[previous]
+        # FUN_000d1d78 swaps indices even during motion. It starts new actions
+        # when at least one of the two widgets has no running action.
+        if incoming.elapsed_ms == SWAP_MS or outgoing.elapsed_ms == SWAP_MS:
+            first, second = incoming.pose, outgoing.pose
+            incoming.start, incoming.end = first, (second[0], second[1], 1.0)
+            outgoing.start, outgoing.end = second, (first[0], first[1], 0.6)
+            incoming.elapsed_ms = outgoing.elapsed_ms = 0
+            for position, original in enumerate(self.order):
+                self.portraits[original].opacity = 255 if position == 0 else 91
+        return True
+
+    def tick(self, elapsed_ms):
+        for portrait in self.portraits:
+            portrait.elapsed_ms = min(SWAP_MS, portrait.elapsed_ms + elapsed_ms)
+
+    def hit(self, point):
+        """Native fixed circular hit regions, independent of animated widgets."""
+        x, y = point
+        for slot, original in enumerate(self.order):
+            cx, cy = POSITIONS[slot]
+            radius = 61 * (1 if slot == 0 else 0.6)
+            if (x - cx) ** 2 + (y - cy) ** 2 <= radius ** 2:
+                return original
+        return None
+
+    def validate(self):
+        count = len(self.characters)
+        if (not 1 <= count <= 5 or sorted(self.order) != list(range(count))
+                or len(self.portraits) != count
+                or any(not -32768 <= c <= 32767 for c in self.characters)):
+            raise ValueError('Invalid character selection state')
+        for portrait in self.portraits:
+            if not 0 <= portrait.elapsed_ms <= SWAP_MS or portrait.opacity not in (91, 255):
+                raise ValueError('Invalid portrait animation')
+            for x, y, scale in (portrait.start, portrait.end):
+                if (not all(math.isfinite(v) for v in (x, y, scale))
+                        or not 52 <= x <= 269 or not 170 <= y <= 275 or not 0.6 <= scale <= 1):
+                    raise ValueError('Invalid portrait position or scale')

exp_runtime_engine-0.5.0/src/exp_runtime/choice.py

@@ -0,0 +1,116 @@
+"""Choice-panel geometry in the original 320 by 480 coordinate system.
+
+The supplied iPhone screenshots define the visual target. Fonts, skins and
+insets come from the APK; the 44-pixel rows also occur in FUN_000d9038.
+See docs/UI_FIDELITY.md for differences from the Android Cocos drawing path.
+"""
+from dataclasses import dataclass, replace
+from functools import lru_cache
+import math
+
+from .fonts import load_font, TextLayout, TextStyle, layout_text
+from .ui_assets import LayoutBank, Rect, read_ui
+
+
+BODY_FONT = 'ArialRoundedMTBold16'
+FOOTER_FONT = 'ArialMT11'
+TITLE_FONTS = {1: 'PajamaHip26', 2: 'PajamaHip266', 3: 'PajamaHipG26'}
+
+
+@dataclass(frozen=True)
+class ChoiceRow:
+    index: int
+    rect: Rect
+    text: TextLayout
+    origin: tuple[float, float]
+    enabled: bool
+
+
+@dataclass(frozen=True)
+class ChoicePage:
+    box: Rect  # Outer border, unlike DialoguePage's center-fill rectangle.
+    title_font: str
+    title: TextLayout
+    title_origin: tuple[float, float]
+    description: TextLayout
+    description_origin: tuple[float, float]
+    portrait: Rect | None
+    rows: tuple[ChoiceRow, ...]
+    theme: int
+    max_scroll: int
+    timer_panel: Rect | None = None
+
+
+class ChoiceLayout:
+    def __init__(self, resources):
+        self.resources = resources
+        self.bank = LayoutBank.parse(read_ui(resources, 14))
+
+    @lru_cache(maxsize=8)
+    def font(self, name):
+        return load_font(self.resources.library, name)
+
+    def page(self, details, *, theme=1, has_portrait=False):
+        minigame = details.get('minigame', False)
+        timed = not minigame and details.get('timeout_ms', 0) > 0
+        width = self.bank.layouts[65].width
+        header = self.bank.rectangle(7 if has_portrait else 8, 9)
+        title_font = TITLE_FONTS.get(theme, 'PajamaHipY26')
+        title_indent = 20 if details.get('portrait_mode', 1) == 1 else 5
+        title_style = TextStyle(26, 8, indents=(0, title_indent) if has_portrait else ())
+        title = layout_text(self.font(title_font), details['title'], header.width, title_style)
+        if not has_portrait:
+            # A character-free heading occupies the full top of the panel.
+            glyphs = tuple(replace(g, x=g.x + (header.width - line.width) / 2)
+                           for line in title.lines for g in title.glyphs
+                           if line.start <= g.index < line.end)
+            title = replace(title, glyphs=glyphs)
+
+        color = {1: (1, 76, 215), 2: (166, 45, 45), 3: (108, 108, 108)}.get(theme, (223, 163, 52))
+        body_font = self.font(BODY_FONT)
+        body_rect = self.bank.rectangle(65, 4)
+        # FUN_000d9038 measures progressively around the portrait; the actual
+        # text uses the smaller nominal height configured by FUN_000d6afc.
+        indents = ()
+        if has_portrait:
+            for count in (1, 2, 3):
+                indents = (105, 95, 85)[:count]
+                measured = layout_text(body_font, details['text'], body_rect.width,
+                                       TextStyle(16, 10, color, indents=indents))
+                if len(measured.lines) <= count:
+                    break
+        description = layout_text(body_font, details['text'], body_rect.width,
+                                  TextStyle(10, 10, color, indents=indents))
+        description_y = max(26, title.height + 2)
+        header_height = math.ceil(max(112 if has_portrait else 38,
+                                      description_y + description.height + 6))
+        laid_out = []
+        for label, enabled in zip(details['options'], details['enabled']):
+            text = layout_text(body_font, label, width - 16,
+                               TextStyle(12, 1, color if enabled else (150, 150, 150)))
+            _, top, _, bottom = text.ink_bounds
+            laid_out.append((text, max(37 if minigame else 44, math.ceil(bottom - top + 16)), enabled))
+
+        footer_height = self.bank.layouts[22].height if timed else (80 if minigame else 20)
+        height = header_height + sum(h for _, h, _ in laid_out) + footer_height
+        # The reference's panel is centered below its overlapping heading.
+        # Taller lists can scroll without changing the script's option order.
+        box = Rect((320 - width) // 2, max(32, (480 - height) // 2 + (0 if minigame else 11)), width, height)
+        rows, y = [], box.y + header_height
+        for index, (text, height, enabled) in enumerate(laid_out):
+            _, top, _, bottom = text.ink_bounds
+            rect = Rect(box.x + 3, y, width - 6, height)
+            origin = (box.x + 14, y + (height - (bottom - top)) / 2 - top + 2)
+            rows.append(ChoiceRow(index, rect, text, origin, enabled))
+            y += height
+        portrait = Rect(box.x - 27, box.y - 24, 128, 128) if has_portrait else None
+        timer_panel = None
+        max_scroll = max(0, box.y + box.height - 421)
+        if timed:
+            # Layout 22 supplies the timer's lower panel. Keep it visible when
+            # the desktop's expanded rows need scrolling above the footer.
+            timer_panel = Rect(box.x, min(y, 421 - footer_height), width, footer_height)
+            max_scroll = max(0, y - timer_panel.y)
+        return ChoicePage(box, title_font, title, (box.x + header.x, box.y - 9),
+                          description, (box.x + 7, box.y + description_y), portrait,
+                          tuple(rows), theme, max_scroll, timer_panel)

exp_runtime_engine-0.5.0/src/exp_runtime/choice_hints.py

@@ -0,0 +1,153 @@
+"""Optional hints from native word scores or isolated story-choice previews.
+
+These are near-term outcome hints, not a solver for an episode's best ending.
+Recognized relationship changes, score notices and per-game answer-feedback
+sounds establish outcomes. Arbitrary counters and dialogue words do not.
+"""
+from copy import deepcopy
+from dataclasses import dataclass
+
+from .content import ContentError
+from .games import GAMES
+from .vm import VMError
+
+
+# Observed in the supplied SHS and CoD scripts. Unrecognized/localized notices
+# stay unknown; ordinary dialogue containing these words is not evidence.
+SCORE_NOTICES = frozenset(('Score Up!', 'Detective Score Up!'))
+DECISIONS = frozenset(('choice', 'character_picker', 'text_input', 'word_game',
+                       'word_grid', 'football', 'finished', 'episode_exit'))
+PANELS = frozenset(('dialogue', 'presentation', 'message_panel'))
+
+
+@dataclass(frozen=True)
+class ChoiceHint:
+    kind: str  # gain, loss, no_gain, mixed, unknown
+
+
+def preview_choices(session, *, max_steps=6000, max_panels=48, max_options=16,
+                    max_decisions=4, max_branches=192):
+    """Compare native outcomes on bounded, isolated runtime copies.
+
+    Immediate feedback takes precedence. For deferred feedback, compare the
+    same later answers across every initial option. An option dominates another
+    only if it is never worse and is better for at least one continuation.
+    Unmatched decisions, unknown services or exhausted budgets remain unknown.
+    """
+    if session.pending and session.pending.name == 'word_game':
+        # Service 71 supplies explicit good/bad answers. Read the current deal's
+        # weights, including duplicate labels and its native random order.
+        game = session.engine.word_game
+        return tuple(ChoiceHint('gain' if weight > 0 else 'loss' if weight < 0 else 'no_gain')
+                     for weight in game.weights) if game else ()
+    if not session.pending or session.pending.name != 'choice':
+        return ()
+    if min(max_steps, max_panels, max_options, max_decisions, max_branches) < 1:
+        raise ValueError('Preview budgets must be positive')
+    details = session.pending.details
+    feedback_sounds = GAMES[session.engine.game_key].CHOICE_FEEDBACK_SOUNDS
+    deadline = session.vm.steps_executed + max_steps
+    branches = 0
+
+    def follow(source, value, effects=None, panels=0):
+        nonlocal branches
+        branches += 1
+        if branches > max_branches:
+            return None
+        preview = deepcopy(source, {id(source.resources): source.resources,
+                                    id(source.vm.program): source.vm.program})
+        effects = dict(effects or {})
+
+        def observe(action):
+            if action.name == 'set_next_dialogue_notice' and action.details['text'] in SCORE_NOTICES:
+                effects['score_notice'] = effects.get('score_notice', 0) + 1
+            elif action.name == 'request_audio' and action.request.yield_id == 79:
+                feedback = feedback_sounds.get(action.details['asset_id'], 0)
+                if feedback:
+                    # Explicit correct/wrong feedback can accompany script-local
+                    # quiz scoring without a relationship or Score Up! notice.
+                    # Keep opposite cues separate so mixed feedback cannot cancel.
+                    key = 'correct_feedback' if feedback > 0 else 'incorrect_feedback'
+                    effects[key] = effects.get(key, 0) + feedback
+            elif action.name in ('set_number', 'set_number_bit'):
+                owner, key = action.details['owner'], action.details['key']
+                if owner > 0 and key == 407:
+                    address = preview.engine.number_key(owner, key)
+                    effects[address] = preview.engine.numbers[address] - session.engine.numbers.get(address, 0)
+
+        try:
+            preview._complete_choice(value)
+            while preview.vm.steps_executed < deadline:
+                action = preview.advance(max_steps=deadline - preview.vm.steps_executed,
+                                         max_events=2000, observe=observe)
+                if action.name in DECISIONS:
+                    return preview, effects, panels
+                if action.name not in PANELS or panels == max_panels:
+                    break
+                panels += 1
+                preview._complete_panel()
+                preview.engine.title_screen = preview.engine.message_panel = None
+        except (ContentError, VMError, OSError, ValueError):
+            pass
+        return None
+
+    nodes = [follow(session, value) if enabled and index < max_options else None
+             for index, (value, enabled) in enumerate(zip(details['values'], details['enabled']))]
+    hints = [ChoiceHint(_kind(node[1]) if node else 'unknown') for node in nodes]
+    if not any(node and any(node[1].values()) for node in nodes):
+        enabled = [i for i, value in enumerate(details['enabled']) if value]
+
+        def outcomes(group, depth):
+            if not group or any(node is None for node in group):
+                return None
+            if any(any(node[1].values()) for node in group):
+                return [[node[1] for node in group]]
+            actions = [node[0].pending for node in group]
+            if all(a.name in ('finished', 'episode_exit') for a in actions):
+                return [[{} for _ in group]]
+            if depth >= max_decisions or any(a.name != 'choice' for a in actions):
+                return None
+            # Match the actual script decision and result values, independently
+            # of native randomized display order. Do not guess how unrelated
+            # questions, disabled options or minigames correspond.
+            signatures = [(node[0].scene, a.request.pc,
+                           tuple(sorted(v for v, on in zip(a.details['values'], a.details['enabled']) if on)))
+                          for node, a in zip(group, actions)]
+            if any(s != signatures[0] for s in signatures) or not signatures[0][2]:
+                return None
+            values = tuple(dict.fromkeys(signatures[0][2]))
+            if len(values) > max_options:
+                return None
+            result = []
+            for value in values:
+                children = [follow(preview, value, effects, panels) for preview, effects, panels in group]
+                leaves = outcomes(children, depth + 1)
+                if leaves is None:
+                    return None
+                result.extend(leaves)
+            return result
+
+        leaves = outcomes([nodes[i] for i in enabled], 1)
+        if leaves is not None:
+            dominates = set()
+            for a in range(len(enabled)):
+                for b in range(len(enabled)):
+                    deltas = [row[a].get(key, 0) - row[b].get(key, 0)
+                              for row in leaves for key in row[a].keys() | row[b].keys()]
+                    if deltas and min(deltas) >= 0 and max(deltas) > 0:
+                        dominates.add((a, b))
+            for index, original in enumerate(enabled):
+                if any(b == index for _, b in dominates):
+                    hints[original] = ChoiceHint('no_gain')
+                elif any(a == index for a, _ in dominates):
+                    hints[original] = ChoiceHint('gain')
+    # Absence of recognized feedback alone is not proof of a wrong answer.
+    # Mark non-scoring alternatives only when this decision has a known gain.
+    has_gain = any(hint.kind == 'gain' for hint in hints)
+    return tuple(ChoiceHint('unknown') if hint.kind == 'no_gain' and not has_gain else hint
+                 for hint in hints)
+
+
+def _kind(effects):
+    gain, loss = any(v > 0 for v in effects.values()), any(v < 0 for v in effects.values())
+    return 'mixed' if gain and loss else 'gain' if gain else 'loss' if loss else 'no_gain'