Unity Edit Tools

Unity Edit Tools is a portable, prefab-focused Codex and VS Code extension for raster-backed Unity UI. It provides whole-image generation guidance, exact layer separation and prefab application, optional text extraction, capture, and visual validation without importing game-specific architecture or asset conventions.

The VS Code extension depends on gangdol.unity-tools-base. In a trusted, filesystem-backed Unity workspace it asks Base to transactionally install or update the Editor-only com.gangdol.unity-tools.edit package and the narrow .agents/skills/unity-edit-tools project skill. Installation reconciliation is coalesced and detached from custom-editor creation. An accepted full-install receipt skips installer and prefab-association reconciliation entirely on activation, open, restore, preview, and Phase 1/2 use. An exact, strictly shaped host-global readiness receipt is bound to the canonical project, Edit component and host-extension versions, an immutable build identity, the exact capability set, and completion of the scoped prefab-default adaptation in the exact VS Code workspace composition. The extension writes full only after the association and its ownership ledger have completed and the global-state write itself has succeeded. Valid receipts are deduplicated by canonical project without a project-count eviction limit. It never treats an unawaited or rejected state write as full success. A missing receipt (for example after a profile reset) also does not block an already-installed project: the editor opens through the same normal prefab-preview route while Base reconciles in the background. An actually missing provider, a transient domain reload, or a missing route affects only preview; the normal bounded preview polling retries without entering the installer.

Base installation reconciliation runs only for first setup, an exact version/build identity change, a prior component partial state, or explicit repair. A workspace composition change retries only the safe prefab-default association adaptation and never re-enters Base installation for the unchanged full component. Normal preview responses—including 200, 204, transient 503, and missing-route 404 results—perform no installer, status, hash, legacy, skill, or capability call and never invalidate a full receipt. Ordinary capture errors such as Unity compilation, a missing target prefab, or a malformed request likewise do not trigger installation repair. Explicit Base repair is the recovery authority when the installed package itself needs repair.

Normal first setup and updates use Base's fast structural transaction and may run while Unity is open; explicit Repair retains deep Unity validation. If detached setup fails, Edit reports the exact reason and offers Retry Setup, which reruns the same reconciliation without requiring a window reload. A deep operation that is waiting for Unity to close says so and keeps its automatic retry visible.

Preview bytes use Base's authenticated GET /v1/base/prefab-preview route; Edit does not open a second listener or install an alternate transport. Bridge identity rotation arrives through Base's shared descriptor watcher when that optional runtime helper is available. The normal preview path reuses the cached identity without project filesystem polling or descriptor hash, ACL, installation-state, skill, legacy, or capability revalidation. If the watcher is unavailable, the same cache remains hot and only a real GET authentication/transport failure causes one bounded descriptor refresh. Automatic project discovery is likewise optional; opening the custom editor still resolves its project directly. An exact full receipt covering the current workspace skips automatic Base discovery too. A new or changed workspace composition falls through to discovery and retries only the missing association adaptation when the component is already full; it does not re-enter the installer.

