unity-devkit 0.1.0__py3-none-any.whl

unity_devkit/build_unity.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+import typer
+from pydantic_settings import BaseSettings
+
+from .cache import restore, save
+from .ci_step import ci_step
+from .license_restore import restore_license
+from .setup import configure_git, install_dotnet
+from .setup_oras import install_oras
+from .unity import prepare_unity_project, resolve_unity_build, run_unity_batchmode
+from .git_tags import get_latest_tag_version
+
+
+class Settings(BaseSettings):
+    github_workspace: str
+
+
+settings = Settings.model_validate({})
+
+app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+
+@app.command()
+def main(
+    project: str = typer.Option(help="Project name"),
+    project_path: Path = typer.Option(help="Path to Unity project"),
+    platform: str = typer.Option(help="Target platform"),
+    cache_key: str = typer.Option(help="Cache key prefix"),
+    run_number: int = typer.Option(0, help="CI run number"),
+    branch: str = typer.Option("dev", help="Git branch name"),
+    registry: str = typer.Option(help="OCI registry path"),
+    build_env: str = typer.Option(
+        "", help="Newline-separated KEY=VALUE pairs injected into the Unity build process environment"
+    ),
+) -> None:
+    for line in build_env.splitlines():
+        entry = line.strip()
+        if not entry:
+            continue
+        key, separator, value = entry.partition("=")
+        if not separator:
+            raise SystemExit(f"Invalid --build-env entry (expected KEY=VALUE): {entry!r}")
+        os.environ[key.strip()] = value.strip()
+
+    with ci_step("Setup"):
+        configure_git(settings.github_workspace)
+        install_dotnet("8.0")
+        install_oras()
+        restore_license()
+
+    branch_slug = branch.replace("/", "-")
+    tag = f"{cache_key}-{platform}-{branch_slug}"
+    fallback_branch = "dev"
+    fallback_tags = [f"{cache_key}-{platform}-{fallback_branch}"] if branch_slug != fallback_branch else None
+
+    with ci_step("Restore library cache"):
+        restore(registry, "unity-library", tag, Path("."), fallback_tags=fallback_tags)
+
+    with ci_step("Prepare build"):
+        project_config, build_flag, execute_method = resolve_unity_build(project, platform)
+        unity_project_path = project_config.path
+
+    with ci_step("Prepare project"):
+        prepare_unity_project(unity_project_path)
+
+    with ci_step(f"Build {unity_project_path.name} [{platform}]"):
+        tag_prefix = project_config.tag_prefix
+        if tag_prefix:
+            version = get_latest_tag_version(f"{tag_prefix}-v") or "0.0.0"
+            full_version = f"{version}-dev+{run_number}" if branch != "main" else f"{version}+{run_number}"
+            version_file = unity_project_path / ".build-version.json"
+            version_file.write_text(json.dumps({"version": full_version, "runNumber": run_number}))
+            print(f"Wrote version {full_version} (bundleVersionCode={run_number}) to {version_file}")
+
+        run_unity_batchmode(unity_project_path, f"{build_flag} -executeMethod {execute_method}", nographics=False)
+
+    with ci_step("Save library cache"):
+        # PackageCache (~1.6 GiB) is redundant with the shared UPM cache at ~/.cache/Unity/upm/
+        package_cache = project_path / "Library" / "PackageCache"
+        if package_cache.exists():
+            shutil.rmtree(package_cache)
+
+        save(registry, "unity-library", tag, Path("."), [f"{project_path}/Library/"])
+
+    with ci_step("Collect build artifacts"):
+        build_directory = project_path / "Build"
+        if build_directory.is_dir():
+            artifact_directory = Path("/tmp/unity-builds")
+            artifact_directory.mkdir(parents=True, exist_ok=True)
+            if platform == "linux64":
+                shutil.copytree(build_directory, artifact_directory, dirs_exist_ok=True)
+            else:
+                for file in build_directory.rglob("*"):
+                    if file.suffix in {".apk", ".exe"}:
+                        shutil.copy2(file, artifact_directory / file.name)

