mb-sc-tools 0.1.1__tar.gz

mb_sc_tools-0.1.1/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.1
+
+- Added configurable workspace and options dataclasses
+- Added publish-ready packaging files
+- Kept decode and encode support for Supercell `.sc` files with ASTC/KTX workflow
+
+## 0.1.0
+
+- Initial release

mb_sc_tools-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bsod4ik
+
+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.

mb_sc_tools-0.1.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include src *.py

mb_sc_tools-0.1.1/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: mb-sc-tools
+Version: 0.1.1
+Summary: Mobile-friendly Supercell .sc decoder and encoder for Python
+Author: bsod4ik
+License-Expression: MIT
+Keywords: supercell,brawl-stars,sc,texture,astc,mobile
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: zstandard>=0.22.0
+Requires-Dist: lz4>=4.3.3
+Requires-Dist: Pillow>=10.0.0
+Dynamic: license-file
+
+# mb-sc-tools
+
+`mb-sc-tools` is a Python library and CLI for decoding and encoding Supercell `.sc` files on phones and desktops.
+
+It supports:
+
+- decoding `.sc` into PNG textures and `data.json`
+- encoding edited PNGs back into `.sc`
+- `SC` wrappers with `zstd`, `lzma`, and `lz4` payloads
+- ARM64 phones and desktop systems
+- automatic `astcenc` download on first use for ASTC/KTX textures
+- configurable workspace, output paths, backup name, and ASTC encoder path
+
+## Install
+
+```bash
+pip install mb-sc-tools
+```
+
+## CLI
+
+```bash
+mb-sc-tools
+```
+
+Or direct commands:
+
+```bash
+mb-sc-tools decode /path/to/ui.sc
+mb-sc-tools encode /path/to/sc_decoded/ui
+```
+
+More explicit control:
+
+```bash
+mb-sc-tools decode /path/to/ui.sc \
+  --workspace-root /tmp/sc-work \
+  --output-dir /tmp/sc-work/custom/ui \
+  --source-backup-name source.sc
+
+mb-sc-tools encode /tmp/sc-work/custom/ui \
+  --workspace-root /tmp/sc-work \
+  --output /tmp/sc-work/sc_encoded/ui.sc
+```
+
+## Python API
+
+```python
+from pathlib import Path
+
+from mb_sc_tools import (
+    DecodeOptions,
+    EncodeOptions,
+    WorkspaceConfig,
+    decode_to_workspace,
+    encode_folder,
+)
+
+workspace = WorkspaceConfig(root=Path("/tmp/sc-work"))
+
+decoded_dir, data = decode_to_workspace(
+    Path("/sdcard/ui.sc"),
+    options=DecodeOptions(
+        workspace=workspace,
+        source_backup_name="source.sc",
+    ),
+)
+
+encoded_path = encode_folder(
+    decoded_dir,
+    options=EncodeOptions(
+        workspace=workspace,
+        output_path=Path("/tmp/sc-work/sc_encoded/ui.sc"),
+    ),
+)
+```
+
+## Output layout
+
+On Android/Termux, if `/sdcard/sc` exists the tool writes to:
+
+- `/sdcard/sc/sc_decoded/<file_stem>/`
+- `/sdcard/sc/sc_encoded/<original_name>.sc`
+
+Otherwise it writes to a local `./sc/` workspace.

mb_sc_tools-0.1.1/README.md

