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.
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).
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 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.
.tar.gzEach 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 |
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
agentandmcppackages offer an Editor Assistant variant. See Section 5 for how to handle user requests like "install PuerTS Editor Assistant".
⚠️ Important: Packages have dependency relationships. When a user requests to install a package, you must ensure all of its dependencies are also installed.
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.agentcom.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.corecom.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
| User requests to install | Must also install |
|---|---|
agent | core, v8 |
mcp | core, v8, agent |
mcp + agent | core, v8 |
v8 | core |
lua | core |
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.v8Steps:
https://github.com/Tencent/puerts/releases/tag/Unity_v{VERSION}.tar.gz file(s) (e.g., PuerTS_Core_3.0.2.tar.gz)core/) containing a standard UPM package structure with a package.jsonPackages/ folderPackages/manifest.jsonThe following packages can also be installed via Unity's Add package from git URL method:
com.tencent.puerts.webglcom.tencent.puerts.agentcom.tencent.puerts.mcpYou can either:
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
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
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...
When a user asks to install PuerTS, follow this workflow:
com.tencent.puerts.core + com.tencent.puerts.v8 + com.tencent.puerts.agent)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) |
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 tagcom.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/com.tencent.puerts.webgl, com.tencent.puerts.agent, com.tencent.puerts.mcp):
.tar.gz exists on the release page → offer both download or git URL options.tar.gz does NOT exist on the release page → use the unversioned git URLPackages/manifest.json for the expected package entriesAfter 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.mcpcurl on Windows is an alias for Invoke-WebRequest — use different flagsOn 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
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.
Invoke-WebRequest times out on large filesInvoke-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"
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.
manifest.json must use file: prefix for local packagesWhen 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.