egl-project-tile

Register an out-of-tree UE project with Epic Games Launcher (macOS)

EGL's Library → Unreal Engine → "My Projects" tile grid is populated mainly by scanning one fixed folder:

• macOS: ~/Documents/Unreal Projects/

Projects outside that path will not appear as tiles from the scan source. The fix: place a link inside the scan folder that points at the real project directory.

macOS: symbolic link

On macOS use a regular symlink. ln -s does not need sudo or Developer Mode.

ln -s "<absolute-path-to-real-project-dir>" \
      "$HOME/Documents/Unreal Projects/<DisplayName>"

Example:

ln -s "$HOME/work/MyProject/SampleProject" \
      "$HOME/Documents/Unreal Projects/[MyProject] SampleProject"

Verify: ls -la "$HOME/Documents/Unreal Projects/<DisplayName>" should show l... (symlink) and the correct target.

Then fully quit EGL (⌘Q, or right-click dock icon → Quit — closing the window leaves it running) and relaunch.

EGL on macOS displays the symlink path in the tile tooltip, not the resolved target. So the symlink folder name is what users see when identifying which project a tile maps to.

Disambiguating projects with the same .uproject filename

If multiple repos contain a .uproject with the same filename (e.g. several SampleProject.uproject), give each symlink a distinct, prefixed display name so tooltips and tile paths stay readable:

~/Documents/Unreal Projects/[ProjectA] SampleProject → ~/work/ProjectA/SampleProject
~/Documents/Unreal Projects/[ProjectB] SampleProject → ~/work/ProjectB/SampleProject

Brackets and spaces in the symlink name are fine — EGL renders them verbatim in the tile tooltip path. The tile's underlying display label still comes from the .uproject file (so the visible label may still read SampleProject); the prefix shows up in the tooltip path, which is what disambiguates them at a glance.

RecentlyOpenedProjectFiles can also produce tiles

On macOS EGL also surfaces tiles for paths recorded in ~/Library/Application Support/Epic/UnrealEngine/<ver>/Saved/Config/MacEditor/EditorSettings.ini under RecentlyOpenedProjectFiles, even when those paths live outside ~/Documents/Unreal Projects/. This means a project the user has previously opened (with EGL having recorded it) may already be a tile without any symlink. Do not assume the absence of a tile means the project has never been seen — check that file first.

The two sources (~/Documents/Unreal Projects/ scan and RecentlyOpenedProjectFiles) coexist and do not dedup against each other: a project linked via symlink and also present in RecentlyOpenedProjectFiles will produce two separate tiles. If two tiles for the "same" project annoy the user, either drop the symlink or remove the corresponding RecentlyOpenedProjectFiles line from EditorSettings.ini.

Don't do these instead

• Don't move the project into ~/Documents/Unreal Projects/. The user's git working tree, build scripts, and tooling assume the original path. Moving it breaks all of that.
• Don't change EGL's default project storage location unless the user explicitly asks. It affects every project's discovery and create flow.
• Don't rely on "just open it once and it'll appear". It sometimes works via RecentlyOpenedProjectFiles, but the behaviour is not guaranteed; the symlink is the deterministic fix.

Scope

• macOS only. Windows and Linux are not covered.
• Single-project case. For bulk registration, repeat the link step per project with distinct display names.