Skip to content

feat: Unreal Engine support - One File Per Actor filename decoding #2068

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
Jus2Cat wants to merge 11 commits into
base: develop
Choose a base branch
from
Open

feat: Unreal Engine support - One File Per Actor filename decoding #2068

Jus2Cat wants to merge 11 commits into from
+1,550 −35

Conversation

@Jus2Cat
Copy link

@Jus2Cat Jus2Cat commented Jan 25, 2026 •
edited
Loading

This PR adds support for Unreal Engine's One File Per Actor system. It decodes hashe filenames
(e.g. KCBX0GWLTFQT9RJ8M1LY8.uasset) into human-readable view.

One-file-per-actor-git-support

This solves a major pain point for UE developers where file names are meaningless hash strings.

This makes it impossible to identify which actors have been modified without opening the Unreal Editor, causing significant workflow delays.
Currently, only one paid Git client offers a similar feature, and there are no free alternatives.

🛡️ Safety & Performance (Key Highlights)

  • Zero Overhead by Default: The feature is completely opt-in. All heavy logic is guarded by
    EnableUnrealEngineSupport. If disabled, this code path is never executed.
  • Memory Safe: Binary decoding is capped at 256KB per file. This prevents
    System.OutOfMemoryException and UI freezes, even if users modify huge binary assets (1GB+).
  • Batched Processing: Instead of spawning a process for every file, it uses git cat-file --batch
    to read Git objects. This makes it performant even with thousands of changes.
  • Caching: Decoded names are cached based on file size/timestamp to avoid redundant I/O on
    refresh.

🛠️ Changes

  1. Core: Added OFPAParser (custom binary reader for .uasset headers).
  2. ViewModel: Integrated async decoding into WorkingCopy.cs using Task.Run to keep UI responsive.
  3. UI: Added toggle in Repository Settings and Working Copy toolbar. Added specific icons for
    decoded files.
  4. Tests: Added comprehensive unit tests covering Parser edge cases and UI Converters.
  5. Locales: Added translations for English, Russian, and Chinese (Simplified).

One-file-per-actor-git-support-modes

  • Full View Support: Works across all three display modes: Tree, List, and Grid.
  • The feature is active only within Unreal Engine projects containing __ExternalActors__ or __ExternalObjects__ folders and a .uproject file.
  • Zero Clutter: For non-Unreal repositories, the OFPA toggle and icons are not displayed,
    ensuring no impact on the standard Git workflow.

Naineten added 6 commits January 24, 2026 23:08
feat: add support for decoding UE OFPA filenames in working copy
a10bc73 
This feature helps Unreal Engine developers by displaying human-readable Actor labels instead of raw hashed filenames (e.g., 'KCBX...uasset') in the Working Copy view.

Changes:
- Implemented a native C# parser for .uasset files to extract 'ActorLabel' or 'FolderLabel'.
- Added 'EnableOFPADecoding' option in Repository Settings.
- Added a toggle button in the Working Copy toolbar.
- Implemented async path decoding in WorkingCopy ViewModel to avoid UI blocking.
- Updated ChangeTreeNode to display decoded names in Tree View mode.
- Added unit tests for the OFPA parser.
feat: enhance OFPA support and support all view modes
6aad495 
This update polishes the OFPA naming implementation and extends support to List and Grid views.

Improvements:
- Refactored binary parser into 'SourceGit.Utilities.OFPAParser' with improved naming and safety.
- Created 'PathToDisplayNameConverter' to enable decoded names in List and Grid views.
- Fixed UI refresh issue when toggling OFPA mode by ensuring dictionary reference swapping.
- Added race condition protection in async decoding task.
- Updated all view modes in 'ChangeCollectionView' to support 'DecodedPaths'.
- Fixed nullable warnings for .NET 10.0 compatibility.
feat: complete Unreal Engine OFPA support with contextual UI and caching
828cd3e 
This update finalizes the OFPA feature logic.

Changes:
- Added contextual visibility: The decoding toggle is now hidden unless a .uproject or .uplugin file is detected.
- Implemented metadata caching: Files are re-decoded only when modified (size/time check).
- Added fallback to Git Index/HEAD: Deleted or missing files are now decoded by reading blobs from Git.
- Fixed Race Condition: Guarded against applying results if the feature was disabled during async processing.
- Safety: Added checks for object disposal to prevent crashes.
i18n: add Chinese and Russian translations for OFPA feature
2095f17
feat(perf): optimize OFPA decoding with batch git processing and caching
68a20b5 
Major performance improvement for Unreal Engine projects with many OFPA files.