The custom editor is always an opt-in Open With candidate, so a healthy existing runtime can self-prove without installer latency. It becomes the default only after validated preview readiness. The portable extension can then add one workspace-scoped, absolute file-URI glob for only that resolved project. Literal glob metacharacters in its path are escaped, so nested, multi-root, and filesystem-alias workspaces do not broaden the match. It preserves every other association and never writes the global setting. An existing explicit *.prefab, **/*.prefab, or exact-project choice for another editor wins; Edit remains available through Open With and does not disable any validated capability. A POSIX name whose file URI contains a literal backslash cannot be represented safely as a VS Code glob and remains Open With-only; ordinary Windows paths use slash-separated file-URI paths. If this adaptation cannot be completed safely, readiness is durably recorded as partial with only default prefab opening affected. Preview through Open With, Phase 1 generation, and Phase 2 application remain available.

Immediately before creating an association, Edit persists a separate pending intent in VS Code's workspace state. A successful configuration write promotes that intent to ownership. On restart, an exact pending mapping is promoted only after preview validation succeeds; first-time, affirmatively unavailable preview removes only that exact still-Edit-owned mapping, while an absent or user-changed mapping merely clears the ledger. A transient detached installer/status failure never removes or rewrites a remembered successful association and never changes or closes a live preview/Phase 1/ Phase 2 session. An accepted partial that affirmatively disables prefab preview closes only affected preview sessions; it does not disable Phase 1 or Phase 2. Ordinary deactivation intentionally keeps a usable association. After uninstall, any unreconciled mapping names an unregistered editor and is inert because VS Code provides no hook that can enumerate and rewrite every previously opened workspace. Base's installer remains the sole legacy-protection authority. Normal preview, generation, application, and validation never scan legacy markers.

Base's exact legacy-protection detector remains inside the trusted installer/readiness boundary. Only the coherent original identity—both exact legacy protocol/bridge declarations and the exact original tool manifest identity together—keeps the portable suite dormant and preserves every legacy file and state record. Lone, path-only, copied, malformed, symlinked, or ambiguous markers do not block adaptation.

Codex generation and application sessions run against the selected Unity project so they can inspect and adapt to its actual assets, prefab hierarchy, packages, and local conventions. Extension-launched Phase 1 and Phase 2 prompts embed immutable focused instructions loaded from the trusted VSIX; they never read the mutable project skill. The separately installed project skill remains available for agent discovery and setup and does not govern extension-launched operations. It imports no unrelated Genius gameplay or architecture guidance.

When unityEditTools.savePrefabEditChats is enabled, Codex generation can resume the active image-edit thread recorded in that prefab's bounded .prefabreplicate history. Setting it to false starts an ephemeral thread and stores no Codex thread ID.

An interactive Phase 1 run has no separate output-canvas option or canvas-choice step. The image-editing model owns the canvas decision and chooses the final width and height after judging all available evidence together: standalone and per-region prompts, live follow-ups, fixed-area selections and what their prompts mean, dragged source-to-target geometry, the source image, visual references, the complete composition and design meaning, and any target dimensions the user supplied. No keyword or geometry rule decides the result. A fixed-area prompt or the composition alone can imply an aspect change, while an outward or edge-touching drag can still be an object-only change.

Canvas size is judged independently: when a size change seems intended, at least one final pixel dimension must change; otherwise both dimensions stay exactly equal to the source. A proportional size change can preserve aspect, so changing size never decides the aspect rule.

If an aspect change seems intended from the complete context, the final canvas aspect must change, even without literal canvas or aspect-ratio wording. If it does not seem intended, the final canvas must preserve the source aspect. The model declares that decision and its chosen dimensions. Extension code only validates the declaration, exact PNG dimensions, the stated preserve/change relationship, and safety limits; it never parses intent or replaces the model-owned canvas with source, selection, or geometry-guide dimensions. Geometry-guide bounds are non-authoritative and exist only to communicate spatial evidence.

Canvas dimensions and aspect, composition and object geometry, and raster resampling remain separate decisions. Uniform same-factor resampling is allowed for an appropriate aspect- preserving size change or final dimension normalization, but unequal-axis mechanical resampling of rendered pixels is never used to change aspect. A generated result that merely looks like that operation is equally invalid. Intentional object aspect-ratio, shape, or internal-layout proportion changes are generated, redrawn, or recomposed so spacing, strokes, corner radii, glyphs, textures, and layout look native to the new geometry. An intentional crop may change canvas framing when edge loss is appropriate, and intentional padding may change canvas extent when added canvas or preserved composition is genuinely intended or required. Neither operation may evade a required canvas, object, layout, or composition change. The host never silently selects a candidate or fit and never force-fits a mismatch. A fallback may normalize only to the model-declared canvas, using same-aspect shared scaling or an explicit model-declared crop/pad that is valid for the semantically final composition; it can never derive a target from the source or a guide, revise the decision, or restore the former aspect after an intended change. The exact final canvas is the artifact reviewed and offered for Phase 2.

Adjacent .prefabreplicate files are user-created image-history documents (up to the documented revision and byte limits). Installation never creates them. The portable format uses its own identifier and does not claim, migrate, or rewrite a legacy Genius sidecar.

Phase 3 text extraction is packaged for explicit future use but remains off by default. Prefab preview and visual validation are required for an aggregate successful Edit installation. A project-skill-domain conflict does not affect extension-launched generation or application, and unavailable visual validation affects only the ability to claim that validation completed. The uGUI, TMP, and URP assemblies are conditional capture adapters, not separately exposed extension features. They load opportunistically when their project packages are present, while their absence does not turn an otherwise complete installation into a false partial. The required graphical smoke test validates the active preview and visual-validation path, including every adapter that applies in that project. A newer candidate that would reduce the validated core capability set is rolled back so the prior last-known-good payload remains active.

The focused project skill is also required for aggregate installation success. A conflicting pre-existing skill root is preserved and reported as non-success partial, but that independent discovery/setup domain has zero influence on the validated extension runtime: prefab preview, extension-launched Phase 1 generation, and Phase 2 application continue from the bundled instructions at full capability. Only agent discovery or setup through that unavailable project-skill domain is affected.

Windows uses Base's source-available, hash-pinned native verifier for handle-bound ACL, identity, reparse-point, hard-link, race-safe consent, and executable checks. Its ordinary and elevated adversarial suites are validated on VM-local NTFS in Parallels. A successful Windows installation therefore has the same all-capabilities-validated meaning and Edit behavior as every other supported host; an unsafe or incomplete installation fails closed without redefining the feature. The verifier is confined to installer/consent/Unity-validation boundaries; normal preview, generation, and application descriptor/runtime calls never invoke it.

This software is proprietary. Permission to download, install, and use it is provided by the bundled LICENSE file.