Puerts install-puerts-for-unity

Name: install-puerts-for-unity
Author: Tencent

install

source · Clone the upstream repo

git clone https://github.com/Tencent/puerts

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/Tencent/puerts "$T" && mkdir -p ~/.claude/skills && cp -r "$T/unity/skills/install-puerts-for-unity" ~/.claude/skills/tencent-puerts-install-puerts-for-unity && rm -rf "$T"

manifest: unity/skills/install-puerts-for-unity/SKILL.md

source content

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:

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.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:

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