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

exp_runtime/creator/native.py

@@ -0,0 +1,174 @@
+"""Round-trip authored graphs or edit lossless native basic blocks.
+
+Original bytecode is never guessed into dialogue or flattened past unknown
+services. Fixed instruction counts preserve every native PC and callback.
+"""
+import base64
+from dataclasses import replace
+
+from exp_runtime.authored import authoring_record
+from exp_runtime.exp import ExpArchive, Metadata, encode_exp
+from exp_runtime.decode.bytecode import OPERAND_OPCODES, decode_program
+from .model import Asset, Node, Project, ProjectError, project_from_record, validate_structure
+
+
+def _resources(project):
+    try:
+        return {int(key): base64.b64decode(value, validate=True)
+                for key, value in project.native['resources'].items()}
+    except (KeyError, TypeError, ValueError) as error:
+        raise ProjectError('Invalid native resource bank') from error
+
+
+def import_exp(data, *, game='shs'):
+    archive = ExpArchive(data)
+    record = authoring_record(archive)
+    if record and record.get('project'):
+        document = record['project']
+        for asset in document.get('assets', []):
+            if asset.get('data') == '@resource':
+                asset['data'] = base64.b64encode(archive.read(asset['id'])).decode('ascii')
+        project = project_from_record(document)
+        project.library = ''
+        return project
+    meta = archive.metadata()
+    resources = {key: archive.read(key) for key in archive.entries}
+    project = Project(title=meta.title, game=game, pack_id=meta.pack_id, episode_id=meta.episode_id,
+                      nodes=[], native={'resources': {str(key): base64.b64encode(value).decode('ascii')
+                                                     for key, value in resources.items()}})
+    project.locales = {language: {'title': title} for language, title in
+                      zip(('en', 'fr', 'it', 'de', 'es'), meta.titles)}
+    for script, program in sorted(archive.programs().items()):
+        instructions = program.instructions
+        if not instructions:
+            continue
+        boundaries = {instructions[0].pc}
+        pcs = {ins.pc for ins in instructions}
+        for ins in instructions:
+            target = ins.branch_target()
+            if target in pcs:
+                boundaries.add(target)
+            if target is not None or ins.opcode in (0x1e, 0x1f, 0x33, 0x43):
+                if ins.pc + 1 in pcs:
+                    boundaries.add(ins.pc + 1)
+        starts = sorted(boundaries)
+        for index, start in enumerate(starts):
+            end = starts[index + 1] if index + 1 < len(starts) else instructions[-1].pc + 1
+            base = instructions[0].pc
+            block = instructions[start - base:end - base]
+            last = block[-1]
+            targets = []
+            if last.branch_target() in pcs:
+                targets.append(last.branch_target())
+            if last.opcode not in (0x29, 0x33, 0x43) and end in pcs:
+                targets.append(end)
+            node = Node(f'{script}:{start}', 'native', f'Script {script} · PC {start}',
+                        x=index % 6 * 290, y=(index // 6 + len(project.nodes) // 6) * 160,
+                        scene=script, params={'script': script, 'pc': start,
+                        'instructions': [[ins.opcode, ins.operand] for ins in block],
+                        'edges': [f'{script}:{pc}' for pc in dict.fromkeys(targets)]})
+            project.nodes.append(node)
+    if not project.nodes:
+        raise ProjectError('EXP has no editable KiWi programs')
+    project.start = next((n.id for n in project.nodes if n.scene == 25001), project.nodes[0].id)
+    project.assets = [Asset(key, f'Resource {key}', value) for key, value in resources.items()
+                      if value.startswith((b'\x89PNG\r\n\x1a\n', b'\xff\xd8'))]
+    from .editing import auto_layout
+    auto_layout(project)
+    validate_structure(project)
+    return project
+
+
+def compile_native(project):
+    resources = _resources(project)
+    programs = {key: decode_program(value) for key, value in resources.items() if value.startswith(b'kiwi')}
+    originals = {key: {ins.pc: ins for ins in program.instructions} for key, program in programs.items()}
+    edits = {key: {} for key in programs}
+    for node in project.nodes:
+        if node.kind != 'native':
+            raise ProjectError('Native projects require native blocks; create a new project for high-level nodes')
+        p = node.params
+        try:
+            script, start, rows = p['script'], p['pc'], p['instructions']
+            if type(start) is not int or type(script) is not int or not isinstance(rows, list) or not rows:
+                raise ValueError('invalid block')
+            original = originals[script]
+            for index, row in enumerate(rows):
+                pc = start + index
+                op, arg = row
+                if pc not in original or pc in edits[script] or type(op) is not int or not 0 <= op <= 255:
+                    raise ValueError('overlapping block or invalid PC/opcode')
+                if (op in OPERAND_OPCODES and (type(arg) is not int or not 0 <= arg <= 65535)
+                        or op not in OPERAND_OPCODES and arg is not None):
+                    raise ValueError('operand does not match opcode width')
+                edits[script][pc] = replace(original[pc], opcode=op, operand=arg)
+        except (KeyError, TypeError, ValueError) as error:
+            raise ProjectError(f'{node.label}: invalid native block: {error}') from error
+    for script, program in programs.items():
+        if set(edits[script]) != {ins.pc for ins in program.instructions}:
+            raise ProjectError('Preserve every instruction in an imported native project')
+        resources[script] = replace(program, instructions=tuple(edits[script][ins.pc] for ins in program.instructions)).to_bytes()
+    for asset in project.assets:
+        if asset.data is not None:
+            resources[asset.id] = asset.data
+    old = ExpArchive(encode_exp(resources)).metadata()
+    titles = tuple(project.title if lang == 'en' and project.title != old.title else
+                   project.locales.get(lang, {}).get('title', project.title)
+                   for lang in ('en', 'fr', 'it', 'de', 'es'))
+    if (old.pack_id, old.episode_id, old.titles) != (project.pack_id, project.episode_id, titles):
+        resources[1] = Metadata(project.pack_id, project.episode_id, titles).to_bytes()
+    return encode_exp(resources)
+
+
+def validate_native(project):
+    compile_native(project)
+
+
+def set_data_words(project, script, words, *, extra=False):
+    """Explicit data-bank editing; addresses and bank lengths remain stable."""
+    resources = _resources(project)
+    program = decode_program(resources[script])
+    key = 'extra_words' if extra else 'main_words'
+    if (len(words) != len(getattr(program, key))
+            or any(type(word) is not int or not 0 <= word <= 65535 for word in words)):
+        raise ProjectError('Keep the original data-bank length and use unsigned 16-bit words')
+    resources[script] = replace(program, **{key: tuple(words)}).to_bytes()
+    project.native['resources'][str(script)] = base64.b64encode(resources[script]).decode('ascii')
+
+
+def packed_strings(project, script):
+    """Offer printable packed-text candidates with exact main-bank addresses.
+
+    Data words are untyped; this list is a viewing aid, never decompilation.
+    """
+    import struct
+    program = decode_program(_resources(project)[script])
+    data = struct.pack(f'>{len(program.main_words)}H', *program.main_words)
+    result, position = [], 0
+    while position < len(data):
+        end = data.find(b'\0', position)
+        if end < 0: break
+        text = data[position:end].decode('latin-1')
+        if len(text) >= 2 and all(c.isprintable() or c in '\n\r\t' for c in text):
+            result.append({'address': position // 2, 'text': text})
+        position = (end + 2) // 2 * 2
+    return result
+
+
+def edit_packed_text(project, script, address, text):
+    """Replace a confirmed main-bank string without relocating other addresses."""
+    import struct
+    resources = _resources(project)
+    program = decode_program(resources[script])
+    data = bytearray(struct.pack(f'>{len(program.main_words)}H', *program.main_words))
+    if type(address) is not int or not 0 <= address < len(program.main_words):
+        raise ProjectError('Text address must identify a main-bank word')
+    start = address * 2
+    end = data.find(b'\0', start)
+    if end < 0: raise ProjectError('Text must have an existing NUL terminator')
+    try: encoded = text.encode('latin-1')
+    except UnicodeError as error: raise ProjectError('Native text uses Latin-1') from error
+    if b'\0' in encoded or len(encoded) > end - start:
+        raise ProjectError('Replacement must fit the original string allocation without NULs')
+    data[start:end] = encoded + b'\0' * (end - start - len(encoded))
+    set_data_words(project, script, list(struct.unpack(f'>{len(program.main_words)}H', data)))

exp_runtime/creator/operations.py

@@ -0,0 +1,83 @@
+"""One transaction vocabulary shared by workspace edits and MCP schemas."""
+from dataclasses import fields
+
+from .model import Character, Choice, Node, ProjectError
+from . import graph
+
+
+def patch_record(record, changes, allowed):
+    if not isinstance(changes, dict) or set(changes) - set(allowed):
+        raise ProjectError('Unsupported fields: ' + ', '.join(sorted(set(changes) - set(allowed)))
+                           if isinstance(changes, dict) else 'Changes must be an object')
+    for key, value in changes.items():
+        if key == 'options':
+            if not isinstance(value, list): raise ProjectError('Options must be a list')
+            try: value = [Choice(**option) for option in value]
+            except TypeError as error: raise ProjectError(f'Invalid choice: {error}') from error
+        setattr(record, key, value)
+
+
+def apply(workspace, project, operation):
+    """Apply to a disposable candidate. The workspace validates and commits once."""
+    if not isinstance(operation, dict): raise ProjectError('An edit operation must be an object')
+    op = operation.get('op')
+    allowed = {
+        'project': {'changes'}, 'node': {'id', 'changes', 'remove'},
+        'character': {'id', 'changes', 'remove'}, 'rename_node': {'id', 'new_id'},
+        'connect': {'source', 'target', 'field'}, 'image': {'source'},
+        'library_image': {'library', 'resource', 'episode'}, 'asset_label': {'id', 'label'}, 'layout': set(),
+    }
+    if op not in allowed or set(operation) - {'op'} - allowed[op]:
+        raise ProjectError('Unknown edit operation or operation fields')
+    if op == 'project':
+        changes = dict(operation['changes'])
+        if 'game' in changes and changes['game'] != project.game and (project.assets or project.native or project.library):
+            raise ProjectError('Create a new project to change the game after importing resources')
+        if changes.get('library'): changes['library'] = str(workspace.path(changes['library']))
+        patch_record(project, changes, {'title', 'game', 'pack_id', 'episode_id', 'start', 'language', 'locales', 'library'})
+    elif op in ('node', 'character'):
+        key = operation['id']
+        if not isinstance(key, str) or not key: raise ProjectError('An edit needs a nonempty ID')
+        collection = project.nodes if op == 'node' else project.characters
+        record = next((r for r in collection if r.id == key), None)
+        if project.native and (op == 'character' or record is None or operation.get('remove')):
+            raise ProjectError('Native projects retain their original blocks and character definitions')
+        if operation.get('remove'):
+            if record is None: raise ProjectError(f'Unknown {op}: {key}')
+            collection.remove(record)
+        else:
+            if record is None:
+                record = Node(key) if op == 'node' else Character(key)
+                collection.append(record)
+            patch_record(record, operation.get('changes', {}), {f.name for f in fields(record)} - {'id'})
+    elif op == 'rename_node': graph.rename_node(project, operation['id'], operation['new_id'])
+    elif op == 'connect': graph.connect(project, operation['source'], operation['target'], operation.get('field', 'next'))
+    elif op == 'image':
+        from .model import MAX_ASSET_BYTES
+        path = workspace.path(operation['source'])
+        if path.stat().st_size > MAX_ASSET_BYTES: raise ProjectError('Image is too large')
+        project.add_image(path.name, path.read_bytes())
+    elif op == 'library_image':
+        from exp_runtime.content import ContentLibrary
+        from .assets import import_library_image
+        with ContentLibrary(workspace.path(operation['library'])) as content:
+            episode = operation.get('episode')
+            import_library_image(project, content, operation['resource'], content.open_episode(episode) if episode else None)
+    elif op == 'asset_label':
+        asset = next((a for a in project.assets if a.id == operation['id']), None)
+        if asset is None: raise ProjectError('Import the asset into the project before labeling it')
+        asset.name = operation['label']
+    elif op == 'layout':
+        from .editing import auto_layout
+        auto_layout(project)
+
+
+def check_removals(before, after):
+    removed = {n.id for n in before.nodes} - {n.id for n in after.nodes}
+    references = [e for e in graph.edges(after) if e['target'] in removed]
+    if after.start in removed or references:
+        raise ProjectError('Removed node is still referenced; reconnect its incoming edges and project start in the same batch')
+    removed_characters = {c.id for c in before.characters} - {c.id for c in after.characters}
+    if any(n.character in removed_characters or n.params.get('left_character') in removed_characters or
+           n.params.get('right_character') in removed_characters for n in after.nodes):
+        raise ProjectError('Removed character is still referenced by a node')

exp_runtime/creator/panels.py

@@ -0,0 +1,221 @@
+"""Structured authoring dialogs shared by character and minigame inspectors."""
+from copy import deepcopy
+import json
+
+from PySide6.QtWidgets import (QCheckBox, QComboBox, QDialog, QDialogButtonBox, QFormLayout,
+    QHBoxLayout, QLabel, QLineEdit, QListWidget, QMessageBox, QPushButton, QScrollArea,
+    QSpinBox, QTableWidget, QTableWidgetItem, QTextEdit, QVBoxLayout, QWidget)
+
+from .model import ProjectError
+
+
+LIST_TEMPLATES = {
+    'symbols': ['A', 26000],
+    'expressions': None,
+    'tutorials': dict(title='Practice', body='Connect the word.', position=0, tap_to_advance=False,
+                      hide_board=False, width=3, height=3, heading='Practice', prompt='Find CAT',
+                      words=['CAT'], highlight=True, fixed_board='CAT\nAAA\nAAA', show_hints=True,
+                      animate=True, timed=False, failure_next=-1, success_next=-2),
+}
+
+def value_field(value, parent=None, key=None):
+    """Return a widget and a typed getter; containers have their own row editor."""
+    if isinstance(value, (dict, list)):
+        current = deepcopy(value)
+        button = QPushButton(f'Edit {len(value)} ' + ('fields…' if isinstance(value, dict) else 'items…'), parent)
+        def edit():
+            dialog = (RecordDialog(current, parent) if isinstance(current, dict) else
+                      ListDialog([None] * 5 if key == 'expressions' and not current else current,
+                                 parent, template=LIST_TEMPLATES.get(key)))
+            if dialog.exec() == QDialog.DialogCode.Accepted:
+                current.clear(); current.update(dialog.value) if isinstance(current, dict) else current.extend(dialog.value)
+                button.setText(f'Edit {len(current)} items…')
+        button.clicked.connect(edit)
+        return button, lambda: deepcopy(current)
+    if type(value) is bool:
+        widget = QCheckBox(parent); widget.setChecked(value)
+        return widget, widget.isChecked
+    if type(value) is int:
+        widget = QSpinBox(parent); widget.setRange(-32768, 65535); widget.setValue(value)
+        return widget, widget.value
+    widget = QLineEdit('null' if value is None else str(value), parent)
+    return widget, (lambda: json.loads(widget.text())) if value is None else widget.text
+
+
+class RecordDialog(QDialog):
+    def __init__(self, record, parent=None, title='Edit fields'):
+        super().__init__(parent)
+        self.setWindowTitle(title); self.resize(560, 650)
+        layout = QVBoxLayout(self)
+        scroll = QScrollArea(); scroll.setWidgetResizable(True)
+        panel = QWidget(); form = QFormLayout(panel); self.getters = {}
+        for key, value in record.items():
+            field, getter = value_field(value, self, key)
+            field.setObjectName(key); self.getters[key] = getter
+            form.addRow(key.replace('_', ' ').capitalize(), field)
+        scroll.setWidget(panel); layout.addWidget(scroll)
+        buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel)
+        buttons.accepted.connect(self.accept); buttons.rejected.connect(self.reject); layout.addWidget(buttons)
+
+    def accept(self):
+        try:
+            self.value = {key: getter() for key, getter in self.getters.items()}
+        except (ValueError, TypeError) as error:
+            QMessageBox.warning(self, 'Invalid value', str(error)); return
+        super().accept()
+
+
+class ListDialog(QDialog):
+    def __init__(self, values, parent=None, title='Edit items', template=None):
+        super().__init__(parent)
+        self.value = deepcopy(values); self.template = template
+        self.setWindowTitle(title); self.resize(650, 480)
+        layout = QVBoxLayout(self); self.items = QListWidget(); layout.addWidget(self.items)
+        buttons = QHBoxLayout()
+        for label, callback in (('Edit', self.edit), ('Add', self.add), ('Duplicate', self.duplicate),
+                                ('Remove', self.remove), ('Move up', lambda: self.move(-1)),
+                                ('Move down', lambda: self.move(1))):
+            button = QPushButton(label); button.clicked.connect(callback); buttons.addWidget(button)
+        layout.addLayout(buttons)
+        self.items.itemDoubleClicked.connect(self.edit)
+        done = QDialogButtonBox(QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel)
+        done.accepted.connect(self.accept); done.rejected.connect(self.reject); layout.addWidget(done)
+        self.refresh()
+
+    def refresh(self, row=0):
+        self.items.clear()
+        for index, value in enumerate(self.value):
+            self.items.addItem(f'{index + 1}. ' + (value.get('name', value.get('heading', str(value)))
+                                               if isinstance(value, dict) else str(value)))
+        self.items.setCurrentRow(row)
+
+    def edit(self, *unused):
+        row = self.items.currentRow()
+        if row < 0: return
+        value = self.value[row]
+        if isinstance(value, list):
+            dialog = ListDialog(value, self)
+        else:
+            dialog = RecordDialog(value if isinstance(value, dict) else {'value': value}, self)
+        if dialog.exec() == QDialog.DialogCode.Accepted:
+            self.value[row] = dialog.value if isinstance(value, (list, dict)) else dialog.value['value']
+            self.refresh(row)
+
+    def add(self):
+        self.value.append(deepcopy(self.template if self.template is not None else self.value[-1] if self.value else ''))
+        if isinstance(self.value[-1], dict) and 'id' in self.value[-1] and isinstance(self.value[-1]['id'], str):
+            import uuid
+            self.value[-1]['id'] = uuid.uuid4().hex[:10]
+        self.refresh(len(self.value) - 1); self.edit()
+
+    def duplicate(self):
+        row = self.items.currentRow()
+        if row >= 0:
+            self.value.insert(row + 1, deepcopy(self.value[row]))
+            if isinstance(self.value[row + 1], dict) and isinstance(self.value[row + 1].get('id'), str):
+                import uuid
+                self.value[row + 1]['id'] = uuid.uuid4().hex[:10]
+            self.refresh(row + 1)
+
+    def remove(self):
+        row = self.items.currentRow()
+        if row >= 0:
+            self.value.pop(row); self.refresh(max(0, row - 1))
+
+    def move(self, delta):
+        row = self.items.currentRow(); other = row + delta
+        if 0 <= row < len(self.value) and 0 <= other < len(self.value):
+            self.value[row], self.value[other] = self.value[other], self.value[row]; self.refresh(other)
+
+
+class TranslationsDialog(QDialog):
+    def __init__(self, project, parent=None):
+        from .features import text_fields
+        super().__init__(parent)
+        self.setWindowTitle('Translations'); self.resize(1000, 600)
+        self.locales = deepcopy(project.locales); self.fields = text_fields(project)
+        layout = QVBoxLayout(self); self.language = QComboBox()
+        for name, code in (('English', 'en'), ('French', 'fr'), ('Italian', 'it'), ('German', 'de'), ('Spanish', 'es')):
+            self.language.addItem(name, code)
+        self.language.setCurrentIndex(self.language.findData(project.language))
+        layout.addWidget(self.language)
+        layout.addWidget(QLabel('Empty translations use the original text. Story text uses native Latin-1 encoding.'))
+        self.table = QTableWidget(0, 3); self.table.setHorizontalHeaderLabels(['Field', 'Original', 'Translation'])
+        layout.addWidget(self.table); self.current = self.language.currentData(); self.populate()
+        self.language.currentIndexChanged.connect(self.change)
+        buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel)
+        buttons.accepted.connect(self.accept); buttons.rejected.connect(self.reject); layout.addWidget(buttons)
+
+    def populate(self):
+        from PySide6.QtCore import Qt
+        self.table.setRowCount(len(self.fields))
+        for row, (key, value) in enumerate(self.fields.items()):
+            for column, text in enumerate((key, value, self.locales.get(self.current, {}).get(key, ''))):
+                item = QTableWidgetItem(text)
+                if column < 2: item.setFlags(item.flags() & ~Qt.ItemFlag.ItemIsEditable)
+                self.table.setItem(row, column, item)
+        self.table.resizeColumnsToContents()
+
+    def store(self):
+        self.locales[self.current] = {key: self.table.item(row, 2).text() for row, key in enumerate(self.fields)
+                                     if self.table.item(row, 2).text()}
+
+    def change(self):
+        self.store(); self.current = self.language.currentData(); self.populate()
+
+    def accept(self):
+        self.store(); super().accept()
+
+
+class DebugDialog(QDialog):
+    def __init__(self, project, parent=None, select=None, start=None):
+        from .debugger import DebugSession
+        super().__init__(parent)
+        self.debug = DebugSession(project, start=start); self.select = select
+        self.setWindowTitle('Story debugger'); self.resize(800, 650)
+        layout = QVBoxLayout(self); row = QHBoxLayout()
+        for label, callback in (('Step node', lambda: self.execute(step=True)), ('Run', self.execute)):
+            button = QPushButton(label); button.clicked.connect(callback); row.addWidget(button)
+        layout.addLayout(row)
+        self.breakpoints = QLineEdit(); self.breakpoints.setPlaceholderText('Breakpoint node IDs, separated by commas')
+        self.breakpoints.editingFinished.connect(lambda: setattr(self.debug, 'breakpoints',
+            set(value.strip() for value in self.breakpoints.text().split(',') if value.strip())))
+        layout.addWidget(self.breakpoints)
+        self.output = QTextEdit(); self.output.setReadOnly(True); layout.addWidget(self.output)
+        row = QHBoxLayout(); self.answer = QLineEdit(); self.answer.setPlaceholderText('Text, or zero-based choice/word/play index')
+        row.addWidget(self.answer)
+        button = QPushButton('Submit / continue'); button.clicked.connect(self.submit); row.addWidget(button)
+        button = QPushButton('Advance clock 1s'); button.clicked.connect(lambda: self.execute(milliseconds=1000)); row.addWidget(button)
+        layout.addLayout(row)
+        row = QHBoxLayout(); self.variable = QLineEdit(); self.variable.setPlaceholderText('Numeric variable name')
+        self.value = QSpinBox(); self.value.setRange(-32768, 32767)
+        row.addWidget(self.variable); row.addWidget(self.value)
+        button = QPushButton('Set value'); button.clicked.connect(self.set_variable); row.addWidget(button)
+        layout.addLayout(row); self.refresh()
+
+    def refresh(self):
+        state = self.debug.state()
+        self.output.setPlainText(json.dumps(state, indent=2, ensure_ascii=False))
+        if self.select and state['node']: self.select(state['node'])
+
+    def execute(self, checked=False, **kwargs):
+        try:
+            self.debug.resume(**kwargs); self.refresh()
+        except ValueError as error:
+            QMessageBox.warning(self, 'Execution stopped', str(error)); self.refresh()
+
+    def submit(self):
+        action = self.debug.state()['action']
+        value = self.answer.text()
+        if action in ('choice', 'word_game', 'football'):
+            try: value = int(value)
+            except ValueError:
+                QMessageBox.warning(self, 'Choose an answer', 'Enter a zero-based answer index.'); return
+        elif action != 'text_input': value = None
+        self.execute(answer=value, provide_answer=True)
+
+    def set_variable(self):
+        try:
+            self.debug.set_variable(self.variable.text(), self.value.value()); self.refresh()
+        except ProjectError as error:
+            QMessageBox.warning(self, 'Variable', str(error))