From 172f8b87e46f3be2a5c50ba8dd54cba08c77410a Mon Sep 17 00:00:00 2001 From: Eric Sun <141227631+EricSun0218@users.noreply.github.com> Date: Fri, 21 Aug 2026 20:40:02 +0800 Subject: [PATCH] feat(unity): publish through GitHub UPM and OpenUPM --- .github/workflows/publish-upm.yml | 96 +++++++++++++++++++ README.md | 8 ++ README.zh-CN.md | 8 ++ docs/engine-integration.md | 14 +++ .../com.opengameagent.runtime/CHANGELOG.md | 1 + .../com.opengameagent.runtime/README.md | 23 ++++- .../com.opengameagent.runtime/package.json | 5 + engines/unity/build-package.ps1 | 2 +- engines/unity/test-package.ps1 | 4 +- 9 files changed, 155 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/publish-upm.yml diff --git a/.github/workflows/publish-upm.yml b/.github/workflows/publish-upm.yml new file mode 100644 index 0000000..35ded90 --- /dev/null +++ b/.github/workflows/publish-upm.yml @@ -0,0 +1,96 @@ +name: Publish Unity UPM + +on: + workflow_dispatch: + inputs: + version: + description: Semantic version to publish from the Unity package manifest + required: true + default: 0.3.0-alpha.3 + +permissions: + contents: write + +concurrency: + group: publish-upm-${{ inputs.version }} + cancel-in-progress: false + +jobs: + publish: + if: ${{ github.ref == 'refs/heads/main' }} + runs-on: ubuntu-latest + env: + PACKAGE_VERSION: ${{ inputs.version }} + PACKAGE_NAME: com.opengameagent.runtime + UPM_TAG_PREFIX: upm/ + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + with: + fetch-depth: 0 + - uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6 + env: + DOTNET_INSTALL_DIR: ${{ runner.temp }}/.dotnet + with: + global-json-file: global.json + - name: Validate version and build package + shell: pwsh + run: | + if ($env:PACKAGE_VERSION -notmatch '^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$') { + throw 'Version must be semantic.' + } + + $sourceManifest = Get-Content -LiteralPath 'engines/unity/Packages/com.opengameagent.runtime/package.json' -Raw | ConvertFrom-Json + if ($sourceManifest.name -ne $env:PACKAGE_NAME -or $sourceManifest.version -ne $env:PACKAGE_VERSION) { + throw 'The requested version must match the Unity package manifest on main.' + } + + $stubs = Join-Path $env:RUNNER_TEMP 'unity-stubs' + dotnet restore tests/OpenGameAgent.Unity.Stubs/OpenGameAgent.Unity.Stubs.csproj --locked-mode + dotnet build tests/OpenGameAgent.Unity.Stubs/OpenGameAgent.Unity.Stubs.csproj -c Release --no-restore -o $stubs + ./engines/unity/test-package.ps1 -UnityManagedDir $stubs -Version $env:PACKAGE_VERSION + + $builtPackage = Resolve-Path 'artifacts/unity/com.opengameagent.runtime' + $stagedPackage = Join-Path $env:RUNNER_TEMP 'opengameagent-upm-package' + New-Item -ItemType Directory -Path $stagedPackage | Out-Null + Copy-Item -Path (Join-Path $builtPackage '*') -Destination $stagedPackage -Recurse -Force + "UPM_PACKAGE_PATH=$stagedPackage" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8 + - name: Publish immutable UPM branch and tag + shell: bash + run: | + set -euo pipefail + + tag="${UPM_TAG_PREFIX}${PACKAGE_VERSION}" + if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null 2>&1; then + echo "::error::Immutable UPM tag ${tag} already exists." + exit 1 + fi + + package_copy="${RUNNER_TEMP}/opengameagent-upm-package-copy" + mkdir -p "${package_copy}" + cp -a "${UPM_PACKAGE_PATH}/." "${package_copy}/" + + if git ls-remote --exit-code --heads origin refs/heads/upm >/dev/null 2>&1; then + git fetch origin refs/heads/upm:refs/remotes/origin/upm + git switch --create upm --track origin/upm + git rm -r --ignore-unmatch . + else + git switch --orphan upm + git rm -r --ignore-unmatch . + fi + + find . -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf -- {} + + cp -a "${package_copy}/." . + + manifest_name="$(jq -r .name package.json)" + manifest_version="$(jq -r .version package.json)" + if [[ "${manifest_name}" != "${PACKAGE_NAME}" || "${manifest_version}" != "${PACKAGE_VERSION}" ]]; then + echo "::error::Generated package manifest does not match the requested package." + exit 1 + fi + + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + git add -- . + git commit -m "chore(upm): publish ${PACKAGE_NAME} ${PACKAGE_VERSION}" + git tag -a "${tag}" -m "${PACKAGE_NAME} ${PACKAGE_VERSION}" + git push origin HEAD:refs/heads/upm "refs/tags/${tag}" diff --git a/README.md b/README.md index 874203a..6d8c001 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,14 @@ The kernel boundary is intentionally small and designed to stabilize early. New Download versioned package artifacts, Godot and Unity archives, or the portable server from the [Releases](https://github.com/EricSun0218/OpenGameAgent/releases) page. For active development against a source checkout, reference only the projects your game needs: +Unity 6 projects can install the complete `0.3.0-alpha.3` package directly from its immutable GitHub UPM tag: + +```text +https://github.com/EricSun0218/OpenGameAgent.git#upm/0.3.0-alpha.3 +``` + +After the package is indexed by OpenUPM, it can also be installed with `openupm add com.opengameagent.runtime@0.3.0-alpha.3`. The generated `upm` branch contains the tested binaries; the Unity source directory on `main` is not itself a distributable package. + ```xml diff --git a/README.zh-CN.md b/README.zh-CN.md index 6648ae9..63fed00 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -54,6 +54,14 @@ OpenGameAgent 不绑定任何模型或 Provider。角色通过开发者定义的 可以从 [Releases](https://github.com/EricSun0218/OpenGameAgent/releases) 下载版本化包文件、Godot/Unity 压缩包或可移植服务端。若游戏需要持续跟随本地最新源码，请只引用实际使用的项目： +Unity 6 项目可以直接通过不可变的 GitHub UPM tag 安装完整的 `0.3.0-alpha.3` 包： + +```text +https://github.com/EricSun0218/OpenGameAgent.git#upm/0.3.0-alpha.3 +``` + +OpenUPM 完成索引后，也可以执行 `openupm add com.opengameagent.runtime@0.3.0-alpha.3`。自动生成的 `upm` 分支包含经过测试的完整二进制；`main` 上的 Unity 源码目录本身不是可分发包。 + ```xml diff --git a/docs/engine-integration.md b/docs/engine-integration.md index 164b72c..f8da974 100644 --- a/docs/engine-integration.md +++ b/docs/engine-integration.md @@ -43,6 +43,20 @@ Verify package structure and a real editor import/scene run: ## Unity 6 +Install the immutable package from **Window > Package Manager > + > Add package from git URL**: + +```text +https://github.com/EricSun0218/OpenGameAgent.git#upm/0.3.0-alpha.3 +``` + +OpenUPM users can install the same package content with: + +```bash +openupm add com.opengameagent.runtime@0.3.0-alpha.3 +``` + +Release tags under `upm/` point at a generated package-only branch. This avoids checking generated assemblies into `main` while keeping Git installs reproducible. The `engines/unity/Packages/com.opengameagent.runtime` directory on `main` contains package source and metadata, not the complete installable package. + Build the distributable UPM directory: ```powershell diff --git a/engines/unity/Packages/com.opengameagent.runtime/CHANGELOG.md b/engines/unity/Packages/com.opengameagent.runtime/CHANGELOG.md index 7dfe0f3..ee602ea 100644 --- a/engines/unity/Packages/com.opengameagent.runtime/CHANGELOG.md +++ b/engines/unity/Packages/com.opengameagent.runtime/CHANGELOG.md @@ -5,6 +5,7 @@ - Add a deterministic no-key sample and store-ready package metadata. - Add complete third-party notices for bundled runtime dependencies. - Validate the sample in a real Unity 6 editor smoke test. +- Publish complete immutable packages through GitHub UPM tags and OpenUPM. ## 0.3.0-alpha.2 diff --git a/engines/unity/Packages/com.opengameagent.runtime/README.md b/engines/unity/Packages/com.opengameagent.runtime/README.md index 9f9a70a..c1d6053 100644 --- a/engines/unity/Packages/com.opengameagent.runtime/README.md +++ b/engines/unity/Packages/com.opengameagent.runtime/README.md @@ -2,10 +2,25 @@ Unity 6 adapter for the OpenGameAgent runtime. -1. Build the local UPM package with `engines/unity/build-package.ps1`. -2. Add the generated directory through Unity Package Manager. -3. Add `OpenGameAgentBehaviour` to a persistent GameObject. -4. Call `Configure(runtime)` for in-process execution or `ConfigureRemote(client)` for a .NET service. +## Install + +Install the immutable GitHub UPM release from **Window > Package Manager > + > Add package from git URL**: + +```text +https://github.com/EricSun0218/OpenGameAgent.git#upm/0.3.0-alpha.3 +``` + +Or install from OpenUPM after the package is listed: + +```bash +openupm add com.opengameagent.runtime@0.3.0-alpha.3 +``` + +The `upm/*` tags point to a generated package-only branch containing the tested adapter, runtime/client assemblies, notices, and sample. Do not install the package source subdirectory from `main`; generated DLLs intentionally do not live there. + +For local development, build the package with `engines/unity/build-package.ps1` and add the generated `artifacts/unity/com.opengameagent.runtime` directory through Unity Package Manager. + +Add `OpenGameAgentBehaviour` to a persistent GameObject and call `Configure(runtime)` for in-process execution or `ConfigureRemote(client)` for a .NET service. For a no-key first run, import **Minimal Local Agent** from Package Manager > OpenGameAgent > Samples, add `OpenGameAgentQuickstart` to a GameObject, and enter Play Mode. The sample uses a deterministic provider so it never contacts an external service. diff --git a/engines/unity/Packages/com.opengameagent.runtime/package.json b/engines/unity/Packages/com.opengameagent.runtime/package.json index 8d13aca..5832154 100644 --- a/engines/unity/Packages/com.opengameagent.runtime/package.json +++ b/engines/unity/Packages/com.opengameagent.runtime/package.json @@ -8,6 +8,11 @@ "documentationUrl": "https://github.com/EricSun0218/OpenGameAgent/blob/main/docs/engine-integration.md", "changelogUrl": "https://github.com/EricSun0218/OpenGameAgent/blob/main/engines/unity/Packages/com.opengameagent.runtime/CHANGELOG.md", "licensesUrl": "https://github.com/EricSun0218/OpenGameAgent/blob/main/LICENSE", + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/EricSun0218/OpenGameAgent.git" + }, "keywords": [ "ai", "agent", diff --git a/engines/unity/build-package.ps1 b/engines/unity/build-package.ps1 index df44df4..648749d 100644 --- a/engines/unity/build-package.ps1 +++ b/engines/unity/build-package.ps1 @@ -2,7 +2,7 @@ param( [Parameter(Mandatory = $true)] [string] $UnityManagedDir, - [string] $Version = '0.3.0-alpha.2', + [string] $Version = '0.3.0-alpha.3', [string] $OutputDirectory ) diff --git a/engines/unity/test-package.ps1 b/engines/unity/test-package.ps1 index 898e6e3..3201ae5 100644 --- a/engines/unity/test-package.ps1 +++ b/engines/unity/test-package.ps1 @@ -2,7 +2,7 @@ param( [Parameter(Mandatory = $true)] [string] $UnityManagedDir, - [string] $Version = '0.3.0-alpha.2' + [string] $Version = '0.3.0-alpha.3' ) Set-StrictMode -Version Latest @@ -56,6 +56,8 @@ if ($unexpected) { $manifest = Get-Content -LiteralPath (Join-Path $packagePath 'package.json') -Raw | ConvertFrom-Json if ($manifest.name -ne 'com.opengameagent.runtime' -or $manifest.version -ne $Version -or + $manifest.license -ne 'MIT' -or + $manifest.repository.url -ne 'https://github.com/EricSun0218/OpenGameAgent.git' -or $manifest.unity -ne '6000.0' -or $manifest.unityRelease -ne '0f1' -or $manifest.samples.Count -ne 1) {