exp-runtime-creator 0.6.0__py3-none-any.whl

exp_runtime/creator/playtest.py

@@ -0,0 +1,185 @@
+"""Bounded, reproducible player-input workflows over the production debugger."""
+from .model import ProjectError
+
+ENDS = {'episode_exit', 'finished'}
+INPUTS = {'choice', 'text_input', 'word_game', 'word_grid', 'football', 'character_picker'}
+ACKNOWLEDGE = {'dialogue', 'presentation', 'message_panel', 'survey_confirmation'}
+
+
+class Playtest:
+    def __init__(self, debugger):
+        self.debugger = debugger
+        self.transcript = []
+        self.last_event = None
+        self.sequence = 0
+        self.error = None
+
+    def capture(self):
+        raw = self.debugger.state()
+        details = raw['details']
+        token = (raw['scene'], raw['pc'], self.debugger.session.vm.steps_executed,
+                 raw['action'], details.get('page_start'))
+        if raw['action'] and token != self.last_event:
+            self.last_event = token
+            self.sequence += 1
+            self.transcript.append(dict(sequence=self.sequence, node_id=raw['node'], action=raw['action'],
+                speaker=details.get('speaker', details.get('title', '')), text=details.get('text', details.get('prompt', '')),
+                options=self.choices(raw), page_start=details.get('page_start')))
+            del self.transcript[:-200]
+        return raw
+
+    def choices(self, raw):
+        if raw['action'] != 'choice': return []
+        details = raw['details']
+        return [dict(id=f'{raw["node"]}:{value}', text=text, enabled=enabled, visible_index=index)
+                for index, (text, value, enabled) in enumerate(zip(details['options'], details['values'], details['enabled']))]
+
+    def state(self, *, verbose=False):
+        raw = self.capture()
+        action = raw['action']
+        choices = self.choices(raw)
+        actions = []
+        if action in ACKNOWLEDGE or action == 'vm_pause': actions.append('continue')
+        if action == 'choice': actions.append('choose')
+        if action == 'text_input': actions.append('answer_text')
+        if action in ('word_game', 'football', 'character_picker'): actions.append('answer')
+        if action == 'word_grid': actions.append('grid_pointer')
+        if action not in ENDS and action is not None: actions.append('tick')
+        if action is None: actions.extend(('run', 'step'))
+        result = dict(node_id=raw['node'], scene=raw['scene'], pc=raw['pc'], action=action,
+            paused=self.debugger.paused, variables=raw['variables'], text_variables=raw['text_variables'],
+            text=raw['details'].get('text', raw['details'].get('prompt', '')),
+            speaker=raw['details'].get('speaker', raw['details'].get('title', '')), choices=choices,
+            remaining_ms=self.debugger.session.remaining_ms, next_actions=actions,
+            visited_count=len(self.debugger.visited), seed=self.debugger.seed,
+            manual_overrides=list(self.debugger.overrides), error=self.error)
+        if action not in INPUTS | ACKNOWLEDGE | ENDS | {'loading', None}:
+            result.update(pending_arguments=raw['pending_arguments'], details=raw['details'])
+        if verbose: result['vm'] = raw
+        return result
+
+    def perform(self, operation):
+        before = self.debugger.state()['variables']
+        sequence = self.sequence
+        self.error = None
+        try:
+            reason = operation()
+        except (ValueError, KeyError, IndexError) as error:
+            # A real VM/service failure is visible and stays suspended. Do not
+            # supply a guessed callback result or roll gameplay forward.
+            self.error = str(error)
+            reason = 'error'
+        result = self.state()
+        result.update(stop_reason=reason, variable_changes={key: dict(before=before.get(key), after=value)
+            for key, value in result['variables'].items() if before.get(key) != value},
+            transcript=[row for row in self.transcript if row['sequence'] > sequence],
+            transcript_truncated=self.sequence - sequence > 200)
+        return result
+
+    def run(self, *, until='input', node_id=None, max_operations=500, max_ms=60000):
+        if until not in ('input', 'choice', 'end', 'node'): raise ProjectError('Use until input, choice, end or node')
+        if until == 'node' and node_id not in {n.id for n in self.debugger.project.nodes}:
+            raise ProjectError('Select an existing node as the stopping point')
+        if type(max_operations) is not int or not 1 <= max_operations <= 2000:
+            raise ProjectError('Operation budget must be 1–2000')
+        if type(max_ms) is not int or not 0 <= max_ms <= 60000:
+            raise ProjectError('Clock budget must be 0–60000 ms')
+        def execute():
+            elapsed = 0
+            original = set(self.debugger.breakpoints)
+            if until == 'node': self.debugger.breakpoints.add(node_id)
+            try:
+                for _ in range(max_operations):
+                    raw = self.capture(); action = raw['action']
+                    if action in ENDS: return 'end'
+                    if self.debugger.paused and (raw['node'] == node_id or raw['node'] in original): return 'breakpoint'
+                    if action in INPUTS: return 'choice' if action == 'choice' else 'input'
+                    if until == 'input' and action in ACKNOWLEDGE: return 'input'
+                    if action in ACKNOWLEDGE:
+                        session = self.debugger.session
+                        ready = (session.engine.dialogue_animation.complete if action == 'dialogue' else
+                                 session.engine.title_screen.ready if action == 'presentation' else
+                                 session.engine.message_panel.ready)
+                        if ready:
+                            self.debugger.resume(provide_answer=True)
+                        else:
+                            if elapsed >= max_ms: return 'clock_budget'
+                            step = min(100, max_ms - elapsed)
+                            self.debugger.resume(milliseconds=step); elapsed += step
+                    elif action == 'loading':
+                        if elapsed >= max_ms: return 'clock_budget'
+                        step = min(100, max_ms - elapsed)
+                        self.debugger.resume(milliseconds=step); elapsed += step
+                    elif action is None:
+                        self.debugger.resume()
+                    else:
+                        return 'unsupported'  # Includes explicit VM pauses; only manual input may resume those.
+                return 'operation_budget'
+            finally:
+                self.debugger.breakpoints = original
+        return self.perform(execute)
+
+    def choose(self, option_id):
+        raw = self.debugger.state()
+        option = next((o for o in self.choices(raw) if o['id'] == option_id), None)
+        if option is None or not option['enabled']: raise ProjectError('Choose an enabled option ID from the current state')
+        return self.perform(lambda: self.debugger.resume(answer=option['visible_index'], provide_answer=True) and 'input')
+
+    def input(self, action, *, value=None, milliseconds=0, phase=None, cell=None):
+        if action not in ('continue', 'answer_text', 'answer', 'tick', 'step', 'grid_pointer'):
+            raise ProjectError('Unknown playtest input')
+        if type(milliseconds) is not int or not 0 <= milliseconds <= 60000:
+            raise ProjectError('Clock step must be 0–60000 ms')
+        def execute():
+            if action == 'tick':
+                if milliseconds: self.debugger.resume(milliseconds=milliseconds)
+            elif action == 'step': self.debugger.resume(step=True)
+            elif action == 'grid_pointer':
+                from .debugger import _Paused
+                if phase not in ('down', 'move', 'up', 'cancel'): raise ProjectError('Invalid pointer phase')
+                try: self.debugger.session.grid_pointer(phase, cell)
+                except _Paused: pass
+            else:
+                self.debugger.resume(answer=None if action == 'continue' else value, provide_answer=True)
+            return 'input'
+        return self.perform(execute)
+
+
+def run_scenario(debugger, scenario):
+    """Replay a declarative scenario. No eval, arbitrary code or fabricated results."""
+    steps = scenario.get('steps', [])
+    assertions = scenario.get('assertions', [])
+    if (not isinstance(steps, list) or len(steps) > 200 or not isinstance(assertions, list) or
+            len(assertions) > 200 or set(scenario) - {'seed', 'start', 'language', 'steps', 'assertions'}):
+        raise ProjectError('A scenario allows seed/start/language, up to 200 steps and 200 assertions')
+    test, results, failures = Playtest(debugger), [], []
+    for index, step in enumerate(steps):
+        try:
+            args = dict(step); action = args.pop('action')
+            if action == 'run': result = test.run(**args)
+            elif action == 'choose': result = test.choose(**args)
+            else: result = test.input(action, **args)
+            results.append(dict(step=index, action=result['action'], node_id=result['node_id'],
+                                stop_reason=result['stop_reason'], variable_changes=result['variable_changes']))
+            if result['stop_reason'] in ('error', 'unsupported', 'operation_budget', 'clock_budget'):
+                failures.append(dict(step=index, message=result['error'] or result['stop_reason'])); break
+        except (TypeError, ValueError, KeyError) as error:
+            failures.append(dict(step=index, message=str(error))); break
+    state = test.state()
+    for index, assertion in enumerate(assertions):
+        kind = assertion.get('kind') if isinstance(assertion, dict) else None
+        if kind in ('variable', 'text_variable'):
+            values = state['variables' if kind == 'variable' else 'text_variables']
+            if assertion.get('name') not in values or 'equals' not in assertion:
+                failures.append(dict(assertion=index, message='Name must identify an existing variable and equals is required')); continue
+            actual, expected = values[assertion['name']], assertion['equals']
+        elif kind == 'node': actual, expected = state['node_id'], assertion.get('equals')
+        elif kind == 'action': actual, expected = state['action'], assertion.get('equals')
+        elif kind == 'visited': actual, expected = assertion.get('node_id') in debugger.visited, True
+        elif kind == 'ended': actual, expected = state['action'] in ENDS, True
+        else:
+            failures.append(dict(assertion=index, message='Unknown assertion kind')); continue
+        if actual != expected:
+            failures.append(dict(assertion=index, message='Assertion failed', actual=actual, expected=expected))
+    return dict(passed=not failures, failures=failures, steps=results, state=state, transcript=test.transcript,
+                coverage=dict(visited=sorted(debugger.visited), total=len(debugger.project.nodes)))

