Release v0.84.38 runtime cache layout

Autodidac · Autodidac · commit cc19bd347c23 · 2026-05-23T02:53:48.000-04:00
diff --git a/.gitignore b/.gitignore
@@ -67,6 +67,12 @@ Tools/epoch_install.log
 Tools/epoch_install.log
 Engine/examples/ConsoleApplication1/atlas_dump/
 Engine/examples/ConsoleApplication1/atlas_dump_backup/
+cache/updates/
+cache/packages/
+cache/atlases/
+Engine/cache/updates/
+Engine/cache/packages/
+Engine/cache/atlases/
 
 Engine/bin/
 Engine/Bin/
diff --git a/AGENTS.md b/AGENTS.md
@@ -23,6 +23,11 @@
   task is explicitly about those artifacts. Common generated/local paths include
   `build/`, `x64/`, `Engine/Bin/`, `Engine/build/`, `Engine/built/`, and
   runtime logs/captures.
+- Runtime-created cache buckets are executable-local: updater work, temporary
+  probes, extraction state, and managed helper tools belong in `cache/updates/`;
+  downloaded package archives belong in `cache/packages/`; generated/runtime
+  atlases belong in `cache/atlases/`. These are disposable local artifacts, not
+  public release payload and not tracked source.
 - Keep `addons/` local/offline. It contains extra starter projects and research
   imports that may later be reviewed into core Epoch, but it must not be added
   to the online repo by default.
diff --git a/Changes/changelog.txt b/Changes/changelog.txt
@@ -1,5 +1,29 @@
 # Epoch Changelog
 
+## [Unreleased]
+
+## [v0.84.38]
+- Bumped the active source and stable release line to `v0.84.38` for the
+  executable-local cache and command-menu stability release.
+- Fixed a remaining command/dropdown menu flicker path by keeping OpenGL
+  top-layer menu sprites out of the normal GUI draw queue. OpenGL now draws
+  those sprites only in the explicit top-layer replay pass that sits above the
+  scene viewport.
+- Top toolbar dropdowns now close when the operator clicks outside the active
+  menu button and dropdown bounds.
+- Operator eye-test confirmed the Windows Release editor is stable with the
+  command menu open after this fix.
+- Updater downloads, source-update work, temporary scripts/log probes, and
+  managed helper tools now stay under executable-local `cache/updates/`; runtime
+  release packages download under executable-local `cache/packages/` instead of
+  `%LOCALAPPDATA%`, the system temp directory, or loose executable-root update
+  artifacts.
+- The updater's Windows runtime fallback now matches the public
+  `EpochEditor.exe` product name while still accepting legacy
+  `ConsoleApplication1.exe` source-build outputs during source-update probes.
+- Documented `cache/atlases/` as the runtime-generated/generated-atlas home so
+  created atlases do not pollute source asset trees or public release payloads.
+
 ## [v0.84.37]
 - Bumped the active source and stable release line to `v0.84.37` for the
   corrected production runtime package refresh.
diff --git a/Changes/roadmap.md b/Changes/roadmap.md
@@ -86,6 +86,12 @@ Build Epoch into one professional, engine-owned runtime and editor shell for:
   duplicated `x64` compatibility folders, source-shaped `Engine/` folders,
   headless smoke binaries, and `ConsoleApplication1.exe` aliases are not public
   runtime payload.
+- Runtime-created data stays executable-local under `cache/`: updater work,
+  temporary update probes, managed tools, and extraction state live under
+  `cache/updates/`; downloaded runtime/source packages live under
+  `cache/packages/`; generated/runtime atlases live under `cache/atlases/`.
+  None of these cache buckets belong in public release payloads or tracked
+  source.
 - The updater must resolve the active install type before replacing files:
   - packaged Windows runtime: install the newest matching `.zip` runtime asset
   - packaged Linux/WSL runtime: install the newest matching `.tar.gz` runtime asset
@@ -295,7 +301,8 @@ does not claim renderer, editor, atlas, or source-tree migration work is done.
 - Later cleanup must classify source atlas assets, generated atlases,
   runtime/cache atlases, and test/demo atlases.
 - Source atlases belong under the canonical asset tree.
-- Generated/cache atlases must not pollute source directories.
+- Generated/cache atlases must be written under executable-local
+  `cache/atlases/` and must not pollute source directories.
 - Generated/cache atlases must be ignored.
 - Editor-generated graph/runtime surfaces must use the dedicated runtime-surface
   atlas and must not be packed into the small built-in GUI skin atlas.
@@ -334,7 +341,8 @@ does not claim renderer, editor, atlas, or source-tree migration work is done.
   resolver-only cleanup pass.
 - Atlas state is mixed but classified: source/demo assets live under the
   example/canonical asset trees, tracked prebaked atlases live under
