Skip to content

feat(scene): add shared reference image library - #889

Merged
wuzhiming merged 6 commits into
cocos:mainfrom
sekiroxxxx:codex/reference-image-cli
Aug 28, 2026
Merged

feat(scene): add shared reference image library#889
wuzhiming merged 6 commits into
cocos:mainfrom
sekiroxxxx:codex/reference-image-cli

Conversation

@sekiroxxxx

@sekiroxxxx sekiroxxxx commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add an editor-only reference image library for external PNG/JPG/JPEG files, with scene-specific optional bindings and 2D-only rendering.
  • Keep the project-local scene.referenceImage configuration as the only persisted data, while moving formal library mutations into a main-process single-writer store to prevent concurrent Scene Webviews from overwriting each other.
  • Synchronize Scene Webviews through versioned authority snapshots and the existing scene:invoke channel; preview interaction and image decoding remain local to the Scene runtime.
  • Add clear-binding support and make deletion remove all bindings to an image without automatically selecting a neighboring image.
  • Restore a visible reference image after a PinK restart by reconciling its ephemeral runtime objects through the existing ReferenceImage lifecycle. The service now uses Gizmo's restored 2D view state instead of the Camera controller's transient cold-start state.
  • Preserve an active parameter preview when another Scene changes an unrelated library entry. A preview is cancelled only when its current binding changes or is removed.
  • Publish reference-image state only after an actual authority or runtime state change, avoiding redundant refreshes from no-op reloads and repeated dimension events.
  • Document the ownership, synchronization, and bundle-registration boundaries in the new reference-image modules for review.

Validation

  • Targeted ReferenceImage service and store Jest tests (26 cases)
  • TypeScript build
  • Scene bundle rebuild
  • Manual PinK restart verification with an already-visible, bound reference image

Manual test plan

  1. Open two 2D scenes or prefabs. Add different reference images from each, then switch between them; both views should show the same library while retaining their own selected binding.
  2. Clear the binding in one scene. Its image should become unbound, while the library and the other scene binding remain intact.
  3. Delete an image bound by multiple scenes. All affected scenes should become unbound and no replacement image should be selected automatically.
  4. Adjust opacity, position, and scale using the reference image controls. Drag previews should be temporary; committing should persist after reopening the scene.
  5. While dragging parameters in one open Scene, add an unrelated image from another open Scene. Complete the original drag; its final parameter value should still be saved.
  6. With a bound reference image visible, close and reopen PinK, then open the same 2D scene. The image should reappear without toggling visibility. Switch to 3D and back to 2D; it should hide in 3D and reappear in 2D.

@wuzhiming
wuzhiming requested a review from knoxHuang August 27, 2026 11:52
@wuzhiming
wuzhiming merged commit 5e4c668 into cocos:main Aug 28, 2026
4 checks passed
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.

3 participants