Eve library

Binary Asset Version Control Guide

Guide

Revision 1

On this page

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.