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

exp_runtime/creator/workspace.py

@@ -0,0 +1,271 @@
+"""Shared desktop/file authoring operations restricted to one workspace."""
+from copy import deepcopy
+from dataclasses import asdict, fields, is_dataclass
+import hashlib
+import json
+import re
+from pathlib import Path
+import threading
+import uuid
+
+from .compiler import compile_details
+from .model import (Project, ProjectError, atomic_write, project_from_record,
+                    project_bytes, project_from_bytes, project_record, save_project, validate_structure)
+from .sharing import guard, session_info, snapshot, request, digest
+
+
+class Workspace:
+    def __init__(self, root):
+        self.root = Path(root).resolve(strict=True)
+        if not self.root.is_dir(): raise ProjectError('Workspace must be an existing directory')
+        self.lock = threading.RLock()
+        self.debuggers = {}
+        self.playtests = {}
+        self.responses = {}
+
+    def path(self, name, suffix=None):
+        path = (self.root / name).resolve()
+        if not path.is_relative_to(self.root) or path == self.root:
+            raise ProjectError('Paths must remain inside the configured workspace')
+        if suffix and path.suffix.lower() != suffix:
+            raise ProjectError(f'Expected a {suffix} file')
+        return path
+
+    def revision(self, path):
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+
+    def read(self, name):
+        state = self.snapshot(name)
+        return state.project, state.revision
+
+    def snapshot(self, name):
+        return snapshot(self.path(name, '.expproj'))
+
+    def describe(self, name, offset=0, limit=100):
+        if type(offset) is not int or offset < 0 or type(limit) is not int or not 1 <= limit <= 200:
+            raise ProjectError('Use a nonnegative offset and limit from 1 to 200')
+        state = self.snapshot(name)
+        project = state.project
+        return {'revision': state.revision, 'live': state.live, 'unsaved': state.unsaved,
+                'title': project.title, 'game': project.game,
+                'pack_id': project.pack_id, 'episode_id': project.episode_id, 'start': project.start,
+                'language': project.language, 'locales': project.locales, 'library': project.library,
+                'native': bool(project.native), 'node_count': len(project.nodes),
+                'nodes': [asdict(n) for n in project.nodes[offset:offset + limit]],
+                'characters': [asdict(c) for c in project.characters],
+                'assets': [{'id': a.id, 'name': a.name, 'embedded': a.data is not None,
+                            'bytes': len(a.data) if a.data else 0} for a in project.assets]}
+
+    def create(self, name, title='Untitled episode', game='shs', pack_id=30000, episode_id=1):
+        with self.lock:
+            path = self.path(name, '.expproj')
+            with guard(path):
+                if path.exists() or session_info(path): raise ProjectError('Project already exists')
+                project = Project(title=title, game=game, pack_id=pack_id, episode_id=episode_id)
+                save_project(project, path)
+            return self.describe(name)
+
+    def edit(self, name, revision, operation):
+        with self.lock:
+            project, actual = self.read(name)
+            if not revision or revision != actual:
+                raise ProjectError('Project changed; read its current revision before editing')
+            before = deepcopy(project)
+            operation(project)
+            validate_structure(project)
+            from .operations import check_removals
+            check_removals(before, project)
+            result = self.commit(name, revision, project_bytes(project, self.path(name)))
+            return dict(**result, changed=self.changes(before, project), library=project.library)
+
+    def commit(self, name, revision, data):
+        path = self.path(name, '.expproj')
+        project = project_from_bytes(data, path)
+        with guard(path):
+            info = session_info(path)
+            if info is None:
+                previous = path.read_bytes()
+                if digest(previous) != revision:
+                    raise ProjectError('Project changed; read its current revision before editing')
+                checkpoint = self._checkpoint(name, previous, 'Before edit')
+                atomic_write(path, data)
+                return dict(revision=digest(data), undo_checkpoint=checkpoint['checkpoint'], live=False, unsaved=False)
+        # Do not hold a filesystem lock while the GUI processes a request. The
+        # GUI checks the revision again, including edits made after this read.
+        checkpoint = self.checkpoint(name, revision, 'Before edit')
+        result = request(info, 'commit', revision=revision, project=project_record(project))
+        return dict(**result, undo_checkpoint=checkpoint['checkpoint'])
+
+    @staticmethod
+    def changes(before, after):
+        def brief(value):
+            if is_dataclass(value): return brief(asdict(value))
+            if isinstance(value, bytes): return dict(bytes=len(value), sha256=hashlib.sha256(value).hexdigest())
+            if isinstance(value, str) and len(value) > 1000:
+                return dict(preview=value[:1000], characters=len(value), truncated=True)
+            if isinstance(value, list): return [brief(v) for v in value[:20]] + ([dict(truncated=True, total=len(value))] if len(value) > 20 else [])
+            if isinstance(value, dict):
+                keys = list(value)[:20]
+                result = {k: brief(value[k]) for k in keys}
+                if len(keys) < len(value): result['_truncated'] = dict(total=len(value))
+                return result
+            return value
+        result = {}
+        for field in fields(Project):
+            a, b = getattr(before, field.name), getattr(after, field.name)
+            if a == b: continue
+            if field.name in ('nodes', 'characters', 'assets'):
+                old, new = {r.id: r for r in a}, {r.id: r for r in b}
+                updated = sorted(key for key in new.keys() & old.keys() if new[key] != old[key])
+                result[field.name] = dict(added=sorted(new.keys() - old.keys()), removed=sorted(old.keys() - new.keys()),
+                    updated=updated, details={key: {f.name: dict(before=brief(getattr(old[key], f.name)),
+                        after=brief(getattr(new[key], f.name))) for f in fields(new[key])
+                        if getattr(old[key], f.name) != getattr(new[key], f.name)} for key in updated[:20]})
+                if len(updated) > 20: result[field.name]['details_truncated'] = True
+            else:
+                result[field.name] = dict(before=brief(a), after=brief(b))
+        return result
+
+    def batch(self, name, revision, operations, *, preview=False):
+        from .operations import apply, check_removals
+        if not isinstance(operations, list) or not 1 <= len(operations) <= 200:
+            raise ProjectError('A transaction needs 1–200 operations')
+        def run(project):
+            for index, operation in enumerate(operations):
+                try: apply(self, project, operation)
+                except (KeyError, TypeError, ValueError) as error:
+                    raise ProjectError(f'Operation {index}: {error}') from error
+        if not preview: return self.edit(name, revision, run)
+        with self.lock:
+            before, actual = self.read(name)
+            if revision != actual: raise ProjectError('Project changed; read its current revision before editing')
+            candidate = deepcopy(before); run(candidate)
+            validate_structure(candidate); check_removals(before, candidate)
+            from .diagnostics import diagnose
+            return dict(revision=actual, changed=self.changes(before, candidate), validation=diagnose(candidate), applied=False)
+
+    def _history(self, name):
+        identity = str(self.path(name, '.expproj').relative_to(self.root))
+        return self.path('.creator-history/' + hashlib.sha256(identity.encode()).hexdigest() + '/index.json')
+
+    def checkpoints(self, name):
+        with guard(self.path(name, '.expproj')):
+            return self._checkpoints(name)
+
+    def _checkpoints(self, name):
+        index = self._history(name)
+        if not index.exists(): return []
+        records = json.loads(index.read_text(encoding='utf-8'))
+        if (not isinstance(records, list) or len(records) > 40 or any(
+                not isinstance(r, dict) or set(r) != {'checkpoint', 'revision', 'label'} or
+                not isinstance(r['checkpoint'], str) or not re.fullmatch('[0-9a-f]{32}', r['checkpoint']) or
+                not isinstance(r['revision'], str) or not re.fullmatch('[0-9a-f]{64}', r['revision']) or
+                not isinstance(r['label'], str) for r in records)):
+            raise ProjectError('Invalid checkpoint index')
+        return records
+
+    def checkpoint(self, name, revision, label='Checkpoint'):
+        with self.lock:
+            state = self.snapshot(name)
+            if revision != state.revision: raise ProjectError('Project changed; reread before checkpointing')
+            with guard(self.path(name, '.expproj')):
+                return self._checkpoint(name, state.data, label)
+
+    def _checkpoint(self, name, data, label):
+        if not isinstance(label, str) or len(label) > 200: raise ProjectError('Checkpoint label must fit 200 characters')
+        index = self._history(name)
+        index.parent.mkdir(parents=True, exist_ok=True)
+        records = self._checkpoints(name)
+        key = uuid.uuid4().hex
+        target = self.path(index.parent / (key + '.expproj'))
+        atomic_write(target, data)
+        record = dict(checkpoint=key, revision=digest(data), label=label)
+        records.append(record)
+        atomic_write(index, json.dumps(records[-40:]).encode())
+        for old in records[:-40]:
+            self.path(index.parent / (old['checkpoint'] + '.expproj')).unlink(missing_ok=True)
+        return record
+
+    def restore(self, name, revision, checkpoint):
+        with self.lock:
+            target = self.path(name, '.expproj')
+            record = next((r for r in self.checkpoints(name) if r['checkpoint'] == checkpoint), None)
+            if record is None: raise ProjectError('Unknown checkpoint for this project')
+            source = self.path(self._history(name).parent / (checkpoint + '.expproj'))
+            if self.revision(source) != record['revision']: raise ProjectError('Checkpoint checksum does not match')
+            # Raw bytes retain library paths relative to the original project location.
+            data = source.read_bytes()
+            project_from_record(json.loads(data))
+            result = self.commit(name, revision, data)
+            return dict(**result, restored=checkpoint)
+
+    def update(self, name, revision, changes):
+        return self.batch(name, revision, [dict(op='project', changes=changes)])
+
+    def node(self, name, revision, node_id, changes=None, remove=False):
+        return self.batch(name, revision, [dict(op='node', id=node_id, changes=changes or {}, remove=remove)])
+
+    def character(self, name, revision, character_id, changes=None, remove=False):
+        return self.batch(name, revision, [dict(op='character', id=character_id, changes=changes or {}, remove=remove)])
+
+    def import_image(self, name, revision, source):
+        from .model import MAX_ASSET_BYTES
+        path = self.path(source)
+        if path.stat().st_size > MAX_ASSET_BYTES: raise ProjectError('Image is too large')
+        return self.edit(name, revision, lambda project: project.add_image(path.name, path.read_bytes()))
+
+    def library_image(self, name, revision, library, resource, episode=None):
+        from exp_runtime.content import ContentLibrary
+        from .assets import import_library_image
+        path = self.path(library)
+        def apply(project):
+            with ContentLibrary(path) as content:
+                import_library_image(project, content, resource, content.open_episode(episode) if episode else None)
+        return self.edit(name, revision, apply)
+
+    def import_episode(self, source, destination, game='shs'):
+        from .native import import_exp
+        from .model import MAX_PROJECT_BYTES
+        with self.lock:
+            source, output = self.path(source, '.exp'), self.path(destination, '.expproj')
+            if source.stat().st_size > MAX_PROJECT_BYTES: raise ProjectError('EXP exceeds the editable project size limit')
+            with guard(output):
+                if output.exists() or session_info(output): raise ProjectError('Project destination already exists')
+                save_project(import_exp(source.read_bytes(), game=game), output)
+            return self.describe(destination)
+
+    def export(self, name, destination, revision, language=None, replace_revision=None):
+        with self.lock:
+            project, actual = self.read(name)
+            if actual != revision: raise ProjectError('Project changed; read its current revision before exporting')
+            output = self.path(destination, '.exp')
+            if output.exists() and self.revision(output) != replace_revision:
+                raise ProjectError('Export exists; provide its SHA-256 as replace_revision to replace it')
+            result = compile_details(project, language=language)
+            atomic_write(output, result.data)
+            return {'path': str(output.relative_to(self.root)), 'sha256': self.revision(output),
+                    'bytes': len(result.data), 'scripts': sorted(result.locations)}
+
+    def start_debug(self, name, start=None, *, seed=None, library=None, language=None):
+        from .debugger import DebugSession
+        if len(self.debuggers) >= 8: raise ProjectError('Close a debug session before starting another (limit 8)')
+        project, revision = self.read(name)
+        if library is not None: project.library = str(self.path(library)) if library else ''
+        if project.library: project.library = str(self.path(project.library))
+        debugger = DebugSession(project, start=start, seed=seed, library=project.library or None, language=language)
+        key = uuid.uuid4().hex
+        debugger.path, debugger.revision = name, revision
+        self.debuggers[key] = debugger
+        from .playtest import Playtest
+        self.playtests[key] = Playtest(debugger)
+        return {'session': key, 'revision': revision, **debugger.state()}
+
+    def debugger(self, key):
+        if key not in self.debuggers: raise ProjectError('Unknown or closed playtest session')
+        return self.debuggers[key]
+
+    def close_debug(self, key):
+        debugger = self.debuggers.pop(key, None)
+        if debugger is not None: debugger.close()
+        self.playtests.pop(key, None)
+        return dict(closed=True)