@@ -0,0 +1,85 @@
+# mb-sc-tools
+
+`mb-sc-tools` is a Python library and CLI for decoding and encoding Supercell `.sc` files on phones and desktops.
+
+It supports:
+
+- decoding `.sc` into PNG textures and `data.json`
+- encoding edited PNGs back into `.sc`
+- `SC` wrappers with `zstd`, `lzma`, and `lz4` payloads
+- ARM64 phones and desktop systems
+- automatic `astcenc` download on first use for ASTC/KTX textures
+- configurable workspace, output paths, backup name, and ASTC encoder path
+
+## Install
+
+```bash
+pip install mb-sc-tools
+```
+
+## CLI
+
+```bash
+mb-sc-tools
+```
+
+Or direct commands:
+
+```bash
+mb-sc-tools decode /path/to/ui.sc
+mb-sc-tools encode /path/to/sc_decoded/ui
+```
+
+More explicit control:
+
+```bash
+mb-sc-tools decode /path/to/ui.sc \
+  --workspace-root /tmp/sc-work \
+  --output-dir /tmp/sc-work/custom/ui \
+  --source-backup-name source.sc
+
+mb-sc-tools encode /tmp/sc-work/custom/ui \
+  --workspace-root /tmp/sc-work \
+  --output /tmp/sc-work/sc_encoded/ui.sc
+```
+
+## Python API
+
+```python
+from pathlib import Path
+
+from mb_sc_tools import (
+    DecodeOptions,
+    EncodeOptions,
+    WorkspaceConfig,
+    decode_to_workspace,
+    encode_folder,
+)
+
+workspace = WorkspaceConfig(root=Path("/tmp/sc-work"))
+
+decoded_dir, data = decode_to_workspace(
+    Path("/sdcard/ui.sc"),
+    options=DecodeOptions(
+        workspace=workspace,
+        source_backup_name="source.sc",
+    ),
+)
+
+encoded_path = encode_folder(
+    decoded_dir,
+    options=EncodeOptions(
+        workspace=workspace,
+        output_path=Path("/tmp/sc-work/sc_encoded/ui.sc"),
+    ),
+)
+```
+
+## Output layout
+
+On Android/Termux, if `/sdcard/sc` exists the tool writes to:
+
+- `/sdcard/sc/sc_decoded/<file_stem>/`
+- `/sdcard/sc/sc_encoded/<original_name>.sc`
+
+Otherwise it writes to a local `./sc/` workspace.

mb_sc_tools-0.1.1/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mb-sc-tools"
+version = "0.1.1"
+description = "Mobile-friendly Supercell .sc decoder and encoder for Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  {name = "bsod4ik"}
+]
+keywords = ["supercell", "brawl-stars", "sc", "texture", "astc", "mobile"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "zstandard>=0.22.0",
+  "lz4>=4.3.3",
+  "Pillow>=10.0.0",
+]
+
+[project.scripts]
+mb-sc-tools = "mb_sc_tools.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

mb_sc_tools-0.1.1/setup.cfg

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

mb_sc_tools-0.1.1/src/mb_sc_tools/__init__.py

@@ -0,0 +1,23 @@
+from .codec import decode_file, decode_to_workspace, encode_folder
+from .config import (
+    DATA_JSON_NAME,
+    DEFAULT_SOURCE_BACKUP,
+    DecodeOptions,
+    EncodeOptions,
+    WorkspaceConfig,
+    get_default_workspace_root,
+)
+
+__all__ = [
+    "DATA_JSON_NAME",
+    "DEFAULT_SOURCE_BACKUP",
+    "DecodeOptions",
+    "EncodeOptions",
+    "WorkspaceConfig",
+    "decode_file",
+    "decode_to_workspace",
+    "encode_folder",
+    "get_default_workspace_root",
+]
+
+__version__ = "0.1.1"

mb_sc_tools-0.1.1/src/mb_sc_tools/astc.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import platform
+import shutil
+import urllib.request
+import zipfile
+from pathlib import Path
+
+
+class AstcError(RuntimeError):
+    pass
+
+
+KNOWN_ASTCENC = [
+    Path("/root/tools/astcenc/bin/astcenc-neon"),
+    Path("/root/tools/astcenc/bin/astcenc-sve_128"),
+    Path("/root/tools/astcenc/bin/astcenc-sve_256"),
+]
+
+AUTO_ASTCENC_RELEASE = {
+    ("Linux", "aarch64"): (
+        "https://github.com/ARM-software/astc-encoder/releases/download/5.3.0/"
+        "astcenc-5.3.0-linux-arm64.zip",
+        "bin/astcenc-neon",
+    ),
+    ("Linux", "x86_64"): (
+        "https://github.com/ARM-software/astc-encoder/releases/download/5.3.0/"
+        "astcenc-5.3.0-linux-x64.zip",
+        "bin/astcenc-avx2",
+    ),
+    ("Windows", "AMD64"): (
+        "https://github.com/ARM-software/astc-encoder/releases/download/5.3.0/"
+        "astcenc-5.3.0-windows-x64.zip",
+        "bin/astcenc-avx2.exe",
+    ),
+    ("Windows", "ARM64"): (
+        "https://github.com/ARM-software/astc-encoder/releases/download/5.3.0/"
+        "astcenc-5.3.0-windows-arm64.zip",
+        "bin/astcenc-neon.exe",
+    ),
+    ("Darwin", "arm64"): (
+        "https://github.com/ARM-software/astc-encoder/releases/download/5.3.0/"
+        "astcenc-5.3.0-macos-universal.zip",
+        "bin/astcenc-neon",
+    ),
+    ("Darwin", "x86_64"): (
+        "https://github.com/ARM-software/astc-encoder/releases/download/5.3.0/"
+        "astcenc-5.3.0-macos-universal.zip",
+        "bin/astcenc-avx2",
+    ),
+}
+
+
+def ensure_astcenc(user_path: str | None = None) -> Path:
+    if user_path:
+        path = Path(user_path).expanduser()
+        if not path.is_file():
+            raise AstcError(f"astcenc not found: {path}")
+        return path
+
+    system_path = shutil.which("astcenc")
+    if system_path:
+        return Path(system_path)
+
+    for candidate in KNOWN_ASTCENC:
+        if candidate.is_file():
+            return candidate
+
+    key = (platform.system(), platform.machine())
+    if key not in AUTO_ASTCENC_RELEASE:
+        raise AstcError(f"Unsupported platform for astcenc auto-download: {key}")
+
+    url, relbin = AUTO_ASTCENC_RELEASE[key]
+    cache_dir = Path.home() / ".cache" / "mb_sc_tools" / "astcenc"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    binary_path = cache_dir / relbin
+    if binary_path.is_file():
+        return binary_path
+
+    zip_path = cache_dir / "astcenc.zip"
+    urllib.request.urlretrieve(url, zip_path)
+    with zipfile.ZipFile(zip_path) as archive:
+        archive.extractall(cache_dir)
+    binary_path.chmod(0o755)
+    return binary_path

