exp-runtime-creator 0.6.0__tar.gz

exp_runtime_creator-0.6.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_creator-0.6.0/MANIFEST.in

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

exp_runtime_creator-0.6.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,33 @@
+# 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/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools >= 61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "exp-runtime-creator"
+version = "0.6.0"
+description = "Visual desktop episode creator and native EXP compiler for EXP Runtime"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10"
+dependencies = ["exp-runtime-formats==0.6.0"]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.28,<2", "exp-runtime-player[desktop]==0.6.0", "exp-runtime-shs==0.6.0", "exp-runtime-cod==0.6.0"]
+desktop = ["PySide6-Essentials>=6.10,<7", "exp-runtime-player[desktop]==0.6.0", "exp-runtime-shs==0.6.0", "exp-runtime-cod==0.6.0"]
+
+[project.scripts]
+exp-creator-mcp = "exp_runtime.creator.mcp_server:main"
+
+[project.gui-scripts]
+exp-creator = "exp_runtime.creator.__main__:main"
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["exp_runtime", "exp_runtime.*"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"exp_runtime.creator" = ["kiwi-hammer.svg"]

exp_runtime_creator-0.6.0/setup.cfg

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

exp_runtime_creator-0.6.0/src/exp_runtime/creator/__init__.py

@@ -0,0 +1,8 @@
+"""Episode authoring API. Importing this module does not initialize a GUI."""
+from .model import Asset, Character, Choice, Node, Project, ProjectError, load_project, save_project
+from .compiler import compile_project, compile_details, export_project, export_native_slot
+
+from .native import import_exp
+
+__all__ = ['Asset', 'Character', 'Choice', 'Node', 'Project', 'ProjectError', 'load_project',
+           'save_project', 'compile_project', 'compile_details', 'export_project', 'export_native_slot', 'import_exp']

exp_runtime_creator-0.6.0/src/exp_runtime/creator/__main__.py

@@ -0,0 +1,69 @@
+"""Desktop entry point and headless project export command."""
+import argparse
+from pathlib import Path
+
+from exp_runtime.exp import ContentError
+from .compiler import export_project, export_native_slot
+from .model import load_project, save_project
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description='EXP Runtime episode creator')
+    parser.add_argument('project', nargs='?', type=Path, help='Editable .expproj document')
+    parser.add_argument('--import-exp', type=Path, help='Import an EXP; save to the project argument')
+    parser.add_argument('--language', choices=('en', 'fr', 'it', 'de', 'es'), help='Story language for export')
+    parser.add_argument('--smoke-test', action='store_true', help=argparse.SUPPRESS)
+    parser.add_argument('--export', type=Path, help='Compile a project without starting the GUI')
+    parser.add_argument('--native-slot', type=Path, help='With --export, retain this original EXP catalog identity')
+    parser.add_argument('--preview', type=Path, help=argparse.SUPPRESS)
+    parser.add_argument('--library', type=Path, help=argparse.SUPPRESS)
+    parser.add_argument('--game', choices=('shs', 'cod'), default='shs', help=argparse.SUPPRESS)
+    args = parser.parse_args(argv)
+    try:
+        if args.smoke_test:
+            from PySide6.QtWidgets import QApplication
+            from .ui import Editor
+            from .compiler import compile_project
+            app = QApplication.instance() or QApplication([])
+            editor = Editor(discover_library=False); editor.show(); app.processEvents()
+            assert compile_project(editor.project)
+            assert not editor.grab().isNull()
+            editor.close(); app.processEvents()
+            return
+        if args.import_exp:
+            if not args.project: parser.error('--import-exp requires an output .expproj path')
+            from .native import import_exp
+            if args.project.exists(): parser.error('Import destination already exists')
+            save_project(import_exp(args.import_exp.read_bytes(), game=args.game), args.project)
+            return
+        if args.export:
+            if not args.project:
+                parser.error('--export requires an .expproj document')
+            project = load_project(args.project)
+            if args.language: project.language = args.language
+            if args.native_slot:
+                export_native_slot(project, args.native_slot, args.export)
+            else:
+                export_project(project, args.export)
+            return
+        if args.native_slot:
+            parser.error('--native-slot requires --export')
+        if args.preview:
+            if not args.library:
+                parser.error('--preview requires --library')
+            from .preview import play_preview
+            play_preview(args.preview, args.library, args.game)
+            return
+        try:
+            from .ui import launch
+        except ModuleNotFoundError as error:
+            if error.name and error.name.startswith('PySide6'):
+                parser.error('The visual editor requires exp-runtime[creator] or exp-runtime-creator[desktop]')
+            raise
+        launch(args.project)
+    except (ContentError, OSError) as error:
+        parser.error(str(error))
+
+
+if __name__ == '__main__':
+    main()