-  `Engine/examples/ConsoleApplication1/atlases`, generated dump output under
+  `Engine/examples/ConsoleApplication1/atlases`, generated/runtime atlas output
+  belongs under executable-local `cache/atlases/`, legacy dump output under
   `Engine/examples/ConsoleApplication1/atlas_dump` is ignored, and runtime
   copies under `x64/` are build output.
 - MSVC project/filter files were only touched for newly added files in this
@@ -598,6 +606,13 @@ engine shape and should be treated as starting truth for the next passes:
   `directx.gui.cpp`. Remaining DirectX work is renderer-resource parity, real
   depth/resource ownership, and any operator-observed GUI flicker in the D3D11
   pane, not basic context creation.
+- `v0.84.38` is the cache/update and command-menu stability release line:
+  OpenGL top-layer menu sprites are replay-only, toolbar dropdowns close on
+  outside click, updater work/tools/temp extraction stay under executable-local
+  `cache/updates/`, downloaded packages stay under `cache/packages/`, and
+  generated atlases are reserved for `cache/atlases/`. Windows Release and WSL
+  Clang release build/CTest lanes are required proof before publishing the new
+  runtime packages.
 - Canvas2D projection ownership has moved into `render.preview_grid` via one
   shared projection helper. Editor picking, OpenGL, DirectX, Raylib, SDL, SFML,
   Vulkan, and the software preview fallback now consume the same Canvas2D
@@ -829,8 +844,10 @@ engine shape and should be treated as starting truth for the next passes:
 - finish drag/drop and docking/popup behavior as first-class editor systems,
   not per-backend patches
 - keep GUI menu rendering in the OpenGL flicker repro matrix; menu interaction
-  currently makes the issue easier to trigger and should stay documented until
-  root cause is fixed
+  remains an acceptance test even after the OpenGL top-layer replay-only fix
+  because dropdowns, modals, and command windows must stay scene-over without
+  slow flip/flicker regressions. Windows Release operator eye-test confirmed
+  the first replay-only command-menu fix as stable.
 - improve project, script, AI, systems, and output surfaces until the shell
   reads as a professional editor rather than a debug console
 - keep the new script/file/asset workspaces usable as visible AI iteration
diff --git a/Engine/docs/build/local_build_scripts_and_release_packaging.md b/Engine/docs/build/local_build_scripts_and_release_packaging.md
@@ -78,6 +78,12 @@ When a pass changes runtime, editor, backend, AI, or capture behavior:
 - close live windows after validation
 - avoid disposable runs from bad folders that leave stray logs or captures in
   the wrong place
+- keep updater downloads, extraction work, temporary probes, and managed helper
+  tools under the runtime's executable-local `cache/updates/` folder; downloaded
+  package archives belong in `cache/packages/`, and generated atlases belong in
+  `cache/atlases/`
+- do not include `cache/updates/`, `cache/packages/`, or `cache/atlases/` in
+  public runtime packages
 - when the README or other public-facing markdown changes, verify the rendered
   GitHub result after push instead of trusting the raw file text alone
 
diff --git a/Engine/docs/engine/gui_library_architecture.md b/Engine/docs/engine/gui_library_architecture.md
@@ -40,6 +40,12 @@ viewport should wrap their window draw in `gui::begin_top_layer()` /
 `gui::end_top_layer()` so the renderer can replay only those sprites after the
 scene pass. Do not rely on menu creation order alone for z-order.
 
+On OpenGL, top-layer sprites are replay-only. They must not also be queued in
+the normal deferred GUI batch, or command menus can slowly flip between
+scene-under and scene-over composition while a dropdown is open. Backends that
+do not yet consume the explicit top-layer replay path keep their existing
+normal-batch behavior until their presenter owns a matching replay pass.
+
 ## Intended Layers
 
 - Primitive widgets: labels, buttons, connected tabs, dropdown/select boxes,
diff --git a/Engine/docs/engine/runtime_and_editor_workflows.md b/Engine/docs/engine/runtime_and_editor_workflows.md
@@ -34,6 +34,12 @@ the same engine-owned path.
 - source checkout installs still use the same binary-first rule; only after
   packaged parity or absence of a newer package should they rebuild from the
   GitHub source snapshot using the platform build path
+- runtime-created update/package/cache data is app-local: updater work,
+  temporary probes, extraction folders, and helper tools live under
+  `cache/updates/`; downloaded release/source packages live under
+  `cache/packages/`; generated/runtime atlases live under `cache/atlases/`.
+  These folders are disposable runtime state, not public release payload and not
+  tracked source.
 - OpenGL editor composition is scene-first: draw the scene preview, drain
   queued render work, then render the latest persistent GUI batch. The
   persistent batch is required because the OpenGL render thread can run between
