install-puerts-for-unity

name	Install PuerTS for Unity
description	Guide for downloading and installing PuerTS UPM packages into a Unity project — covers version selection, package dependencies, download/extract and git URL installation methods, and Editor Assistant setup.

Install PuerTS for Unity

This skill guides you through downloading and installing PuerTS packages into a Unity project.

⚠️ Important: Always ask the user which PuerTS version they want to install if they haven't specified one. The version number follows the Core package's version (e.g., 3.0.2).

---

1. Release Page & Version

• The release download page URL pattern is:

  https://github.com/Tencent/puerts/releases/tag/Unity_v{VERSION}
  

  For example: https://github.com/Tencent/puerts/releases/tag/Unity_v3.0.2

⚠️ Important — Version Numbers Inside Archives: The version number in the release page URL (e.g., Unity_v3.0.2) is based on the Core package version. However, the version numbers inside each .tar.gz filename may differ — each package follows its own versioning cadence. You may need to download/parse the release page HTML to determine the exact filenames available.

---

2. Available Packages

Each release page may contain the following .tar.gz archives, each corresponding to a UPM package:

Archive File	UPM Package	Has Native Plugins	Always Available
PuerTS_Core_{ver}.tar.gz	com.tencent.puerts.core	✅ Yes	✅ Yes
PuerTS_Lua_{ver}.tar.gz	com.tencent.puerts.lua	✅ Yes	✅ Yes
PuerTS_Nodejs_{ver}.tar.gz	com.tencent.puerts.nodejs	✅ Yes	✅ Yes
PuerTS_Python_{ver}.tar.gz	com.tencent.puerts.python	✅ Yes	✅ Yes
PuerTS_Quickjs_{ver}.tar.gz	com.tencent.puerts.quickjs	✅ Yes	✅ Yes
PuerTS_V8_{ver}.tar.gz	com.tencent.puerts.v8	✅ Yes	✅ Yes
PuerTS_Webgl_{ver}.tar.gz	com.tencent.puerts.webgl	❌ No	✅ Yes
PuerTS_Agent_{ver}.tar.gz	com.tencent.puerts.agent	❌ No	❌ Not every release
PuerTS_MCP_{ver}.tar.gz	com.tencent.puerts.mcp	❌ No	❌ Not every release

Notable Package Features

• com.tencent.puerts.agent: Provides an Agent framework for building LLM agents, and also includes an Agent-based Editor Assistant for Unity.
• com.tencent.puerts.mcp: Provides an MCP (Model Context Protocol) framework, and also includes an MCP-based Editor Assistant for Unity.

Both the agent and mcp packages offer an Editor Assistant variant. See Section 5 for how to handle user requests like "install PuerTS Editor Assistant".

---

3. Package Dependencies

⚠️ Important: Packages have dependency relationships. When a user requests to install a package, you must ensure all of its dependencies are also installed.

Dependency Rules

• com.tencent.puerts.core is the foundational package — all other packages depend on it.
• com.tencent.puerts.agent depends on com.tencent.puerts.core + com.tencent.puerts.v8
• com.tencent.puerts.mcp depends on com.tencent.puerts.core + com.tencent.puerts.v8 + com.tencent.puerts.agent
• All backend packages (com.tencent.puerts.v8, com.tencent.puerts.lua, com.tencent.puerts.nodejs, com.tencent.puerts.python, com.tencent.puerts.quickjs, com.tencent.puerts.webgl) depend on com.tencent.puerts.core

Dependency Graph

com.tencent.puerts.core  (required by all)
  ├── com.tencent.puerts.v8
  │     ├── com.tencent.puerts.agent
  │     │     └── com.tencent.puerts.mcp
  │     └── com.tencent.puerts.mcp
  ├── com.tencent.puerts.nodejs
  ├── com.tencent.puerts.lua
  ├── com.tencent.puerts.python
  ├── com.tencent.puerts.quickjs
  └── com.tencent.puerts.webgl

Examples of Automatic Dependency Resolution

User requests to install	Must also install
agent	core, v8
mcp	core, v8, agent
mcp + agent	core, v8
v8	core
lua	core

---

4. Installation Methods

4.1 Download & Extract Method (Required for packages with native plugins)

The following packages contain compiled native binary plugins and must be installed by downloading from the release page:

• com.tencent.puerts.core
• com.tencent.puerts.lua
• com.tencent.puerts.nodejs
• com.tencent.puerts.python
• com.tencent.puerts.quickjs
• com.tencent.puerts.v8

Steps:

1. Go to https://github.com/Tencent/puerts/releases/tag/Unity_v{VERSION}
2. Download the required .tar.gz file(s) (e.g., PuerTS_Core_3.0.2.tar.gz)
3. Extract the archive — it will produce a directory (e.g., core/) containing a standard UPM package structure with a package.json
4. Move the extracted directory into the Unity project's Packages/ folder
5. Verify installation by checking Packages/manifest.json

4.2 Git URL Method (Available for packages without native plugins)

The following packages can also be installed via Unity's Add package from git URL method:

• com.tencent.puerts.webgl
• com.tencent.puerts.agent
• com.tencent.puerts.mcp

When the package exists on the release page

You can either:

• Use the Download & Extract method (Section 4.1), OR
• Use a versioned git URL in Unity Package Manager:

  https://github.com/Tencent/puerts.git?path=unity/upms/{package_name}#Unity_v{VERSION}
  

  Examples:

  https://github.com/Tencent/puerts.git?path=unity/upms/agent#Unity_v3.0.2
  https://github.com/Tencent/puerts.git?path=unity/upms/mcp#Unity_v3.0.2
  https://github.com/Tencent/puerts.git?path=unity/upms/webgl#Unity_v3.0.2
  

When the package does NOT exist on the release page

Since com.tencent.puerts.agent and com.tencent.puerts.mcp are newer packages and not available in every release, if they are missing from the download page, install them using an unversioned git URL:

https://github.com/Tencent/puerts.git?path=unity/upms/agent
https://github.com/Tencent/puerts.git?path=unity/upms/mcp

How to add a git URL in Unity

Add the URL to the project's Packages/manifest.json under "dependencies", for example:

{
  "dependencies": {
    "com.tencent.puerts.agent": "https://github.com/Tencent/puerts.git?path=unity/upms/agent#Unity_v3.0.2"
  }
}

Or use the Unity Editor: Window → Package Manager → + → Add package from git URL...

---

5. Installation Workflow

When a user asks to install PuerTS, follow this workflow:

1. Ask the user which version to install (if not already specified)
2. Ask the user which packages they need (common combo: com.tencent.puerts.core + com.tencent.puerts.v8 + com.tencent.puerts.agent)
3. Resolve dependencies — based on the dependency rules in Section 3, automatically include all required dependency packages. Inform the user about the additional packages that will be installed.

Editor Assistant Installation Rules

If the user requests to "install PuerTS Editor Assistant" (or similar phrasing like "安装 puerts 编辑器助手"), apply the following rules:

User Request	Packages to Install
"Install PuerTS Editor Assistant" (no specific version mentioned)	Both com.tencent.puerts.agent and com.tencent.puerts.mcp (plus all their dependencies: core, v8)
"Install PuerTS Editor Assistant — Agent version"	Only com.tencent.puerts.agent (plus its dependencies: core, v8)
"Install PuerTS Editor Assistant — MCP version"	Only com.tencent.puerts.mcp (plus its dependencies: core, v8, agent)

