t1k:unity:base:asset-store
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: asset store, cloudflare access, mcp, registry, unitypackage, upm
How to invoke
Section titled “How to invoke”/t1k:unity:base:asset-storeThe1Studio Asset Store → UPM
Section titled “The1Studio Asset Store → UPM”Two ways to get a third-party Unity asset into a project without a human clicking through Unity’s Import dialog. Prefer the registry route; fall back to extraction only when the package genuinely is not on UPM.
1. The internal store
Section titled “1. The internal store”https://asset-store.the1studio.org/ — a dashboard that converts Asset Store
purchases into UPM packages and publishes them to https://upm.the1studio.org/.
It is behind Cloudflare Access (Zero Trust SSO). Plain curl gets a 302 to
the1studio.cloudflareaccess.com/login; there is no anonymous access.
Two ways in. Prefer the MCP — no extra binary, and Claude Code already holds the
credential. Fall back to cloudflared when the MCP server is not registered.
Preferred — discover and download via the unity-asset-store MCP
Section titled “Preferred — discover and download via the unity-asset-store MCP”The server is https://asset-store.the1studio.org/mcp. It is required in
.claude/t1k-config-unity.json, and installs automatically on t1k init and
t1k modules update. Verify with claude mcp get unity-asset-store → ✔ Connected.
⚠ t1k modules add does not register it. The entry carries
appliesWhen: {owningKit: unity, projectType: unity} — the leak guard that keeps
auto-installing servers out of unrelated sessions — and modules add evaluates
that predicate against an empty context, so the entry is skipped
unconditionally. It is not a non-TTY caveat, and it is not something this config
can override. If a module was just added and the server is missing, run
t1k modules update, or register it by hand:
~/.claude/skills/t1k-mcp-management/scripts/install-hosted-mcp.sh \ --name unity-asset-store --url https://asset-store.the1studio.org/mcp --scope localThe entry declares "authMode": "studio": the installer registers the server
with a headersHelper (core’s studio-auth-headers.cjs) so Claude Code sends a
studio bearer on every connection. There is no /mcp browser login in this mode;
the helper exchanges your gh auth token for a 1 h assertion and caches it under
~/.t1k/gh-auth/.
- Needs a GitHub login. Run
gh auth statusfirst. A machine with noghtoken cannot mint a bearer, and a studio registration there fails to connect (the session reminder then prints astudio-auth-headers.cjshint, not the/mcplogin). Fix it withgh auth login, then start a new session. - Existing registrations are not rewritten by
t1k modules update. A project that already has a plain localunity-asset-storeentry gets, at the next session start, anaction=configure ... reason="auth-mode-drift"line whosecmdis the installer above; run it from the project root and start a new session. The installer keeps keys it does not own and aheadersHelperthat is not ours. - Rollback per machine:
T1K_MCP_AUTH_MODE_UNITY_ASSET_STORE=accessbefore the installer returns the entry to a plain{type,url}registration (only our helper is removed). It only helps while Cloudflare Access fronts the host. Kit-wide rollback is"authMode": "access"int1k-config-unity.jsonplus a release.
Discover the asset
Section titled “Discover the asset”| Call | Returns |
|---|---|
search_packages(query=…, publisher=…, category=…, tracked=…) | catalog rows, ≤ 10 per call — page with offset |
get_package(packageId=…) or get_package(packageName="com.foo.bar") | one asset, with its download or publish info |
Read tracked before downloading. It decides the route:
tracked: true→ the asset publishes to UPM. It carriespublishedPackages[](an asset often maps to several) — install those from the registry instead (§ 2). Downloading a tracked asset’s.unitypackagere-creates the mixed-version problem § 4 exists to prevent.tracked: false→ not on UPM. It carries adownloadUrl. Use § 3.
publishedPackageVersion may read "N packages — see logs"; the real versions are
in publishedPackages[]. Never parse that field as a version.
Download it
Section titled “Download it”scripts/asset-store-fetch.py ships with this skill and does the whole job —
resolves the token, streams the file, verifies the payload, and can hand straight
off to the § 3 extractor:
# fetch onlyscripts/asset-store-fetch.py 68570 -o /tmp/amped.unitypackage
# fetch, then extract (dry-run; add --apply to write)scripts/asset-store-fetch.py 68570 --extract-project /path/to/UnityProject --applyIt authenticates with the OAuth token Claude Code already holds for the MCP server.
That token is scoped to the whole origin, not just /mcp, so it also
authenticates /api/packages/<id>/download — no cloudflared needed.
- Token secrecy: never log the token, never put it on argv, never quote it in a report. The full trap list (token expiry, response validation,
User-Agent, full-package downloads) is inreferences/download-traps.md.
Fallback — cloudflared + the REST API
Section titled “Fallback — cloudflared + the REST API”Use when the MCP server is not registered, or when a login must happen without an
MCP client present. It authenticates through Cloudflare Access, so it only works
while Access still fronts asset-store.the1studio.org. Note cloudflared is not installed by the kit.
Login, query endpoints, gotchas and the publishedChildren note: see references/cloudflared-fallback.md.
⚠ /api/publish/quick writes to shared studio infrastructure that other projects
resolve from. Never publish without explicit user approval.
2. Installing from the registry (preferred)
Section titled “2. Installing from the registry (preferred)”Credential form and enumeration
Section titled “Credential form and enumeration”Detect the credential form before building the header: a token= config takes Bearer, an _auth= config takes Basic. A wrong header returns authorization required to access package X for every name, so that string is never a “published” signal. Presence is proven only by a 200 on an authenticated request; absence only by enumerating /-/all with a plausible count. Detection script, response table and enumeration commands: references/registry-auth-and-enumeration.md.
Then in Packages/manifest.json, both of these are required:
"scopedRegistries": [{ "name": "TheOne", "url": "https://upm.the1studio.org/", "scopes": [ /* ... */ "com.opsive" ] }],"dependencies": { "com.opsive.behaviordesigner": "3.2.0" }A missing scopes entry reads exactly like a registry outage — PackMan reports
Package [x@ver] cannot be found even though it is published and you are authenticated.
Check the scope list before blaming the network.
3. Headless .unitypackage import (when UPM is not an option)
Section titled “3. Headless .unitypackage import (when UPM is not an option)”Some assets were never designed for UPM. Three unattended routes, no dialog.
<pkg> below is the file obtained in § 1 — scripts/asset-store-fetch.py produces
it directly, and can drive the extraction route for you via --extract-project.
| Route | Needs Unity? | Command |
|---|---|---|
| Extraction | No | scripts/unitypackage-extract.py <pkg> --project . --apply |
| Unity CLI | headless | unity_batch_gate_run "$UED" -batchmode -quit -projectPath <p> -importPackage <pkg> (after source .claude/scripts/unity-batch-gate.sh; $UED from unity_batch_gate_resolve) |
t1k unity eval | running editor | t1k unity eval 'AssetDatabase.ImportPackage("<path>", false)' — false = non-interactive |
scripts/unitypackage-extract.py ships with this skill and runs in place — in an
installed project that resolves to
.claude/skills/t1k-unity-base-asset-store/scripts/unitypackage-extract.py. It needs
Python 3 and nothing else.
Extraction is the most robust: it works with the Editor closed or broken, which is often precisely when you need it.
Why extraction is safe
Section titled “Why extraction is safe”The script writes asset.meta back verbatim, so GUIDs survive. Never write an extractor that regenerates .meta files. Rationale and the verified GUID check: references/extraction-and-overlay.md.
4. ⛔ The overlay-corruption trap
Section titled “4. ⛔ The overlay-corruption trap”Never import a newer version on top of an existing older copy. Asset Store imports overwrite the files they ship and leave everything else untouched. When a vendor reorganises between versions — moving source into a DLL, renaming folders — you get new DLLs sitting on stale source, and the same type declared twice:
Symptoms (CS1503 X-to-X, CS0506, CS0103/CS1061 for members that do exist) and the file-mtime check: references/extraction-and-overlay.md.
Recovery: move the whole package tree aside (mv, never rm — untracked vendor DLLs
are unrecoverable), then install one consistent version. Multi-package products must move
all siblings together, or you rebuild the corruption one layer down.
Prevention: prefer the registry route. A UPM package resolves into
Library/PackageCache/ as one atomic version, so overlays are structurally impossible.
5. Removing an embedded package can deadlock Package Manager
Section titled “5. Removing an embedded package can deadlock Package Manager”Before deleting or moving a package under Packages/, grep every package.json for a dependency on it (grep -rn '"com.vendor.name"' Packages/*/package.json Packages/*/*/package.json). A hard UPM dependency on an absent package halts Unity before its Editor command channel starts, so unblock surgically: references/embedded-package-removal.md.
Related
Section titled “Related”scripts/asset-store-fetch.py— obtains a.unitypackagefrom § 1 using the MCP’s OAuth token; verifies the payload and can hand off to the extractor.scripts/unitypackage-extract.py— the headless extractor this skill drives.rules/unity-forbidden-operations.md— neverAssets/Reimport All; an Editor-call timeout ≠ dead editor; a massCS0246cascade is usually a registry auth failure, not a code failure.t1k:unity:base:upm-auth— writes the~/.upmconfig.tomlcredentials § 2 reads.t1k:unity:base:addressables— asset loading once packages are installed.