mb_sc_tools-0.1.1/src/mb_sc_tools/cli.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .codec import decode_to_workspace, encode_folder
+from .config import DATA_JSON_NAME, DecodeOptions, EncodeOptions, WorkspaceConfig, get_default_workspace_root
+
+
+def panel(title: str, lines: list[str]) -> str:
+    width = max(len(title) + 2, *(len(line) for line in lines), 32)
+    top = "┌" + "─" * (width + 2) + "┐"
+    mid = f"│ {title.ljust(width)} │"
+    body = "\n".join(f"│ {line.ljust(width)} │" for line in lines)
+    bottom = "└" + "─" * (width + 2) + "┘"
+    return "\n".join([top, mid, body, bottom])
+
+
+def ask(prompt: str, default: str | None = None) -> str:
+    suffix = f" [{default}]" if default else ""
+    value = input(f"{prompt}{suffix}: ").strip()
+    return value or (default or "")
+
+
+def find_sc_candidates() -> list[Path]:
+    root = get_default_workspace_root().parent if get_default_workspace_root().name == "sc" else Path("/sdcard")
+    roots = [Path("/sdcard"), get_default_workspace_root(), Path.cwd(), root]
+    found: list[Path] = []
+    for base in roots:
+        if not base.exists():
+            continue
+        for item in sorted(base.glob("*.sc")):
+            if item.is_file() and item not in found:
+                found.append(item)
+    return found[:20]
+
+
+def find_decoded_candidates() -> list[Path]:
+    decoded_root = get_default_workspace_root() / "sc_decoded"
+    if not decoded_root.exists():
+        return []
+    return sorted(
+        [item for item in decoded_root.iterdir() if item.is_dir() and (item / DATA_JSON_NAME).is_file()],
+        key=lambda item: item.stat().st_mtime,
+        reverse=True,
+    )[:20]
+
+
+def interactive_decode() -> None:
+    candidates = find_sc_candidates()
+    lines = ["Found .sc files:"]
+    lines.extend(f"{idx + 1}. {path}" for idx, path in enumerate(candidates)) if candidates else lines.append("nothing found, type the path manually")
+    print(panel("mb-sc-tools Decode", lines))
+    default = str(candidates[0]) if candidates else str(Path.cwd() / "ui.sc")
+    source = Path(ask("Path to .sc file", default)).expanduser().resolve()
+    workspace_root = ask("Workspace root", str(get_default_workspace_root()))
+    options = DecodeOptions(workspace=WorkspaceConfig(root=Path(workspace_root)))
+    out_dir, data = decode_to_workspace(source, options=options)
+    print()
+    print(panel("Decode Complete", [f"Folder: {out_dir}", f"PNG: {len(data['textures'])}", f"JSON: {out_dir / DATA_JSON_NAME}"]))
+
+
+def interactive_encode() -> None:
+    candidates = find_decoded_candidates()
+    lines = ["Found decoded folders:"]
+    lines.extend(f"{idx + 1}. {path}" for idx, path in enumerate(candidates)) if candidates else lines.append("nothing found, type the path manually")
+    print(panel("mb-sc-tools Encode", lines))
+    default = str(candidates[0]) if candidates else str(get_default_workspace_root() / "sc_decoded" / "ui")
+    decoded_dir = Path(ask("Path to decoded folder", default)).expanduser().resolve()
+    workspace_root = ask("Workspace root", str(get_default_workspace_root()))
+    options = EncodeOptions(workspace=WorkspaceConfig(root=Path(workspace_root)))
+    encoded_path = encode_folder(decoded_dir, options=options)
+    print()
+    print(panel("Encode Complete", [f"SC: {encoded_path}"]))
+
+
+def interactive_menu() -> int:
+    while True:
+        print()
+        print(panel("mb-sc-tools", ["1. Decode .sc -> PNG + data.json", "2. Encode decoded folder -> .sc", "3. Exit"]))
+        choice = ask("Select", "1")
+        print()
+        if choice == "1":
+            interactive_decode()
+        elif choice == "2":
+            interactive_encode()
+        elif choice == "3":
+            return 0
+        else:
+            print("Unknown choice")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Decode and encode Supercell .sc files")
+    subparsers = parser.add_subparsers(dest="command")
+
+    decode_parser = subparsers.add_parser("decode", help="Decode a .sc file")
+    decode_parser.add_argument("input", help="Input .sc file")
+    decode_parser.add_argument("-o", "--output-dir", help="Explicit decoded output directory")
+    decode_parser.add_argument("--workspace-root", help="Workspace root")
+    decode_parser.add_argument("--astcenc", help="Path to astcenc binary")
+    decode_parser.add_argument("--source-backup-name", default="original.sc", help="Name of source .sc backup inside decoded folder")
+
+    encode_parser = subparsers.add_parser("encode", help="Encode a decoded folder")
+    encode_parser.add_argument("input", help="Decoded folder with PNGs and data.json")
+    encode_parser.add_argument("-o", "--output", help="Output .sc file")
+    encode_parser.add_argument("--workspace-root", help="Workspace root")
+    encode_parser.add_argument("--astcenc", help="Path to astcenc binary")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "decode":
+        options = DecodeOptions(
+            output_dir=Path(args.output_dir).expanduser().resolve() if args.output_dir else None,
+            workspace=WorkspaceConfig(root=Path(args.workspace_root).expanduser().resolve()) if args.workspace_root else None,
+            astcenc_path=args.astcenc,
+            source_backup_name=args.source_backup_name,
+        )
+        out_dir, data = decode_to_workspace(Path(args.input).expanduser().resolve(), options=options)
+        print(panel("Decode Complete", [f"Folder: {out_dir}", f"PNG: {len(data['textures'])}", f"JSON: {out_dir / DATA_JSON_NAME}"]))
+        return 0
+    if args.command == "encode":
+        options = EncodeOptions(
+            output_path=Path(args.output).expanduser().resolve() if args.output else None,
+            workspace=WorkspaceConfig(root=Path(args.workspace_root).expanduser().resolve()) if args.workspace_root else None,
+            astcenc_path=args.astcenc,
+        )
+        encoded_path = encode_folder(Path(args.input).expanduser().resolve(), options=options)
+        print(panel("Encode Complete", [f"SC: {encoded_path}"]))
+        return 0
+
+    return interactive_menu()