unity_devkit/cache.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import platform
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from subprocess import CalledProcessError
+
+from bashrun import bash, bash_check, bash_pipe
+
+
+def _posix(path: Path) -> str:
+    return path.as_posix() if platform.system() == "Windows" else str(path)
+
+
+def restore(
+    registry: str,
+    name: str,
+    tag: str,
+    target_directory: Path,
+    *,
+    required: bool = False,
+    fallback_tags: list[str] | None = None,
+) -> bool:
+    # OCI repository names must be lowercase; GitHub repository names preserve case
+    registry = registry.lower()
+    staging = Path(tempfile.gettempdir()) / "cache"
+
+    for candidate_tag in [tag, *(fallback_tags or [])]:
+        if candidate_tag != tag:
+            print(f"Falling back to {name}:{candidate_tag}")
+
+        reference = f"{registry}/{name}:{candidate_tag}"
+        staging.mkdir(parents=True, exist_ok=True)
+
+        if not bash_check(f"oras pull {reference} -o {staging}"):
+            shutil.rmtree(staging, ignore_errors=True)
+            continue
+
+        archive = staging / f"{name}.tar.zst"
+        try:
+            if platform.system() == "Windows":
+                bash_pipe(f"zstd -d {_posix(archive)} --stdout", f"tar -xf - -C {_posix(target_directory)}")
+            else:
+                bash(f"tar -xf {archive} -C {target_directory}")
+        except CalledProcessError:
+            print(f"WARNING: Cache extraction failed for {name}:{candidate_tag}, trying next")
+            shutil.rmtree(staging, ignore_errors=True)
+            continue
+
+        shutil.rmtree(staging, ignore_errors=True)
+        print(f"Cache hit: {name}:{candidate_tag}")
+        return True
+
+    if required:
+        print(f"FATAL: Required cache missing: {registry}/{name}:{tag}")
+        sys.exit(1)
+
+    print(f"Cache miss: {name}")
+    return False
+
+
+def save(registry: str, name: str, tag: str, source_directory: Path, paths: list[str]) -> None:
+    # OCI repository names must be lowercase; GitHub repository names preserve case
+    registry = registry.lower()
+    resolved: list[str] = []
+    for pattern in paths:
+        if any(character in pattern for character in "*?["):
+            matches = sorted(source_directory.glob(pattern))
+            resolved.extend(str(match.relative_to(source_directory)) for match in matches)
+        else:
+            resolved.append(pattern)
+
+    staging = Path(tempfile.gettempdir()) / "cache"
+    staging.mkdir(parents=True, exist_ok=True)
+    archive_name = f"{name}.tar.zst"
+    archive_path = staging / archive_name
+
+    joined = " ".join(resolved)
+    if platform.system() == "Windows":
+        bash_pipe(f"tar -cf - {joined}", f"zstd -o {_posix(archive_path)}", cwd=source_directory)
+    else:
+        bash(f"tar --zstd -cf {archive_path} {joined}", cwd=source_directory)
+
+    reference = f"{registry}/{name}:{tag}"
+    bash(f"oras push {reference} {archive_name}:application/vnd.unity-devkit.cache.v1+zstd", cwd=staging)
+    archive_path.unlink()
+    print(f"Saved cache: {reference}")

unity_devkit/ci_step.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    github_step_summary: str | None = None
+
+
+settings = Settings.model_validate({})
+_summary_initialized = False
+
+
+def _format_duration(seconds: float) -> str:
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    minutes = int(seconds // 60)
+    remaining = seconds % 60
+    return f"{minutes}m {remaining:.0f}s"
+
+
+def _write_summary(label: str, duration: float, *, failed: bool) -> None:
+    global _summary_initialized
+    summary_path = settings.github_step_summary
+    if not summary_path:
+        return
+    with open(summary_path, "a") as file:
+        if not _summary_initialized:
+            file.write("| Step | Duration |\n|---|---|\n")
+            _summary_initialized = True
+        status = " :x:" if failed else ""
+        file.write(f"| {label}{status} | {_format_duration(duration)} |\n")
+
+
+@contextmanager
+def ci_step(label: str) -> Generator[None]:
+    print(f"::group::{label}", flush=True)
+    start = time.monotonic()
+    failed = False
+    try:
+        yield
+    except BaseException:
+        failed = True
+        raise
+    finally:
+        duration = time.monotonic() - start
+        print("::endgroup::", flush=True)
+        _write_summary(label, duration, failed=failed)

unity_devkit/compile_unity.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from .unity import prepare_unity_project, resolve_unity_build, run_unity_batchmode
+
+app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+
+def build_unity_project(project: str, build: str) -> list[Path]:
+    project_config, build_flag, execute_method = resolve_unity_build(project, build)
+    project_path = project_config.path
+    prepare_unity_project(project_path)
+
+    build_directory = project_path / "Build"
+    before = snapshot_artifacts(build_directory)
+
+    run_unity_batchmode(project_path, f"{build_flag} -executeMethod {execute_method}", nographics=False)
+
+    after = snapshot_artifacts(build_directory)
+    produced = sorted(path for path, modification_time in after.items() if before.get(path) != modification_time)
+    if not produced:
+        raise SystemExit(
+            "Unity exited 0 but no .apk/.exe under Build/ was produced or updated — "
+            "the incremental build served a stale artifact. Delete the existing "
+            "output under Build/ and the project's Library/Bee/.../build/ tree, then retry."
+        )
+    return produced
+
+
+@app.command()
+def compile_unity(
+    project: Annotated[str, typer.Option(help="Unity project name (directory containing unity-build.json)")],
+    build: Annotated[str, typer.Option(help="Build target from the project's builds list (e.g. android-mobile)")],
+) -> None:
+    for artifact in build_unity_project(project, build):
+        print(f"Built: {artifact}")
+
+
+def snapshot_artifacts(build_directory: Path) -> dict[Path, int]:
+    if not build_directory.is_dir():
+        return {}
+    return {
+        path: path.stat().st_mtime_ns for suffix in (".apk", ".exe") for path in build_directory.rglob(f"*{suffix}")
+    }

unity_devkit/git_tags.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from bashrun import bash, bash_check, bash_output
+
+
+def get_latest_tag_version(prefix: str) -> str | None:
+    output = bash_output(f'git tag --list "{prefix}*" --sort=-v:refname').strip()
+    if not output:
+        return None
+    latest_tag = output.splitlines()[0]
+    return latest_tag[len(prefix) :]
+
+
+def has_changes_since_tag(tag: str | None, path: Path) -> bool:
+    if tag is None:
+        return True
+    return not bash_check(f"git diff --quiet {tag} HEAD -- {path}")
+
+
+def create_and_push_tag(tag: str) -> None:
+    bash(f"git tag {tag}")
+    bash(f"git push origin {tag}")

unity_devkit/install.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from bashrun import bash, bash_check, bash_handoff, bash_output
+
+from .compile_unity import build_unity_project
+from .projects import UnityProject, load_unity_projects
+
+INSTALLABLE_TARGETS = {"android-mobile", "magicleap", "linux64"}
+ADB_TARGETS = {"android-mobile", "magicleap"}
+CACHE_ROOT = Path.home() / ".unity-devkit" / "builds"
+
+app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+
+def _resolve_project(projects: dict[str, UnityProject], name: str) -> str:
+    for project_name in projects:
+        if project_name.lower() == name.lower():
+            return project_name
+    valid = ", ".join(projects.keys())
+    raise typer.BadParameter(f"Unknown project '{name}'. Valid projects: {valid}")
+
+
+def _resolve_target(project_config: UnityProject, project_name: str, target: str | None) -> str:
+    installable = [build for build in (project_config.builds or []) if build in INSTALLABLE_TARGETS]
+    if target is None:
+        if len(installable) == 1:
+            return installable[0]
+        valid = ", ".join(installable) if installable else "(none)"
+        raise typer.BadParameter(
+            f"--target is required for {project_name} (multiple installable targets). Valid targets: {valid}"
+        )
+    for build in installable:
+        if build.lower() == target.lower():
+            return build
+    valid = ", ".join(installable)
+    raise typer.BadParameter(f"No installable target '{target}' for {project_name}. Valid targets: {valid}")
+
+
+def _current_git_branch() -> str:
+    branch = bash_output("git rev-parse --abbrev-ref HEAD").strip()
+    if branch == "HEAD":
+        raise typer.BadParameter("HEAD is detached; pass --branch explicitly")
+    return branch
+
+
+def _find_run_id(artifact_name: str, branch: str) -> str:
+    owner_repo = bash_output("gh repo view --json nameWithOwner --jq .nameWithOwner").strip()
+    output = bash_output(
+        f"gh api repos/{owner_repo}/actions/artifacts --method GET -f name={artifact_name} -f per_page=10 --jq .artifacts"
+    )
+    artifacts: list[dict[str, Any]] = json.loads(output)
+    for artifact in artifacts:
+        if artifact["workflow_run"]["head_branch"] == branch:
+            return str(artifact["workflow_run"]["id"])
+    print(f"No artifact '{artifact_name}' found on branch '{branch}'")
+    raise SystemExit(1)
+
+
+def _download_artifact(run_id: str, artifact_name: str) -> Path:
+    cache_path = CACHE_ROOT / run_id / artifact_name
+    if cache_path.is_dir() and any(cache_path.iterdir()):
+        print(f"Using cached artifact: {cache_path}")
+        return cache_path
+    cache_path.mkdir(parents=True, exist_ok=True)
+    bash(f"gh run download {run_id} --name {artifact_name} --dir {cache_path}")
+    return cache_path
+
+
+def _find_linux_executable(artifact_path: Path) -> Path:
+    for item in artifact_path.iterdir():
+        if item.is_file() and (artifact_path / f"{item.stem}_Data").is_dir():
+            return item
+    print("No linux64 executable found in artifact (expected a file with a matching _Data/ directory)")
+    raise SystemExit(1)
+
+
+@app.command()
+def main(
+    project: Annotated[str, typer.Option("--project", "-p", help="Unity project name")],
+    target: Annotated[
+        str | None,
+        typer.Option("--target", "-t", help="Device target (android-mobile, magicleap, linux64)"),
+    ] = None,
+    branch: Annotated[
+        str | None,
+        typer.Option("--branch", "-b", help="Branch to find latest successful run (default: current git branch)"),
+    ] = None,
+    run: Annotated[int | None, typer.Option("--run", "-r", help="Specific GitHub Actions run ID")] = None,
+    serial: Annotated[str | None, typer.Option("--serial", "-s", help="adb device serial")] = None,
+    no_grant_permissions: Annotated[
+        bool,
+        typer.Option(
+            "--no-grant-permissions",
+            help=(
+                "Skip the post-install `adb shell pm grant` calls listed under `grant_permissions` "
+                "for the project in its unity-build.json manifest. Permissions are granted by default."
+            ),
+        ),
+    ] = False,
+    build_locally: Annotated[
+        bool,
+        typer.Option(
+            "--build",
+            "-B",
+            help=(
+                "Compile the project locally via `compile-unity` and install the produced APK / "
+                "linux executable. Skips the GitHub Actions artifact lookup; --branch / --run are ignored."
+            ),
+        ),
+    ] = False,
+) -> None:
+    projects = load_unity_projects()
+    project_name = _resolve_project(projects, project)
+    target_name = _resolve_target(projects[project_name], project_name, target)
+
+    if serial and target_name not in ADB_TARGETS:
+        print(f"Warning: --serial is ignored for target '{target_name}'")
+
+    if build_locally:
+        if branch or run:
+            print("Warning: --branch / --run are ignored when --build is set")
+        produced = build_unity_project(project_name, target_name)
+        apks = [path for path in produced if path.suffix == ".apk"]
+        executables = [path for path in produced if path.suffix == ".exe"]
+    else:
+        artifact_name = f"{project_name}-{target_name}"
+        resolved_branch = branch or _current_git_branch()
+        run_id = str(run) if run else _find_run_id(artifact_name, resolved_branch)
+        print(f"Run: {run_id}")
+        print(f"Artifact: {artifact_name}")
+        download_path = _download_artifact(run_id, artifact_name)
+        apks = sorted(download_path.rglob("*.apk"))
+        executables = [_find_linux_executable(download_path)] if target_name == "linux64" else []
+
+    if target_name in ADB_TARGETS:
+        if not apks:
+            print("No .apk found in install source")
+            raise SystemExit(1)
+
+        print(f"Installing: {apks[0].name}")
+        adb_prefix = f"adb -s {serial}" if serial else "adb"
+        package = projects[project_name].package
+        if package:
+            bash_check(f"{adb_prefix} uninstall {package}")
+        bash(f"{adb_prefix} install {apks[0]}")
+        permissions = projects[project_name].grant_permissions
+        if permissions and not no_grant_permissions:
+            if not package:
+                raise typer.BadParameter(
+                    f"{project_name} has grant_permissions but no 'package' field in unity-build.json"
+                )
+            for permission in permissions:
+                print(f"Granting {permission} to {package}")
+                bash(f"{adb_prefix} shell pm grant {package} {permission}")
+        print("Done.")
+    else:
+        if not executables:
+            print("No linux executable found in install source")
+            raise SystemExit(1)
+        executable = executables[0]
+        os.chmod(executable, executable.stat().st_mode | 0o755)
+        print(f"Launching: {executable.name}")
+        bash_handoff(str(executable))

unity_devkit/license.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from bashrun import bash
+from pydantic_settings import BaseSettings
+
+from .cache import restore, save
+from .license_restore import license_cache_tag
+from .setup import configure_git
+from .setup_oras import install_oras
+
+
+class Settings(BaseSettings):
+    cache_registry: str
+    github_workspace: str
+    unity_email: str
+    unity_password: str
+    unity_serial: str
+
+
+settings = Settings.model_validate({})
+activate_app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+
+def activate(oras_push: bool) -> None:
+    configure_git(settings.github_workspace)
+    install_oras()
+
+    license_directory = Path.home() / ".local" / "share" / "unity3d" / "Unity"
+    license_directory.mkdir(parents=True, exist_ok=True)
+
+    tag = license_cache_tag()
+    cache_hit = False
+    if oras_push:
+        cache_hit = restore(settings.cache_registry, "unity-license", tag, license_directory)
+
+    if not cache_hit:
+        bash(
+            f'unity-editor -batchmode -nographics -quit -serial "{settings.unity_serial}"'
+            f' -username "{settings.unity_email}" -password "{settings.unity_password}" -logFile /dev/stdout'
+        )
+
+    if oras_push and not cache_hit:
+        save(settings.cache_registry, "unity-license", tag, license_directory, ["Unity_lic.ulf"])
+
+
+@activate_app.command()
+def activate_main(oras_push: bool = typer.Option(False, help="Push activated ULF to ORAS cache")) -> None:
+    activate(oras_push)

unity_devkit/license_restore.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+from pydantic_settings import BaseSettings
+
+from .cache import restore
+
+
+# LICENSE_CACHE_TAG env pins the tag for a whole CI run; without it, each call
+# re-reads "now UTC" and a run straddling midnight save/restore-misses itself.
+def license_cache_tag() -> str:
+    override = os.environ.get("LICENSE_CACHE_TAG")
+    if override:
+        return override
+    return f"v-{datetime.now(UTC).strftime('%Y-%m-%d')}"
+
+
+class Settings(BaseSettings):
+    cache_registry: str
+
+
+tag_app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+
+@tag_app.command()
+def tag_main() -> None:
+    print(license_cache_tag())
+
+
+def restore_license() -> None:
+    settings = Settings.model_validate({})
+    license_directory = Path.home() / ".local" / "share" / "unity3d" / "Unity"
+    license_directory.mkdir(parents=True, exist_ok=True)
+    restore(settings.cache_registry, "unity-license", license_cache_tag(), license_directory, required=True)

unity_devkit/lock_unity.py

@@ -0,0 +1,28 @@
+from typing import Annotated
+
+import typer
+
+from .projects import load_unity_projects
+from .unity import prepare_unity_project, run_unity_batchmode
+
+app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+
+@app.command()
+def lock_unity(project: Annotated[str | None, typer.Option(help="Limit to a specific project.")] = None) -> None:
+    config = load_unity_projects()
+
+    if project is not None and project not in config:
+        raise typer.BadParameter(f"Unknown project '{project}'. Valid: {', '.join(config)}")
+
+    all_projects = {name: project_config.path for name, project_config in config.items()}
+    projects = {project: all_projects[project]} if project else all_projects
+
+    for name, project_path in projects.items():
+        lock_file = project_path / "Packages" / "packages-lock.json"
+        print(f"Resolving {name} ({lock_file})...")
+
+        prepare_unity_project(project_path)
+        run_unity_batchmode(project_path, strict_exit=False)
+
+        print("  Done")

unity_devkit/matrix.py

@@ -0,0 +1,31 @@
+import json
+from pathlib import Path
+
+from .projects import load_unity_projects
+from .unity import LICENSE_MODULE, PLATFORM_CONFIGS, UNITYCI_IMAGE_REVISION, read_editor_version
+
+
+def main() -> None:
+    projects = load_unity_projects()
+    matrix: list[dict[str, str]] = []
+    editor_versions: set[str] = set()
+
+    for name, project in projects.items():
+        if not project.builds:
+            continue
+        version = read_editor_version(project.path)
+        editor_versions.add(version)
+        for platform in project.builds:
+            module = PLATFORM_CONFIGS[platform]["module"]
+            matrix.append({
+                "project": str(project.path.relative_to(Path.cwd())),
+                "project-name": name,
+                "cache-key": name.lower(),
+                "platform": platform,
+                "module": module,
+                "editor-image": f"unityci/editor:{version}-{module}-{UNITYCI_IMAGE_REVISION}",
+            })
+
+    license_version = max(editor_versions)
+    print(f"matrix={json.dumps({'include': matrix})}")
+    print(f"license-image=unityci/editor:{license_version}-{LICENSE_MODULE}-{UNITYCI_IMAGE_REVISION}")