exp_runtime/creator/preview.py

@@ -0,0 +1,30 @@
+"""Run an exported episode with the production player and isolated saves."""
+from contextlib import contextmanager
+from copy import copy
+from pathlib import Path
+import tempfile
+
+from exp_runtime.content import ContentLibrary, EpisodeResources, digest
+from exp_runtime.exp import ExpArchive
+from .model import ProjectError
+
+
+@contextmanager
+def preview_resources(data, library_path, game):
+    archive = ExpArchive(data)
+    meta = archive.metadata()
+    with ContentLibrary(Path(library_path)) as library:
+        if library.game_id != game:
+            raise ProjectError('Preview library does not match the project game')
+        with tempfile.TemporaryDirectory(prefix='exp-creator-preview-') as temporary:
+            isolated = copy(library)
+            isolated.directory = Path(temporary)
+            record = dict(id=digest(data), sha256=digest(data), name=meta.title + '.exp',
+                          titles=list(meta.titles), pack_id=meta.pack_id, episode_id=meta.episode_id)
+            yield EpisodeResources(isolated, record, archive)
+
+
+def play_preview(path, library_path, game):
+    from exp_runtime.desktop import play
+    with preview_resources(Path(path).read_bytes(), library_path, game) as resources:
+        play(resources)

exp_runtime/creator/schema.py

@@ -0,0 +1,102 @@
+"""Small, discoverable authoring contracts and authored examples."""
+from copy import deepcopy
+from dataclasses import asdict
+
+from .features import DEFAULTS, NAMES
+from .model import Node, ProjectError
+
+
+FIELDS = {
+    'dialogue': ('text', 'speaker', 'portrait', 'theme', 'character', 'expression', 'next'),
+    'choice': ('text', 'speaker', 'theme', 'character', 'options', 'timeout_ms', 'timeout_option'),
+    'background': ('asset', 'next'), 'set': ('variable', 'value', 'next'),
+    'branch': ('variable', 'operator', 'value', 'next', 'otherwise'),
+    'text_branch': ('next', 'otherwise'), 'relationship': ('character', 'next'),
+    'input': ('text', 'next'), 'title': ('text', 'next'), 'message': ('text', 'next'),
+    'notice': ('text', 'next'), 'scene_label': ('text', 'next'),
+    'word_game': ('text', 'character', 'next'), 'grid': ('next',), 'football': ('next',),
+    'end': (), 'native': (),
+}
+NOTES = {
+    'dialogue': 'Use character for a reusable speaker, or speaker/portrait for an inline speaker. Text must be nonempty.',
+    'choice': 'Provide 2–8 nonempty answers. Conditions enable answers; timeout_option is a zero-based visible row; native shuffling moves labels/return values, while enabled flags remain on rows.',
+    'background': 'asset must reference an imported image in this project.',
+    'set': 'variable is required; a nonempty params.expression overrides value.',
+    'branch': 'params.expression overrides variable/operator/value. Both destinations are required.',
+    'relationship': 'character is required. Changes the native relationship property, with the real emotion animation.',
+    'score': 'Choose the game/script property owner and key explicitly. There is no universal score property; owner -30000 is reserved.',
+    'input': 'Stores a text variable. Native input uses the selected game\'s character and width limits.',
+    'random': 'bound must be positive. Stores an actual native random draw in result.',
+    'music': 'Music IDs are 8201–8232 in SHS and 8201–8209 in CoD. Some SHS IDs select offsets in another audio asset.',
+    'word_game': 'good needs at least 2 words; bad at least 3. Duration 1–32767 ms. Words cannot contain pipes.',
+    'football': 'Six interleaved offense/defense tables, each 1–10 rows of [code, yards, variation, weight]. See defaults for a valid example.',
+    'grid': 'Problems define dimensions, targets and alphabet. Tutorials use a fixed board. Native limits and table checks apply.',
+    'end': 'Uses native episode-exit service 7. The player returns to its existing menu, where another installed episode can be selected.',
+    'native': 'Imported native projects only. Preserve script/PC, instruction counts and data-bank lengths; no high-level reconstruction is assumed.',
+}
+
+
+def value_schema(value):
+    if value is None: return {'type': ['integer', 'null'], 'minimum': 0, 'maximum': 32767}
+    kind = {str: 'string', int: 'integer', float: 'number', bool: 'boolean', dict: 'object', list: 'array'}[type(value)]
+    result = dict(type=kind, default=deepcopy(value))
+    if kind == 'integer': result.update(minimum=-32768, maximum=32767)
+    if kind == 'array' and value: result['items'] = value_schema(value[0])
+    return result
+
+
+def node_schema(kind=None):
+    if kind is None:
+        return dict(kinds=[dict(kind=k, title=v, games=['shs'] if k in ('football', 'grid') else ['shs', 'cod'])
+                           for k, v in NAMES.items()],
+                    languages=['en', 'fr', 'it', 'de', 'es'],
+                    expressions='Integers, variables, + - * // %, comparisons, and/or/not; signed 16-bit arithmetic, no calls.',
+                    workflow='project_get → graph_search_nodes/graph_get_subgraph → project_preview_edits → project_apply_edits → project_validate → playtest → project_export_exp',
+                    compatibility='Native KiWi/CSPUD export; full original-app playback remains unverified. Consult each kind for restrictions.',
+                    resources=['creator://schema/{kind}', 'creator://examples/branching'],
+                    limits=dict(nodes=20000, characters=199, options=8, batch_operations=200))
+    if kind not in NAMES: raise ProjectError('Unknown node kind')
+    defaults = asdict(Node('example', kind=kind))
+    names = ('id', 'kind', 'label', 'x', 'y', 'scene', *FIELDS.get(kind, ('next',)))
+    properties = {name: value_schema(defaults[name]) for name in names}
+    properties['id'].update(minLength=1, maxLength=200, description='Stable, unique node ID; use readable names such as school_arrival.')
+    properties['kind'] = {'const': kind}
+    properties['scene'].update(minimum=25001, maximum=25999)
+    properties['x'] = properties['y'] = dict(type='number', minimum=-100000, maximum=100000, default=0)
+    for name in ('theme', 'expression'):
+        if name in properties: properties[name].update(minimum=0, maximum=3 if name == 'theme' else 4)
+    if 'options' in properties:
+        properties['options'].update(minItems=2, maxItems=8, items=dict(type='object', additionalProperties=False,
+            properties=dict(text=dict(type='string', minLength=1), target=dict(type='string', minLength=1),
+                            condition=dict(type='string', default='')), required=['text', 'target']))
+        properties['timeout_ms'].update(minimum=0, description='0 disables the timer; otherwise milliseconds, maximum 32767.')
+        properties['timeout_option'].update(minimum=0, maximum=7)
+    properties['params'] = dict(type='object', additionalProperties=False,
+        properties={key: value_schema(value) for key, value in DEFAULTS[kind].items()}, default=deepcopy(DEFAULTS[kind]))
+    if kind == 'native':
+        properties['params'] = dict(type='object', description='Use native_get_data and graph_get_subgraph to inspect the imported block before editing.')
+    example = dict(id='example', kind=kind, params=deepcopy(DEFAULTS[kind]))
+    if 'next' in properties: example['next'] = 'end'
+    if 'otherwise' in properties: example['otherwise'] = 'alternate_end'
+    if 'text' in properties: example['text'] = 'An authored example.'
+    if kind in ('set', 'branch'): example['variable'] = 'points'
+    if kind == 'choice':
+        example['options'] = [dict(text='Help', target='help'), dict(text='Leave', target='end')]
+    if kind == 'relationship': example['character'] = 'friend'
+    if kind == 'background': example['asset'] = 26000
+    return dict(kind=kind, title=NAMES[kind], games=['shs'] if kind in ('football', 'grid') else ['shs', 'cod'],
+                schema=dict(type='object', properties=properties, required=['id', 'kind'], additionalProperties=False),
+                notes=NOTES.get(kind, 'Uses the shared native compiler and host-service contract.'), example=example,
+                compatibility='native_format',
+                original_app_playback='unverified')
+
+
+def branching_example():
+    return dict(description='Apply to a new default project; uses no imported game assets.', operations=[
+        dict(op='node', id='start', changes=dict(text='A friend needs help.', next='decision')),
+        dict(op='node', id='decision', changes=dict(kind='choice', text='What do you do?', options=[
+            dict(text='Help', target='reward'), dict(text='Leave', target='end')])),
+        dict(op='node', id='reward', changes=dict(kind='set', variable='points', value=1, next='end'))],
+        scenario=dict(seed=7, steps=[dict(action='run', until='choice'), dict(action='choose', option_id='decision:0'),
+                                     dict(action='run', until='end')],
+                      assertions=[dict(kind='variable', name='points', equals=1), dict(kind='ended')]))

exp_runtime/creator/sharing.py

@@ -0,0 +1,169 @@
+"""Local desktop discovery, bounded JSON transport and cooperative file locks.
+
+The desktop owns its live document. MCP clients read snapshots and submit a
+revision-checked replacement; an unavailable desktop never falls back to disk.
+This module has no Qt or MCP dependency.
+"""
+from dataclasses import dataclass
+import hashlib
+import json
+import os
+from pathlib import Path
+import secrets
+import socket
+import struct
+
+from .model import (MAX_PROJECT_BYTES, Project, ProjectError, atomic_write, project_bytes,
+                    project_from_bytes, project_from_record)
+
+MAX_MESSAGE = MAX_PROJECT_BYTES * 2
+TIMEOUT = 15
+
+
+class SharingError(ProjectError):
+    code = 'desktop_unavailable'
+
+
+class ProjectBusy(SharingError):
+    code = 'project_busy'
+
+
+def digest(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def state_path(path, suffix):
+    path = Path(path).resolve()
+    folder = path.parent / '.creator-session'
+    if folder.is_symlink(): raise SharingError('The creator session directory must not be a symlink')
+    return folder / (digest(path.name.encode()) + suffix)
+
+
+class FileLock:
+    """Nonblocking process lock; the OS releases it if the owner crashes."""
+    def __init__(self, path):
+        self.path, self.stream = Path(path), None
+
+    def __enter__(self):
+        self.path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if self.path.is_symlink(): raise SharingError('Creator lock files must not be symlinks')
+        self.stream = open(self.path, 'a+b')
+        if not self.stream.seek(0, 2):
+            self.stream.write(b'\0'); self.stream.flush()
+        self.stream.seek(0)
+        try:
+            if os.name == 'nt':
+                import msvcrt
+                msvcrt.locking(self.stream.fileno(), msvcrt.LK_NBLCK, 1)
+            else:
+                import fcntl
+                fcntl.flock(self.stream.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError as error:
+            self.stream.close(); self.stream = None
+            raise ProjectBusy('Project is busy in another operation or desktop window; retry after it finishes.') from error
+        return self
+
+    def __exit__(self, *args):
+        if self.stream is not None:
+            self.stream.close()
+            self.stream = None
+
+
+def guard(path):
+    if not Path(path).resolve().parent.is_dir(): raise ProjectError('Project directory must already exist')
+    return FileLock(state_path(path, '.lock'))
+
+
+def session_info(path):
+    marker = state_path(path, '.json')
+    try:
+        if marker.is_symlink() or marker.stat().st_size > 4096:
+            raise ValueError('Invalid desktop session file')
+        record = json.loads(marker.read_bytes())
+        if (not isinstance(record, dict) or record.get('version') != 1
+                or record.get('path') != str(Path(path).resolve())
+                or type(record.get('port')) is not int or not 1 <= record['port'] <= 65535
+                or not isinstance(record.get('token'), str) or len(record['token']) != 64):
+            raise ValueError('Invalid desktop session record')
+        return record
+    except FileNotFoundError:
+        return None
+    except (OSError, ValueError) as error:
+        raise SharingError('Cannot read the desktop session. Reopen the project in the creator.') from error
+
+
+class Lease:
+    """One desktop window may own a saved project at a time."""
+    def __init__(self, path, port):
+        self.path = Path(path).resolve()
+        self.owner = FileLock(state_path(self.path, '.owner'))
+        self.record = dict(version=1, path=str(self.path), port=port, token=secrets.token_hex(32))
+        with guard(self.path):
+            self.owner.__enter__()
+            try:
+                atomic_write(state_path(self.path, '.json'), json.dumps(self.record).encode())
+            except BaseException:
+                self.owner.__exit__()
+                raise
+
+    def close(self):
+        if self.owner.stream is not None:
+            # The owner lock prevents another window replacing this record.
+            try: state_path(self.path, '.json').unlink(missing_ok=True)
+            finally: self.owner.__exit__()
+
+
+def encode_message(record):
+    data = json.dumps(record, ensure_ascii=False, allow_nan=False).encode()
+    if len(data) > MAX_MESSAGE: raise ProjectError('Desktop request exceeds the project size limit')
+    return struct.pack('>I', len(data)) + data
+
+
+def _receive(stream, size):
+    data = bytearray()
+    while len(data) < size:
+        part = stream.recv(min(size - len(data), 1024 * 1024))
+        if not part: raise OSError('Desktop connection closed')
+        data.extend(part)
+    return bytes(data)
+
+
+def request(info, action, **values):
+    try:
+        with socket.create_connection(('127.0.0.1', info['port']), timeout=TIMEOUT) as stream:
+            stream.sendall(encode_message(dict(token=info['token'], path=info['path'], action=action, **values)))
+            size, = struct.unpack('>I', _receive(stream, 4))
+            if not 0 < size <= MAX_MESSAGE: raise ValueError('Invalid desktop response size')
+            response = json.loads(_receive(stream, size))
+            if not isinstance(response, dict): raise ValueError('Invalid desktop response')
+    except (OSError, ValueError) as error:
+        raise SharingError('Desktop session is unavailable; reopen the project in the creator, then reread it '
+                           'before retrying. No fallback file write was attempted.') from error
+    if 'error' in response:
+        kind = ProjectBusy if response.get('code') == 'project_busy' else ProjectError
+        raise kind(response['error'])
+    return response
+
+
+@dataclass
+class Snapshot:
+    project: Project
+    revision: str
+    data: bytes
+    live: bool = False
+    unsaved: bool = False
+
+
+def snapshot(path):
+    path = Path(path).resolve()
+    with guard(path):
+        info = session_info(path)
+        if info is None:
+            if path.stat().st_size > MAX_PROJECT_BYTES: raise ProjectError('Project file exceeds 96 MiB')
+            data = path.read_bytes()
+            return Snapshot(project_from_bytes(data, path), digest(data), data)
+    response = request(info, 'read')
+    project = project_from_record(response['project'])
+    data = project_bytes(project, path)
+    if digest(data) != response['revision']: raise SharingError('Desktop snapshot checksum does not match')
+    return Snapshot(project, response['revision'], data, True, response['unsaved'])