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:
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:
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:
- Create a stream depot for engine content.
- Use exclusive checkout for source binaries.
- Run P4 Git Connector only for branches that need Git/Perforce mirroring.
- 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:
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=8lfs.activitytimeout=60fetch.parallel=4core.fsmonitor=truefeature.manyFiles=true
Binary Diff Review#
BinaryDiffPlanner selects a review mode by asset kind:
- side-by-side image diff for textures
- tone-mapped diff for
exrandhdr - 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
.gitattributesrules 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.