diff --git a/Engine/examples/ConsoleApplication1/assets/README.md b/Engine/examples/ConsoleApplication1/assets/README.md
@@ -21,5 +21,5 @@ This folder holds the tracked source images used by the example runtime.
 
 - Prebaked atlas outputs do not live in this folder. They belong in
   `../atlases/`.
-- Disposable atlas debug dumps do not live in this folder. They belong in the
-  ignored local dump paths beside the example runtime.
+- Disposable generated/runtime atlases do not live in this folder. They belong
+  in executable-local `cache/atlases/` and remain ignored.
diff --git a/Engine/examples/ConsoleApplication1/atlases/README.md b/Engine/examples/ConsoleApplication1/atlases/README.md
@@ -7,7 +7,8 @@ This folder is the tracked prebaked atlas output for the example runtime.
 - Keep source images under `../assets/`.
 - Keep tracked prebaked atlases here when they are needed so new clones do not
   have to regenerate everything before the example runtime is usable.
-- Keep disposable local dump/debug output out of git.
+- Keep disposable generated/runtime atlas output under executable-local
+  `cache/atlases/` and out of git.
 
 ## Not source of truth
 
diff --git a/Engine/modules/engine.version.ixx b/Engine/modules/engine.version.ixx
@@ -51,7 +51,7 @@ module;
 #if defined(EPOCH_OVERRIDE_VERSION_REVISION)
 #  define EPOCH_VERSION_REVISION_VALUE EPOCH_OVERRIDE_VERSION_REVISION
 #else
-#  define EPOCH_VERSION_REVISION_VALUE 37
+#  define EPOCH_VERSION_REVISION_VALUE 38
 #endif
 
 #if defined(EPOCH_OVERRIDE_WINDOWS_PACKAGED_VERSION_MAJOR)
diff --git a/Engine/modules/updater.config.ixx b/Engine/modules/updater.config.ixx
@@ -86,12 +86,32 @@ namespace epochnamespace::updater
     export inline std::string RUNTIME_BINARY_NAME()
     {
 #if defined(_WIN32)
-        return "ConsoleApplication1.exe";
+        return "EpochEditor.exe";
 #else
         return "epoch";
 #endif
     }
 
+    export inline std::string CACHE_ROOT_SUBDIR()
+    {
+        return "cache";
+    }
+
+    export inline std::string UPDATER_CACHE_SUBDIR()
+    {
+        return "updates";
+    }
+
+    export inline std::string PACKAGE_CACHE_SUBDIR()
+    {
+        return "packages";
+    }
+
+    export inline std::string ATLAS_CACHE_SUBDIR()
+    {
+        return "atlases";
+    }
+
     export inline std::string SOURCE_SOLUTION_NAME()
     {
         return "Engine.sln";
@@ -272,12 +292,12 @@ namespace epochnamespace::updater
 
     export inline std::string UPDATER_TOOLS_SUBDIR()
     {
-        return "Epoch/t";
+        return "tools";
     }
 
     export inline std::string UPDATER_WORK_SUBDIR()
     {
-        return "Epoch/u";
+        return "work";
     }
 
     export inline constexpr std::string_view VCPKG_OWNER = "microsoft";
diff --git a/Engine/modules/updater.system.ixx b/Engine/modules/updater.system.ixx
@@ -494,42 +494,44 @@ namespace epochnamespace::updater
             return text;
         }
 
-        [[nodiscard]] inline std::filesystem::path managed_tools_root()
+        [[nodiscard]] inline std::filesystem::path ensure_directory(
+            const std::filesystem::path& path)
         {
-#if defined(_WIN32)
-            const auto local_app_data = env_path("LOCALAPPDATA");
-            if (!local_app_data.empty())
-                return local_app_data / UPDATER_TOOLS_SUBDIR();
-#endif
-
             std::error_code ec;
-            auto temp_root = std::filesystem::temp_directory_path(ec);
-            if (!ec && !temp_root.empty())
-                return temp_root / UPDATER_TOOLS_SUBDIR();
+            std::filesystem::create_directories(path, ec);
+            return path;
+        }
 
-            if (const auto runtimeRoot = epoch::core::path::runtime_root_dir(); !runtimeRoot.empty())
-                return runtimeRoot / UPDATER_TOOLS_SUBDIR();
+        [[nodiscard]] inline std::filesystem::path runtime_cache_root()
+        {
+            std::error_code ec;
+            auto root = epoch::core::path::runtime_root_dir();
+            if (root.empty())
+                root = std::filesystem::current_path(ec);
+            if (root.empty() || ec)
+                root = std::filesystem::path{ "." };
 
-            return std::filesystem::path{ UPDATER_TOOLS_SUBDIR() };
+            return ensure_directory(root / CACHE_ROOT_SUBDIR());
         }
 