exp_runtime_creator-0.6.0.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: exp-runtime-creator
+Version: 0.6.0
+Summary: Visual desktop episode creator and native EXP compiler for EXP Runtime
+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.6.0
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.28; extra == "mcp"
+Requires-Dist: exp-runtime-player[desktop]==0.6.0; extra == "mcp"
+Requires-Dist: exp-runtime-shs==0.6.0; extra == "mcp"
+Requires-Dist: exp-runtime-cod==0.6.0; extra == "mcp"
+Provides-Extra: desktop
+Requires-Dist: PySide6-Essentials<7,>=6.10; extra == "desktop"
+Requires-Dist: exp-runtime-player[desktop]==0.6.0; extra == "desktop"
+Requires-Dist: exp-runtime-shs==0.6.0; extra == "desktop"
+Requires-Dist: exp-runtime-cod==0.6.0; extra == "desktop"
+Dynamic: license-file
+
+# EXP Runtime Creator
+
+Optional visual desktop editor for new SHS and CoD episodes. Author dialogue,
+choices, branches, characters, audio, minigames and translations, save portable projects and export native CSPUD/KiWi EXP
+files for EXP Runtime and the original games. Original-slot export preserves
+an existing episode's catalog IDs. Native KiWi loader/VM checks pass for SHS
+Android, SHS iOS and CoD iOS; full original-app playback remains unverified.
+
+Install the desktop editor with pip, then launch it:
+
+```sh
+python -m pip install 'exp-runtime-creator[desktop]>=0.6.0'
+exp-creator
+```
+
+Standalone Creator downloads are also included in the v0.6.0 GitHub release
+for Windows, Linux and macOS (Apple Silicon and Intel).
+
+The Python authoring API needs only `exp-runtime-formats`. The `desktop` extra
+adds Qt, the shared player and both game adapters. No game assets are included.
+Preview uses an imported game library and temporary saves. The independent
+`mcp` extra adds a stdio server, production playtesting and isolated player
+rendering/audio previews. It includes pygame but does not install Qt.
+Run `exp-creator-mcp --workspace /path/to/stories`.
+
+Install both extras with `python -m pip install 'exp-runtime-creator[desktop,mcp]>=0.6.0'`
+to use the editor and MCP server together.
+
+Open a saved workspace project in the desktop creator to share live edits with
+an MCP client. Models see unsaved work, their edits appear immediately, and
+desktop undo/redo covers both. Save in the editor to write the shared project.
+
+See the project README and `docs/CREATOR.md` in the source repository.

