From fe8661476e306cad95e80cadb9144bb50aa93630 Mon Sep 17 00:00:00 2001 From: pc-heini Date: Tue, 16 Jun 2026 03:49:31 +0200 Subject: [PATCH] Document the read-only engine user-folder caveat The non-editable install requires SNAP/SNAP_BUILD for engine-path resolution (now in the wrapper). The engine-level user folder (cache/metrics/UserSettings) still resolves under read-only /app for the projectless Project Manager; tested that the SourceProjectUserPath regset is overwritten by O3DE's bootstrap and does not help. These writes are non-fatal - documenting rather than chasing. Co-Authored-By: Claude Opus 4.8 --- README.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 50cec801..c9b69326 100644 --- a/README.md +++ b/README.md @@ -147,11 +147,24 @@ These were confirmed by inspecting the v26.05 package (`opt/O3DE/26.05/…`): project-build CMake-configure path.) If a future release renames the package or bumps its version away from `1.0.0`, the build fails fast — those are the lines to re-check. -- **Other runtime writes into the install tree may still fail.** Anything else - O3DE tries to generate *inside* `/opt/O3DE/...` at runtime (e.g. certain per-gem - Python deps, or the engine-level asset cache) hits the read-only `/app`. Project - data lives in your writable home dir, so normal project work should be fine; - this is the main remaining open risk. +- **Engine-path resolution needs `SNAP`/`SNAP_BUILD`.** Because the `o3de` CLI is + installed non-editably, its package lives in the per-user venv, so O3DE's + `manifest.get_this_engine_path()` (which walks up from the package `__file__`) + would resolve into the venv and fail to find `engine.json`. O3DE has a built-in + override for immutable installs: when `SNAP` and `SNAP_BUILD` are set it returns + `$SNAP/$SNAP_BUILD`. The wrapper sets them to the engine root. (Confirmed these + vars are read *only* there — no other snap-specific behaviour is triggered.) +- **The Project Manager's own user folder is read-only (cosmetic).** With no + project open, O3DE puts its engine-level *user* folder (asset cache, metrics, + `UserSettings.xml`) under `/.../user`, i.e. read-only `/app`. You'll see + `Couldn't find a valid asset cache folder…`, `cannot write to temp file … + UserSettings.xml`, and a metrics warning at startup. These are **non-fatal** — + the Project Manager runs fine; it just doesn't persist its *own* window/UI + settings between runs. The documented override + (`/O3DE/Runtime/FilePaths/SourceProjectUserPath`) does **not** help: O3DE + recomputes that path from the engine root during bootstrap and overwrites a + `--regset`. Real project data (projects you create, their caches) lives under + your home directory and is fully writable, so actual work is unaffected. - **Launcher icon.** Shipped as `org.o3de.O3DE.png` (the `.deb` itself has only in-editor asset icons). It's kept *inside* the app so the running window/taskbar shows it, but removed from the *exported* set because `flatpak build-export`