-        [[nodiscard]] inline std::filesystem::path managed_work_root()
+        [[nodiscard]] inline std::filesystem::path updater_cache_root()
         {
-#if defined(_WIN32)
-            const auto local_app_data = env_path("LOCALAPPDATA");
-            if (!local_app_data.empty())
-                return local_app_data / UPDATER_WORK_SUBDIR();
-#endif
+            return ensure_directory(runtime_cache_root() / UPDATER_CACHE_SUBDIR());
+        }
 
-            std::error_code ec;
-            auto temp_root = std::filesystem::temp_directory_path(ec);
-            if (!ec && !temp_root.empty())
-                return temp_root / UPDATER_WORK_SUBDIR();
+        [[nodiscard]] inline std::filesystem::path package_cache_root()
+        {
+            return ensure_directory(runtime_cache_root() / PACKAGE_CACHE_SUBDIR());
+        }
 
-            if (const auto runtimeRoot = epoch::core::path::runtime_root_dir(); !runtimeRoot.empty())
-                return runtimeRoot / UPDATER_WORK_SUBDIR();
+        [[nodiscard]] inline std::filesystem::path managed_tools_root()
+        {
+            return ensure_directory(updater_cache_root() / UPDATER_TOOLS_SUBDIR());
+        }
 
-            return std::filesystem::path{ UPDATER_WORK_SUBDIR() };
+        [[nodiscard]] inline std::filesystem::path managed_work_root()
+        {
+            return ensure_directory(updater_cache_root() / UPDATER_WORK_SUBDIR());
         }
 
         [[nodiscard]] inline std::string shorten_token(
@@ -1953,7 +1955,7 @@ namespace epochnamespace::updater
                 return std::filesystem::absolute(configured_binary, ec).lexically_normal();
 
 #if defined(_WIN32)
-            return std::filesystem::absolute("ConsoleApplication1.exe", ec).lexically_normal();
+            return std::filesystem::absolute("EpochEditor.exe", ec).lexically_normal();
 #else
             return std::filesystem::absolute("epoch", ec).lexically_normal();
 #endif
@@ -1969,32 +1971,24 @@ namespace epochnamespace::updater
 
         [[nodiscard]] inline std::filesystem::path replacement_package_path(const std::filesystem::path& target_binary)
         {
-#if defined(_WIN32)
-            return target_binary.parent_path() / "main.update.pkg";
-#else
-            const auto install_root =
-                managed_work_root()
-                / shorten_token(
+            const auto install_token =
+                shorten_token(
                     target_binary.parent_path().filename().string()
                     + "_" + target_binary.stem().string(),
                     24);
-            return install_root / "pkg" / "main.update.pkg";
-#endif
+            return ensure_directory(package_cache_root() / install_token) / "main.update.pkg";
         }
 
         [[nodiscard]] inline std::filesystem::path replacement_extract_dir(const std::filesystem::path& target_binary)
         {
-#if defined(_WIN32)
-            return target_binary.parent_path() / "__epoch_update";
-#else
             const auto install_root =
-                managed_work_root()
+                updater_cache_root()
                 / shorten_token(
                     target_binary.parent_path().filename().string()
                     + "_" + target_binary.stem().string(),
-                    24);
-            return install_root / "px";
-#endif
+                    24)
+                / "extract";
+            return install_root;
         }
 
         [[nodiscard]] inline std::filesystem::path source_archive_path(const std::filesystem::path& target_binary)
@@ -2061,12 +2055,7 @@ namespace epochnamespace::updater
         {
             static std::atomic<unsigned long long> s_counter{ 0 };
 
-            std::error_code ec;
-            auto temp_root = std::filesystem::temp_directory_path(ec);
-            if (ec || temp_root.empty())
-            {
-                temp_root = epoch::core::path::runtime_root_dir();
-            }
+            auto temp_root = ensure_directory(updater_cache_root() / "tmp");
 
             std::string safe_stem;
             safe_stem.reserve(stem.size());
@@ -2174,8 +2163,9 @@ namespace epochnamespace::updater
             const std::filesystem::path& target_binary)
         {
 #if defined(_WIN32)
-            const std::array<std::filesystem::path, 3> candidates{
+            const std::array<std::filesystem::path, 4> candidates{
                 runtime_dir / target_binary.filename(),
+                runtime_dir / "EpochEditor.exe",
                 runtime_dir / "ConsoleApplication1.exe",
                 runtime_dir / "epoch.exe",
             };
diff --git a/Engine/src/editor.cpp b/Engine/src/editor.cpp
diff --git a/Engine/src/engine.gui.cpp b/Engine/src/engine.gui.cpp
diff --git a/Images/readme/linux-opengl-v08438.png b/Images/readme/linux-opengl-v08438.png
diff --git a/README.md b/README.md