Changes:
- Implement QueryFileContent.RunBatchAsync using git cat-file --batch to reduce process creation overhead for Index/HEAD file reads.
- Refactor WorkingCopy.DecodeOFPAPathsAsync:
  - Use batch processing for missing working tree files.
  - Implement sequential task execution to prevent race conditions.
  - Add stat-based caching (size/mtime) to skip re-decoding unchanged files.
- Cache IsUnrealEngineProject check in Repository ViewModel to avoid repeated I/O.
- Add unit tests for OFPAParser case sensitivity and extension checks.
- Add PerformanceLogger for internal profiling of decode operations.
feat: finalize OFPA support with memory-safe decoding and UI refinements
bda0c6c 
Complete the Unreal Engine OFPA (One File Per Actor) support with safety guards, updated localization, and performance fixes.

Changes:
- Memory Safety: Implemented MaxOFPASampleSize (256KB) limit for binary reads in QueryFileContent.RunBatchAsync to prevent OOM when processing large UE assets.
- Robust Parsing: Increased MaxHeaderScanSize in OFPAParser and improved heuristic detection for ActorLabel/FolderLabel in complex uasset files.
- UI/UX: Added OFPA-specific icons and updated Repository Configuration view to support the new toggle.
- Localization: Added translations for English, Russian, and Chinese (Simplified).
- Stability: Added unit tests for PathToDisplayNameConverter and Repository-level Unreal Engine support logic.
- Cleanup: Removed legacy SourceGit.sln (migrated to .slnx) and internal PerformanceLogger.
@Jus2Cat Jus2Cat changed the base branch from master to develop January 25, 2026 19:04
Naineten added 2 commits January 26, 2026 03:13
feat: extend OFPA decoding to Commit History and Stashes view
6ff8826 
Applied the OFPA filename decoding logic to historical views (Commit Detail and Stashes).

Changes:
- Implemented async decoding in CommitDetail and StashesPage ViewModels.
- Updated CommitChanges, CommitDetail (Info tab), and StashesPage Views to bind to DecodedPaths.
- Reused efficient batch git processing (git cat-file) to read file content from specific revisions (SHA/Parent) without checking out files.
- Guarded by the same EnableUnrealEngineSupport setting.
refactor: improve naming and style consistency in OFPA logic
f78a6c9
@redsigma
Copy link

redsigma commented Jan 26, 2026 •
edited
Loading

does the decoding also allow to show if the file is locked by someone ? It would be nice if it name shows
<actor name> - <locked by PersonX>

I think it would be useful to have that if possible

Naineten added 2 commits January 27, 2026 15:57
fix(ofpa): eliminate filename popping in history and stash views
b4ed5d8 
- Refactor OFPA decoding in CommitDetail and StashesPage to be fully async and atomic.
- Prevent UI updates until decoding is complete to avoid visual artifacts.
- Ensure thread safety and handle race conditions during rapid navigation.
feat: decode OFPA filenames in LFS Locks dialog
3f130bb 
- Implement async decoding of OFPA paths in the LFS Locks window.
- Reuse OFPAConverters.PathToDisplayName for consistent rendering.
- Ensure decoding happens on a background thread to prevent UI freezing.
- Fallback to raw paths for files missing locally.

This improves usability for UE5 developers by showing human-readable Actor Labels instead of hashed filenames when managing LFS locks.
@Jus2Cat
Copy link
Author

Jus2Cat commented Jan 28, 2026

does the decoding also allow to show if the file is locked by someone ? It would be nice if it name shows <actor name> - <locked by PersonX>

I think it would be useful to have that if possible

Updated.

One-file-per-actor-git-lock-support

@redsigma
Copy link

redsigma commented Jan 30, 2026 •
edited
Loading

@Jus2Cat Awesome work with this PR . I see you added a button to view the locked files in a separate window. I think this approach might be difficult to use if you have 50 locked files and you have to figure out which person locked it.

Would it be possible maybe to achieve one of the following:

  1. Locked files show with a different icon. Currently there is green (added), red(removed) , orange(modified). Maybe some icon like blue can be added ?

  2. Have the locked files be hidden from the commit list. And have a separate button to show them as well.

  3. Have separate button which checks every file in the staging, and lists the locked files and who has locked them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Jus2Cat @redsigma