exp_runtime_creator-0.6.0/src/exp_runtime/creator/assets.py

@@ -0,0 +1,56 @@
+"""Read-only access to a user's already imported game library."""
+from io import BytesIO
+
+from .model import Asset, ProjectError
+
+
+def player_library(game):
+    """Find a usable library through the player's remembered/default location."""
+    from exp_runtime.content import ContentError, ContentLibrary
+    from exp_runtime.launcher import default_library
+    try:
+        path = default_library(game)
+        with ContentLibrary(path) as library:
+            if library.game_id == game:
+                return str(path.resolve())
+    except (ContentError, OSError):
+        pass
+    return ''
+
+
+def image_png(data: bytes) -> bytes:
+    """Decode a single original image for the browser or an embedded copy."""
+    from PIL import Image
+    from exp_runtime.ui_assets import ImagePack
+    if data.startswith((b'\x89PNG', b'\xff\xd8')):
+        with Image.open(BytesIO(data)) as image:
+            image.load()
+            image = image.convert('RGBA')
+    else:
+        pack = ImagePack.parse(data)
+        if len(pack.images) != 1 or pack.images[0].mode != 'RGBA':
+            raise ProjectError('Select a single portrait or background, not a UI atlas')
+        frame = pack.images[0]
+        image = Image.frombytes('RGBA', (frame.width, frame.height), frame.pixels)
+    output = BytesIO()
+    image.save(output, format='PNG')
+    return output.getvalue()
+
+
+def import_library_image(project, library, resource, episode=None):
+    if library.game_id != project.game:
+        raise ProjectError('The library must match the project game')
+    if resource < 25000:
+        image_png(library.read_asset(resource))  # Reject scripts, fonts and atlases.
+        existing = next((asset for asset in project.assets if asset.id == resource), None)
+        if existing:
+            return existing
+        asset = Asset(resource, f'Base image {resource}')
+        project.assets.append(asset)
+        return asset
+    if resource < 26000 or episode is None:
+        raise ProjectError('Select an episode image with an ID of 26000 or higher')
+    # Copy to a reserved local slot: no dependency on the source episode,
+    # and no accidental expression variants from neighboring original IDs.
+    png = image_png(episode.read_asset(resource))
+    return project.add_image(f'Episode image {resource}', png)

exp_runtime_creator-0.6.0/src/exp_runtime/creator/catalog.py

@@ -0,0 +1,30 @@
+"""Paginated, content-derived asset discovery. Never guess original names."""
+from exp_runtime.content import ContentLibrary
+from .graph import page
+from .media import inspect_asset
+
+
+def library_assets(workspace, library, *, episode=None, kind=None, query='', offset=0, limit=50):
+    page(offset, limit)
+    with ContentLibrary(workspace.path(library)) as content:
+        resources = content.open_episode(episode) if episode else content
+        read = resources.archive.read if episode else content.read_asset
+        ids = sorted(resources.archive.entries if episode else content.base_members.keys() | content.music_members.keys())
+        found = []
+        # Metadata is derived only for matching IDs. A type filter requires
+        # inspection, so bound every scan and return a continuation offset.
+        index = offset
+        while index < len(ids) and index < offset + 200 and len(found) < limit:
+            resource = ids[index]; index += 1
+            if query.casefold() not in str(resource): continue
+            info = inspect_asset(read(resource))
+            if kind and info['type'] != kind: continue
+            found.append(dict(id=resource, name=None, **info))
+        return dict(assets=found, total_resources=len(ids), scanned=index - offset,
+                    next_offset=index if index < len(ids) else None)
+
+
+def read_asset(workspace, library, resource, episode=None):
+    with ContentLibrary(workspace.path(library)) as content:
+        resources = content.open_episode(episode) if episode else content
+        return resources.archive.read(resource) if episode else content.read_asset(resource)