Unity AI Visual Reskin

Unity AI Visual Reskin is an open, AI-first visual intelligence and semantic reskin pipeline for Unity projects. It helps developers and coding agents:

• discover which sprites, textures, prefabs, scenes and GameObjects are visually important;
• connect those assets to exact Unity GUID/fileID and hierarchy evidence;
• search reusable Theme Packs through a local Visual RAG;
• propose explainable old-art to new-art mappings;
• preview and apply approved raster replacements without losing Unity identity;
• compile, scan Missing Scripts, run project-specific Unity gates and roll back exactly when either technical or visual quality fails.

The system is designed to work with Unity AI Project Brain. Project Brain provides structural truth; Unity AI Visual Reskin provides visual retrieval, theme knowledge and guarded mutation.

Status: public research and developer tooling. The safe workflow is production-project tested, but final visual approval remains a human or vision-model decision.

Why this repository exists

Normal search can find files named button or background, but it cannot tell an AI:

• whether that image is runtime game art or an Editor-only icon;
• which scene, prefab, component and property use it;
• whether a proposed replacement preserves alpha, slicing and aspect ratio;
• whether changing it created a Missing Script or compile regression;
• whether a technically valid replacement is actually better-looking.

This repository makes those decisions explicit, versioned and testable.

Architecture

Unity repository
   |
   +-- Unity AI Project Brain
   |      GUID/fileID + scene/prefab/GameObject/component evidence
   |                       |
   |                       v
   +---------------- visual-context.json
                           |
                           v
                  Local Visual RAG
                  theme + project index
                           |
                    pending proposals
                           |
                    visual approval
                           |
                           v
                 Unity Reskin Core
             preview -> apply -> gates
                    -> accept/rollback

The repository separates four independently replaceable layers:

1. Core Unity package — deterministic scanning, matching, transactions, safety gates and Editor UX.
2. Theme Packs — reusable art, semantic roles, 9-slice metadata and stable Unity .meta files.
3. Project Adapters — project-specific scenes, prefab roots, exclusions, legacy names and runtime capture recipes.
4. Visual RAG service — local SQLite metadata/vector catalog, Project Brain bridge, retrieval and review-only proposals.

No AI-generated proposal directly authorizes mutation.

Repository layout

Packages/
  com.heycici.visual-reskin/
  com.heycici.visual-reskin.theme.300mind/
  com.heycici.visual-reskin.adapter.puzzledrop/
revisual_rag/          Python Visual RAG and safe raster transactions
schemas/               Versioned bridge, proposal and manifest contracts
tests/                 Unit and Unity portability fixtures
tools/                 Repository and Unity metadata validators
docs/                  Architecture, authoring and operational guides
AGENTS.md              Fast context for AI coding agents
llms.txt               Machine-oriented documentation index

Requirements

• Unity 6000.3 for the verified Unity package baseline;
• Git 2.14+ available on PATH for Unity Package Manager Git installs;
• a Unity project using text serialization for full YAML evidence;
• optionally, Python 3.10+ for the Visual RAG service;
• optionally, Unity AI Project Brain for exact hierarchy/component usage.

Install from Unity Package Manager

Users do not need to clone this repository.

In Unity, open Window → Package Management → Package Manager, select Install package from Git URL, and paste:

https://github.com/orange91pku/unity-ai-visual-reskin.git?path=/Packages/com.heycici.visual-reskin#v0.4.1

This installs the Core Editor/runtime package pinned to release v0.4.1.

Install the optional sample Theme Pack after Core:

https://github.com/orange91pku/unity-ai-visual-reskin.git?path=/Packages/com.heycici.visual-reskin.theme.300mind#v0.4.1

Teams can pin both dependencies directly in Packages/manifest.json:

{
  "dependencies": {
    "com.heycici.visual-reskin": "https://github.com/orange91pku/unity-ai-visual-reskin.git?path=/Packages/com.heycici.visual-reskin#v0.4.1",
    "com.heycici.visual-reskin.theme.300mind": "https://github.com/orange91pku/unity-ai-visual-reskin.git?path=/Packages/com.heycici.visual-reskin.theme.300mind#v0.4.1"
  }
}

See the full UPM installation guide for updates, uninstall order, troubleshooting and Project Adapter guidance.

Optional Visual RAG service

The Unity package works without cloning the repository. Developers who also want the local Visual RAG CLI can install the tagged Python package directly from Git:

python -m pip install \
  "revisual-rag @ git+https://github.com/orange91pku/unity-ai-visual-reskin.git@v0.4.1"
python -m revisual_rag --db .revisual/visual-rag.sqlite3 init

Index a project without Project Brain:

python -m revisual_rag --db .revisual/visual-rag.sqlite3 ingest-project \
  --project-root /absolute/path/to/UnityProject \
  --project-id studio.game

This fallback reads Unity YAML references. For hierarchy, component and property-level evidence, follow the Project Brain integration guide.

Generate safe-default review proposals after ingesting a Theme Pack:

python -m revisual_rag --db .revisual/visual-rag.sqlite3 propose \
  --project-id studio.game \
  --theme-id hydracore.theme.300mind \
  --output .revisual/mapping-proposals.json

Safe defaults exclude Editor-only images and images with zero serialized Unity references. Discovery workflows can explicitly opt into those lanes, but their results remain review-only.

Approval-gated raster pilot

Materialization creates a preview outside Unity Assets/:

python -m revisual_rag --db .revisual/visual-rag.sqlite3 materialize-raster \
  --proposal-file .revisual/mapping-proposals.json \
  --proposal-id vrmap_EXACT_ID \
  --project-root /absolute/path/to/UnityProject \
  --theme-root Packages/com.heycici.visual-reskin.theme.300mind \
  --output-dir .revisual/candidates

Apply requires the same exact proposal ID:

python -m revisual_rag --db .revisual/visual-rag.sqlite3 apply-raster \
  --candidate-manifest .revisual/candidates/vrmap_EXACT_ID-candidate.json \
  --approve vrmap_EXACT_ID \
  --project-root /absolute/path/to/UnityProject \
  --backup-root .revisual/transactions

The transaction verifies image and .meta hashes, GUID, dimensions, alpha and serialized-reference count. Any failed invariant restores the original files. An accepted technical transaction can still be reversed:

python -m revisual_rag rollback-raster \
  --transaction .revisual/transactions/TRANSACTION_ID/transaction.json

Validation

python -m unittest discover -s tests -v
pwsh -File tools/validate-repository.ps1

The current Python suite covers Visual RAG identity, Project Brain usage, schema migration, proposal safety and exact raster rollback. The Unity fixture is documented in Portability test.

Safety model

• Project Brain and Visual RAG exchange versioned JSON; they never share databases.
• Project Brain and Visual RAG are read-only toward Unity source.
• Every mapping starts with mutationAuthorized=false.
• Preview output and indexes stay outside Unity Assets/.
• Apply is explicit, approval-gated and transaction-backed.
• Unity .meta and GUID identity must not change.
• Technical integration and visual quality are separate verdicts.
• A failed verdict rolls back rather than claiming partial success.

Documentation

• Install with Unity Package Manager
• Connect Unity AI Project Brain
• Architecture
• Visual RAG
• Theme Pack authoring
• Project Adapter authoring
• Raster transactions
• Storage and scale
• Production automation findings
• Contributing

For AI agents

Start with AGENTS.md, then read llms.txt for the shortest map of authoritative files. Stable machine contracts live under schemas/. Do not infer mutation authority from search scores or proposal JSON.

License and third-party content

Repository code is licensed under Apache-2.0. Bundled sample Theme Pack art is third-party content and is not relicensed by the code license; see Third-party notices.

This project is not affiliated with or endorsed by Unity Technologies.