Skip to content

feat: add optional Addressables management and content builds - #1486

Open
shaobin1991 wants to merge 1 commit into
CoplayDev:betafrom
shaobin1991:feat/addressables
Open

shaobin1991 wants to merge 1 commit into
CoplayDev:betafrom
shaobin1991:feat/addressables

Conversation

@shaobin1991

@shaobin1991 shaobin1991 commented Oct 22, 2026 •

Copy link
Copy Markdown

Description

Add manage_addressables so MCP clients can inspect Addressables configuration, manage asset registrations and run native content builds without writing custom Editor scripts. Include matching CLI commands and read-only settings/groups resources.

This implements the 22 actions in the Addressables roadmap, plus entry_list for paginated entry inspection and build_status for polling content operations.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Refactoring
  • Test update

Changes Made

  • Keep com.unity.addressables optional through API reflection. ping reports package, API and settings availability. Queries do not create settings; creation requires set_settings with initialize: true.
  • Add group, entry, label, profile and supported settings operations, with pagination, input validation and targeted saves. Respect read-only groups and entries; removing registrations preserves source assets. Support Undo/Redo for eligible mutations and refresh native caches after Undo.
  • Queue native content build, update and clean operations and expose their job status. Updates require a previous-build state file and reject changes that violate static-content restrictions. Jobs interrupted by domain reload report failure.
  • Add matching CLI commands, settings/groups resources, documentation and regression tests. Handle older public content-state path API signatures.

Compatibility / Package Source

  • Platform: Windows.
  • Package source: local file: reference to this branch's MCPForUnity; Git package-lock revision is not applicable.
  • Branch base: CoplayDev/unity-mcp:beta at ed4e205d31a545bac3686d5e19210e67959aeddd.

Addressables test results (ordinary and domain-reload runs are separate):

Unity Editor Addressables Ordinary passed / skipped Domain-reload passed
2021.3.45f2 1.22.3 69 / 1 3
2021.3.45f2 Not installed 3 / 67 3
2022.3.62f3c1 1.22.3 69 / 1 3
2022.3.62f3c1 Not installed 3 / 67 3
6000.0.47f1 2.10.3 69 / 1 3

All rows had zero failures. The skipped case in installed-package environments checks package absence; the 67 skips in no-package environments require Addressables.

Earlier package checks also passed 69 ordinary tests with 1 skipped for 1.21.21 on Unity 2022 and 2.2.2 / 3.0.0 on Unity 6. These preceded the final Undo initialization change and did not include its new domain-reload regression.

Testing/Screenshots/Recordings

  • Python non-live suite: cd Server && .venv/Scripts/python.exe -m pytest tests/ -q --ignore=tests/integration: 1369 passed, 3 skipped. The live integration directory was excluded.
  • Unity EditMode: Addressables results above. Regressions cover query side effects, validation, pagination, persistence, Undo/Redo, static-update restrictions, job failure/retry, domain reload and fixture restoration.
  • Package import/compile check, including without Addressables.
  • Unity PlayMode: not run; the feature performs Editor operations.
  • Generated documentation: Server/.venv/Scripts/python.exe tools/generate_docs_reference.py --check.

Real MCP calls exercised all 24 actions on the Unity 2022 / 1.22.3 and Unity 6 / 2.10.3 environments, including native full-build/update/clean operations. Separate checks verified that test fixtures restore host configuration and assets on success and failure.

tools/check-unity-versions.ps1 on an isolated official-project copy: 1 passed (2021.3.45f2), 0 failed, 3 skipped because the other exact configured Editors are not installed. The complete matrix and online CI remain unverified.

Complete upstream EditMode suite on 2021.3.45f2, without Addressables: 1483 passed, 1 failed, 153 skipped; the separate domain-reload group passed 7/7. The sole failure, ExecPathBatchShimTests.FindAllInPath_ReturnsEveryMatchInPathOrder, compares a Windows 8.3 temporary-directory path with its resolved long path. It reproduces on untouched upstream ed4e205d and is also reported in #1477.

Documentation Updates

  • Added the tool and resources to the generated reference.
  • Updated CLI documentation and examples.
  • Regenerated reference pages from the Python registries and manually reviewed the changes.

Related Issues

Implements the Addressables roadmap item linked above; no associated issue.

Additional Notes

Native builds run synchronously on the Editor main thread and cannot be cancelled; client timeouts do not cancel them. Failed builds may leave outputs. Only the latest content job is retained per Editor session. Group creation/removal explicitly report that Undo is unsupported.

The Unity CI workflow is unchanged; it does not install Addressables specifically for these tests, so package-dependent cases skip when the package is absent. Tuanjie and versions not listed above were not tested.

I use this project regularly and would be happy to follow up on Addressables-related bug reports and compatibility issues.

Summary by CodeRabbit

  • New Features
    • Added Addressables management through the CLI and tools, including queries and updates for settings, groups, entries, labels, and profiles.
    • Added content build, update, clean, and status operations with job tracking and validation.
    • Added resources for reading Addressables settings and groups.
  • Documentation
    • Added Addressables CLI examples and reference guides, including package requirements and operation details.

Expose configuration queries, group/entry/label/profile mutations, supported
settings updates, and native content build/update/clean jobs through MCP and CLI.
Keep Addressables optional and add two bounded read-only resources.

Support older public content-state path APIs and validate successful builds
return an existing state file. Isolate native import callbacks and restore
fixture assets, build-session state and queued callbacks after tests.

