| 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
⚠️ 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.v8com.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.corecom.tencent.puerts.luacom.tencent.puerts.nodejscom.tencent.puerts.pythoncom.tencent.puerts.quickjscom.tencent.puerts.v8
Steps:
- Go to
https://github.com/Tencent/puerts/releases/tag/Unity_v{VERSION}
- Download the required
.tar.gz file(s) (e.g., PuerTS_Core_3.0.2.tar.gz)
- Extract the archive — it will produce a directory (e.g.,
core/) containing a standard UPM package structure with a package.json
- Move the extracted directory into the Unity project's
Packages/ folder
- 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.webglcom.tencent.puerts.agentcom.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:
- Ask the user which version to install (if not already specified)
- Ask the user which packages they need (common combo:
com.tencent.puerts.core + com.tencent.puerts.v8 + com.tencent.puerts.agent)
- 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) |
- 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
- 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/
- 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
- 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.corecom.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.agentcom.tencent.puerts.webglcom.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.