exp_runtime_creator-0.6.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+exp_runtime/creator/__init__.py,sha256=QZLWZm30iREFtLVJTGqsVkfaqXQftp96gwmmjipgoBU,516
+exp_runtime/creator/__main__.py,sha256=XswRWYtj0jgiQbgG7O9D6Q7Fd5TqRrTPA_XQTAt7O1o,3305
+exp_runtime/creator/assets.py,sha256=LKCY1seEcpVJfqPLHlZVmZlcjVjJ3XF5CVMWiDoFSVo,2296
+exp_runtime/creator/catalog.py,sha256=wkwF_WftOQTWRjQEYDd2XLw7YgDvr4mEDpg5sOqp6S4,1630
+exp_runtime/creator/compiler.py,sha256=5v-1CEN0G-0Kwq30GW9qRCupnBzPJOD0yfceYlhexF4,23490
+exp_runtime/creator/debugger.py,sha256=Re2sAjhYbCRo3Y1ZVqVaXcIMzg43oou6KuOWNIsVxuw,5616
+exp_runtime/creator/diagnostics.py,sha256=hEI4vj17J9g__UBdPX9U1NhUJ4YIYPiDRC0Gy95A2NA,5850
+exp_runtime/creator/editing.py,sha256=mSonHvyqckzc2vQHiyZMs5akBWm3yB339msBDUqeXnk,3582
+exp_runtime/creator/expressions.py,sha256=OytGo-IRfJhWPGg1L_IDletiheGlpT6u8EKDAnulMFg,3916
+exp_runtime/creator/features.py,sha256=DI2xwXLonw4Ltojqnu9CteCkN53vJIITQFUlQ7KPx3U,5259
+exp_runtime/creator/graph.py,sha256=kZuUNSDiiN5DVpJY4U90AGiTVLgH07X0Ia2Nr_EXv9I,6424
+exp_runtime/creator/kiwi-hammer.svg,sha256=6c8OU7GDOaBSrFl2kRHCRrfHTrIXh6UEBfd2wvqo0mw,6179
+exp_runtime/creator/live.py,sha256=Vf41PrHrHVxmFEdlbN8iadlBUZNgro8137BSIH0Z3ec,6039
+exp_runtime/creator/mcp_results.py,sha256=Kzqj8oKwEwf6Re66C1OJAquHNUwxrEl8TbRfJ_7Vf5s,3091
+exp_runtime/creator/mcp_server.py,sha256=fzwDizrfvT_pr03O5Y6bVRCZ_2HhiywkrMBnsG00c8E,26203
+exp_runtime/creator/mcp_types.py,sha256=ARlAVAttrD2qXcYbcPJMdfjCCOPKAdJEOA6KQQFpyv8,3481
+exp_runtime/creator/media.py,sha256=gw1WoIvkOZEPFogEbzlhYdPgWwyHs0x1w5NRNGqJ8lA,6983
+exp_runtime/creator/minigames.py,sha256=IzmL0H1XHyu-KnMDI8t4xnM45x27WP3iaAy2NFoIx2g,10668
+exp_runtime/creator/model.py,sha256=p5Ewosfy9ueGHqfzPD9mxh8kYFNkz4oFm3OYSmN9NLY,15903
+exp_runtime/creator/native.py,sha256=P4yRG3xyEyX1Y_ifE4v7XgUWZcj-LWa5_odbKSjsTqY,8978
+exp_runtime/creator/operations.py,sha256=6LAXZuuzGZvyyIuLtLoCKnun81MiLbFOvQOy1RtZYHc,4973
+exp_runtime/creator/panels.py,sha256=vM31pl5Vpkjh7fNS2ZKodIYTznj2FZfj3eKvh-_b-DQ,11719
+exp_runtime/creator/playtest.py,sha256=37o4q4rwVcBJasrdaT0iIwQYG-mowaqyp-x1ZUM-r1U,10939
+exp_runtime/creator/preview.py,sha256=Ld-b4ur8S3-3HoFxiNgciN7iTQt_zzALMkoD1wd6fW4,1248
+exp_runtime/creator/schema.py,sha256=qomZ89c8tpAekNf6mlCXAsVaQ6rSqqzyiIv7d4RnxTo,7694
+exp_runtime/creator/sharing.py,sha256=lQy5pLSQwfa6OoB38-gKq_GGgGg2qFAn1NNF_jazVF4,6450
+exp_runtime/creator/ui.py,sha256=hXsXaaRHWfkdba0nLp6riAMCAzCMYB6z5mUEcgdN9as,51992
+exp_runtime/creator/workspace.py,sha256=tMOtPQWahoz41Uo0onOmhzWJgmNEobG8t1JCRidjFAc,14718
+exp_runtime_creator-0.6.0.dist-info/licenses/LICENSE,sha256=y2xxdaMMD9iKqLFR2Lp8sM_0b3qZWxU4_vW0zgufh2k,1070
+exp_runtime_creator-0.6.0.dist-info/METADATA,sha256=ZnO1QgWDL581sghccDFs7nLPF4swD9mdlMyIm4y7lJI,3652
+exp_runtime_creator-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+exp_runtime_creator-0.6.0.dist-info/entry_points.txt,sha256=d9mJXJursuv0dw3lpULLwZ_phfaJT5sjTk_5C_HDkn4,135
+exp_runtime_creator-0.6.0.dist-info/top_level.txt,sha256=1uRgkxqLAgYpITLluWh9qs6TpAD83zFoh0E5lbic4RA,12
+exp_runtime_creator-0.6.0.dist-info/RECORD,,

exp_runtime_creator-0.6.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

exp_runtime_creator-0.6.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+exp-creator-mcp = exp_runtime.creator.mcp_server:main
+
+[gui_scripts]
+exp-creator = exp_runtime.creator.__main__:main

exp_runtime_creator-0.6.0.dist-info/licenses/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_creator-0.6.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+exp_runtime