Add Python and Editor regression coverage, local multi-version validation,
and generated documentation. Use existing Unity test discovery without
adding optional-package CI jobs.

Register Undo callbacks at Editor domain load and cover Undo before first tool
use after reload. Clarify active-profile CLI defaults and resource prerequisites.
@coderabbitai

coderabbitai Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: cb5f02b7-6388-4983-89a1-b1b2fd561caf
📥 Commits

Reviewing files that changed from the base of the PR and between ed4e205 and bc03938.

📒 Files selected for processing: 27
  • MCPForUnity/Editor/Tools/AddressablesBuildJobs.cs
  • MCPForUnity/Editor/Tools/AddressablesBuildJobs.cs.meta
  • MCPForUnity/Editor/Tools/ManageAddressables.Mutations.cs
  • MCPForUnity/Editor/Tools/ManageAddressables.Mutations.cs.meta
  • MCPForUnity/Editor/Tools/ManageAddressables.cs
  • MCPForUnity/Editor/Tools/ManageAddressables.cs.meta
  • Server/src/cli/commands/addressables.py
  • Server/src/cli/main.py
  • Server/src/services/resources/addressables.py
  • Server/src/services/tools/manage_addressables.py
  • Server/tests/test_manage_addressables.py
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/AddressablesDomainReloadTests.cs
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/AddressablesDomainReloadTests.cs.meta
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests.Builds.cs
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests.Builds.cs.meta
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests.Mutations.cs
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests.Mutations.cs.meta
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests.cs
  • TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests.cs.meta
  • manifest.json
  • website/docs/guides/cli-examples.md
  • website/docs/guides/cli.md
  • website/docs/reference/cli.md
  • website/docs/reference/resources/index.md
  • website/docs/reference/tools/core/index.md
  • website/docs/reference/tools/core/manage_addressables.md
  • website/docs/reference/tools/index.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

This change adds Addressables management to Unity MCP. It includes Unity-side query, mutation, and build handling, server and CLI exposure, resource endpoints, EditMode and server tests, and documentation for the new tool and commands.

Changes: Addressables management

Layer / File(s) Summary
Query entry points and read surfaces
MCPForUnity/Editor/Tools/ManageAddressables.cs, Server/src/services/tools/manage_addressables.py, Server/src/services/resources/addressables.py, Server/src/cli/commands/addressables.py, Server/src/cli/main.py, manifest.json, TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests.cs, Server/tests/test_manage_addressables.py, website/docs/reference/...
Adds the manage_addressables tool entry point, reflection-based Addressables query handling, pagination and cursor validation, server tool and resource wiring, CLI read commands, manifest registration, and tests for query routing, package-state handling, pagination, and resource delegation.
Mutation validation and writes
MCPForUnity/Editor/Tools/ManageAddressables.Mutations.cs, Server/src/cli/commands/addressables.py, TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests*.cs, Server/tests/test_manage_addressables.py, website/docs/guides/cli*.md
Adds validated mutations for settings, groups, entries, labels, and profiles. The code records Undo, saves touched assets, preserves source assets on entry and group removal, and rejects invalid or read-only targets. CLI commands, mutation tests, and usage guides cover the same operations.
Build jobs and status polling
MCPForUnity/Editor/Tools/AddressablesBuildJobs.cs, MCPForUnity/Editor/Tools/ManageAddressables.cs, Server/src/cli/commands/addressables.py, TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/AddressablesDomainReloadTests.cs, TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests.Builds.cs, TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/ManageAddressablesTests.cs
Adds queued Addressables build, clean, and update jobs with persisted status in SessionState, busy-state checks, configuration revalidation before execution, and failure handling for domain reloads, invalid update state, and static-content restrictions. CLI build commands and Unity tests cover polling, lock release, retry behavior, and reload restoration.

Priority: ➖ Normal

Estimated code review effort: 5 (Critical) | ~100 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CLI as addressables CLI
  participant Tool as manage_addressables
  participant Unity as ManageAddressables
  participant Jobs as AddressablesBuildJobs
  participant API as Addressables API

  CLI->>Tool: build_content / build_update
  Tool->>Unity: action + parameters
  Unity->>Jobs: Start(...)
  Jobs->>API: run build operation
  API-->>Jobs: build result or error
  Jobs-->>Unity: stored job status
  CLI->>Tool: build_status(job_id)
  Tool->>Unity: status request
  Unity->>Jobs: Status(job_id)
  Jobs-->>Unity: pending / success / error
Loading

Possibly related issues

  • CoplayDev/unity-mcp#1482: This PR registers manage_addressables in the tool catalog and CLI surface, which matches the issue's note about added default tool-list size.

Suggested reviewers: scriptwonder

Merge Risk: ⚪ Minimal · up to bc039

This change adds optional Addressables management through new MCP tool actions, CLI commands and resources. No concrete merge-blocking issue remains after review, so the change looks ready to merge, subject to normal CI.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 19.12% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 136 functions across 12 files. (15 skippe… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly identifies the primary change: optional Addressables management and content-build support.
Description check Passed The description follows the repository template and provides the feature scope, change list, compatibility details, test results, documentation updates, related issues, and additional notes. It also c…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Description check

Explanation

The description follows the repository template and provides the feature scope, change list, compatibility details, test results, documentation updates, related issues, and additional notes. It also clearly reports unrun PlayMode tests and known upstream test limitations.

Full details: Docstring Coverage

Explanation

Docstring coverage is 19.12% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 136 functions across 12 files. (15 skipped: 15 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant