Publish Unity package through GitHub UPM and OpenUPM

.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}"

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
 <ItemGroup>
   <ProjectReference Include="path/to/OpenGameAgent/src/OpenGameAgent/OpenGameAgent.csproj" />

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
 <ItemGroup>
   <ProjectReference Include="path/to/OpenGameAgent/src/OpenGameAgent/OpenGameAgent.csproj" />

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

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
 

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.
 

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",

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
 )
 

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) {