4. Check the release page https://github.com/Tencent/puerts/releases/tag/Unity_v{VERSION} to see which archives are available — note that actual filenames in the .tar.gz may have different version numbers than the release tag
5. For packages with native plugins (com.tencent.puerts.core, com.tencent.puerts.v8, com.tencent.puerts.lua, com.tencent.puerts.nodejs, com.tencent.puerts.python, com.tencent.puerts.quickjs): guide the user to download and extract into Packages/
6. For packages without native plugins (com.tencent.puerts.webgl, com.tencent.puerts.agent, com.tencent.puerts.mcp):
   • If the .tar.gz exists on the release page → offer both download or git URL options
   • If the .tar.gz does NOT exist on the release page → use the unversioned git URL
7. Verify the installation by checking Packages/manifest.json for the expected package entries

---

6. Verifying Installation

After installation, the following package IDs should appear in Packages/manifest.json (depending on which packages were installed):

• com.tencent.puerts.core
• com.tencent.puerts.v8 (or other backend: com.tencent.puerts.lua, com.tencent.puerts.nodejs, com.tencent.puerts.python, com.tencent.puerts.quickjs)
• com.tencent.puerts.agent
• com.tencent.puerts.webgl
• com.tencent.puerts.mcp

---

7. Known Issues & Troubleshooting (Windows)

7.1 curl on Windows is an alias for Invoke-WebRequest — use different flags

On Windows PowerShell, curl is an alias for Invoke-WebRequest and does not accept standard Unix curl flags like -L, --max-time, -o. Use the native PowerShell syntax instead:

# ❌ Wrong — Unix curl flags don't work in PowerShell
curl -L --max-time 30 -o output.html https://...

# ✅ Correct — use Invoke-WebRequest with PowerShell parameters
Invoke-WebRequest -Uri "https://..." -OutFile "output.html" -UseBasicParsing

7.2 GitHub API rate limit when unauthenticated

Calling https://api.github.com/repos/Tencent/puerts/releases/tags/Unity_v{VERSION} without authentication will quickly hit GitHub's rate limit (especially on shared IPs).

Workaround: Instead of the API, fetch the expanded assets HTML fragment directly — it contains all download links and is not rate-limited:

Invoke-WebRequest -Uri "https://github.com/Tencent/puerts/releases/expanded_assets/Unity_v{VERSION}" `
    -OutFile "assets.html" -UseBasicParsing

# Then extract download links with regex:
$content = Get-Content "assets.html" -Raw
$matches = [regex]::Matches($content, 'href="(/Tencent/puerts/releases/download[^"]*)"')
$matches | ForEach-Object { $_.Groups[1].Value }

This returns the exact filenames (e.g., PuerTS_Core_3.0.2.tar.gz) without consuming API quota.

7.3 Invoke-WebRequest times out on large files

Invoke-WebRequest can time out when downloading large packages (e.g., PuerTS_V8 ~74 MB, PuerTS_Nodejs ~169 MB).

Workaround: Use Start-BitsTransfer instead — it is more reliable for large files and does not time out:

Start-BitsTransfer `
    -Source "https://github.com/Tencent/puerts/releases/download/Unity_v3.0.2/PuerTS_V8_3.0.2.tar.gz" `
    -Destination "C:\path\to\output\PuerTS_V8_3.0.2.tar.gz"

7.4 Release page HTML does not contain download links (JavaScript-rendered)

The main release page (/releases/tag/Unity_v{VERSION}) renders asset links via JavaScript — the raw HTML fetched by Invoke-WebRequest will not contain any releases/download links.

Solution: Use the expanded_assets endpoint instead (see Section 7.2 above), which returns a static HTML fragment with all asset links.

7.5 manifest.json must use file: prefix for local packages

When packages are extracted into the Packages/ directory, manifest.json must reference them with the file: prefix pointing to the subdirectory name:

{
  "dependencies": {
    "com.tencent.puerts.core":   "file:core",
    "com.tencent.puerts.v8":     "file:v8",
    "com.tencent.puerts.nodejs": "file:nodejs",
    "com.tencent.puerts.agent":  "file:agent",
    "com.tencent.puerts.mcp":    "file:mcp"
  }
}

Unity will automatically resolve these local paths when the project is opened.