# Binary Asset Version Control Guide

This guide defines the Maya engine binary asset workflow for Git LFS, file
locking, Perforce interoperability, repository performance, CI validation, and
disaster recovery.

## Git LFS Tracking

Maya game content roots are LFS-backed through `.gitattributes`. The default
tracked extensions include:

- textures and HDR images: `png`, `jpg`, `jpeg`, `tga`, `tif`, `tiff`, `exr`,
  `hdr`
- meshes and scene containers: `fbx`, `obj`, `glb`, `gltf`, `blend`, `usd`,
  `usdc`, `usdz`
- audio: `wav`, `ogg`, `flac`, `mp3`
- Unreal cooked/source packages: `uasset`, `umap`, `ubulk`, `uexp`, `utoc`,
  `ucas`

Use `createMayaLfsAttributeRules` and `renderGitattributesRules` from
`@aphrodite/game-assets/version-control` to regenerate expected attributes for
new content roots.

## Lock Before Editing

All Maya binary asset rules are lockable. Artists should lock before editing and
unlock after commit:

```bash
git lfs lock V5/ue/Content/Characters/Hero/hero.fbx
git add V5/ue/Content/Characters/Hero/hero.fbx
git commit -m "art: update hero retopology"
git lfs unlock V5/ue/Content/Characters/Hero/hero.fbx
```

`AssetLockManager` models the same workflow for automation. CI can reject
changed binary files that do not have a matching lock or that are locked by
another user.

## LFS Storage Backend

Production LFS storage should run through an LFS server backed by S3-compatible
object storage. The storage plan should enable:

- bucket versioning
- object lock or immutability
- lifecycle transition to infrequent access and archive tiers
- multipart upload cleanup
- cross-region replication
- Git LFS locks verification
- LFS batch API

`renderLfsStorageConfig` renders the expected `.lfsconfig` body for a concrete
endpoint, bucket, and prefix. `renderS3LifecyclePolicy` renders the lifecycle
policy shape for S3-compatible storage.

## Perforce Interop

Studios that prefer Perforce should mirror the `.gitattributes` `p4type`
metadata into the Perforce typemap:

```text
binary+l //depot/Oshun/V5/ue/Content/.../*.uasset
binary+l //depot/Oshun/V5/ue/Content/.../*.umap
binary+l //depot/Oshun/V5/ue/Content/.../*.fbx
binary+l //depot/Oshun/V5/ue/Content/.../*.exr
binary+l //depot/Oshun/V5/ue/Content/.../*.wav
```

Recommended setup:

1. Create a stream depot for engine content.
2. Use exclusive checkout for source binaries.
3. Run P4 Git Connector only for branches that need Git/Perforce mirroring.
4. Treat Git LFS pointer validation and Perforce submit validation as equivalent
   gates.

## Budgets, Dedupe, and Pruning

`AssetSizeBudgetValidator` warns when a single asset exceeds 100 MB and fails
when it exceeds 500 MB by default. Audio and video can use per-kind overrides.

`AssetDeduplicator` groups identical content hashes and reports reclaimable
bytes. `AssetPruner` identifies assets that are not referenced by manifests,
levels, materials, or bundles. Prune reports are review lists, not automatic
deletes.

## Shallow Artist Clones

Use `RepositoryOptimizationPlanner.createArtistClonePlan` for onboarding:

```bash
git clone --filter=blob:none --sparse git@github.com:GreyChimp/oshun.git oshun-art
cd oshun-art
git sparse-checkout set V5/ue/Content V6/ue/Content
git lfs fetch --include="V5/ue/Content/**,V6/ue/Content/**" --exclude=""
```

Recommended Git config:

- `lfs.concurrenttransfers=8`
- `lfs.activitytimeout=60`
- `fetch.parallel=4`
- `core.fsmonitor=true`
- `feature.manyFiles=true`

## Binary Diff Review

`BinaryDiffPlanner` selects a review mode by asset kind:

- side-by-side image diff for textures
- tone-mapped diff for `exr` and `hdr`
- wireframe diff for meshes
- waveform diff for audio
- metadata diff for opaque packages

CI and review bots can attach these commands to pull request comments without
requiring authors to inspect raw binary blobs.

## Notifications

`AssetChangeNotifier` routes changes to owner teams and dependent asset users.
Every change notification should include the path, change type, author, owner
team, and dependent levels/materials/cinematics that may need review.

## Backup and Disaster Recovery

`AssetBackupPlanner` defines required checks:

- bucket versioning enabled
- object lock or immutability enabled
- replication lag below 15 minutes
- daily LFS pointer manifest export
- monthly restore drill passing

Keep restore drills scripted and auditable. Backups are incomplete unless both
LFS objects and Git pointer history can be restored together.

## CI Validation

`AssetVersionControlCiValidator` verifies:

- all expected `.gitattributes` rules exist
- LFS-required assets are committed as pointers
- raw binary blobs are not accidentally committed to Git
- size budgets are enforced

Run this gate before merge and in nightly repository health checks.
