Fold Utils and Platform into Core

AGENTS.md

@@ -45,6 +45,8 @@ platform setup (Vulkan SDK, GLFW, etc.).
   Resources, Editor) are documented in [`docs/BuildModules.md`](docs/BuildModules.md) —
   read it before restructuring includes or CMake targets, it records locked decisions.
 - Orientation for where things live today: [`Skills/architecture.md`](Skills/architecture.md).
+- Adding a new CMake module (folder + `fling_add_module`, with a UI example):
+  [`Skills/adding-modules.md`](Skills/adding-modules.md).
 
 ## Contribution conventions
 

CMake/FlingEngineInc.cmake

@@ -31,8 +31,6 @@ MACRO(FLING_ENGINE_INC EngineDir )
 		${EngineDir}Core/inc
 		${EngineDir}Graphics/inc
 		${EngineDir}Resources/inc
-		${EngineDir}Utils/inc
-		${EngineDir}Platform/inc
 		${EngineDir}Gameplay/inc
 		${GENERATED_INC_FOLDER}		# Generated include files that cmake will handle (i.e. GitVersion)
 	)

FlingEngine/CMakeLists.txt

@@ -123,14 +123,6 @@ if( MSVC )
     endforeach()
 endif()
 
-################# Add dynamic module directories ###################
-# TODO: Can't we do this recursively or something like that??
-add_subdirectory(Foundation)
-# Link against the Foundation module
-set( LINK_LIBS ${LINK_LIBS} Foundation )
-
-#find_package(Foundation REQUIRED)
-
 ################# Add library and link ######################
 
 add_library ( ${PROJECT_NAME} ${_source_list} )

FlingEngine/Core/src/Engine.cpp

@@ -4,7 +4,6 @@
 #include "File.h"
 #include "VulkanApp.h"
 #include "Misc/CommandLine.h"
-#include "Foundation.h"
 #include "ComponentTypeRegistry.h"
 #include "RegisterGraphicsComponents.h"
 

FlingTests/CMakeLists.txt

@@ -21,7 +21,6 @@ set ( LINK_LIBS
     glfw ${GLFW_LIBRARIES}
 	Catch2::Catch2WithMain
 	"FlingEngine"
-    Foundation
 )
 
 # link pthread if we need to

Sandbox/CMakeLists.txt

@@ -21,7 +21,6 @@ endif()
 
 set ( LINK_LIBS
 	"FlingEngine"
-    Foundation
 )
 
 # link pthread if we need to

Skills/README.md

@@ -10,6 +10,7 @@ detail on a given topic. These files are meant to be read on demand, not all at
 | [`testing.md`](testing.md) | Running FlingTests, adding new Catch2 tests |
 | [`coding-style.md`](coding-style.md) | Doc-comment conventions, formatting, what not to touch |
 | [`architecture.md`](architecture.md) | Current folder/module layout, where new code belongs |
+| [`adding-modules.md`](adding-modules.md) | How to add a new engine module (`fling_add_module`, UI example) |
 
 These are supplementary to, not a replacement for, the canonical docs they
 reference (`docs/CodingStyle.md`, `docs/BuildModules.md`) — when in doubt, the

Skills/adding-modules.md

@@ -0,0 +1,143 @@
+# Adding an engine module
+
+Canonical design and locked decisions: [`docs/BuildModules.md`](../docs/BuildModules.md).
+This file is the how-to. Do not invent a second pattern (extra globs in the root
+CMakeLists, a hand-rolled `*_API` header, or edits under `external/`).
+
+`fling_add_module()` lives in [`CMake/FlingModule.cmake`](../CMake/FlingModule.cmake).
+Until `FlingEngine/CMakeLists.txt` `add_subdirectory`s each module, the engine is
+still one static library and new folders are picked up by the monolith glob.
+Do **not** add a `fling_add_module` target that compiles the same sources as
+`FlingEngine` — that double-builds. Use this recipe once modules are separate
+targets (or when you are the change that splits them).
+
+## What you add
+
+A module is:
+
+1. A folder under `FlingEngine/` with `inc/` (public headers) and `src/` (sources).
+2. A `CMakeLists.txt` that calls `fling_add_module`.
+3. `add_subdirectory(...)` in `FlingEngine/CMakeLists.txt` **after** that module's
+   dependencies exist.
+4. `MODULE_API` on types that cross the DLL boundary.
+5. `target_link_libraries(Consumer PRIVATE Fling::ModuleName)` on anything that
+   should see that module's headers.
+
+You do not list `.cpp` files by hand. You do not edit the old engine-wide glob.
+
+## Example: a `UI` module
+
+In-game HUD / widgets. Publicly needs Core and Gameplay (types, `Transform`).
+Privately needs Graphics and ImGui to draw. A physics-only tool would not link
+`Fling::UI` and would not see `UISystem.h`.
+
+### 1. Folder
+
+```
+FlingEngine/UI/
+  CMakeLists.txt
+  inc/UISystem.h
+  src/UISystem.cpp
+```
+
+Keep `#include "UISystem.h"` (flat names). Isolation comes from include **paths**
+via `target_link_libraries`, not from renaming headers to `UI/UISystem.h`.
+
+### 2. `FlingEngine/UI/CMakeLists.txt`
+
+```cmake
+fling_add_module(UI
+    PUBLIC_DEPS  Core Gameplay
+    PRIVATE_DEPS Graphics
+    PRIVATE_LIBS ImGui
+)
+```
+
+| Argument | Meaning |
+|----------|---------|
+| `PUBLIC_DEPS` | Fling modules whose headers consumers of UI may also include |
+| `PRIVATE_DEPS` | Fling modules UI uses internally; not pushed onto UI's consumers' include path |
+| `PUBLIC_LIBS` / `PRIVATE_LIBS` | Third-party CMake targets (glfw, ImGui, Vulkan::Vulkan, …) |
+| `STATIC` | Optional. Default is a shared library |
+
+CMake generates `UIAPI.h` (macro `UI_API`) into the UI build dir and puts that
+dir on UI's **public** include path. Do not check `UIAPI.h` into git.
+
+### 3. Register it bottom-up
+
+In `FlingEngine/CMakeLists.txt`, add UI **after** Core, Gameplay, and Graphics.
+A dependency cycle is a configure error.
+
+```cmake
+add_subdirectory(Core)
+add_subdirectory(Resources)
+add_subdirectory(Gameplay)
+add_subdirectory(Graphics)
+add_subdirectory(UI)
+```
+
+If Sandbox or Engine should use UI, link the alias — do not `include_directories`
+the UI folder:
+
+```cmake
+target_link_libraries(SandboxEditor PRIVATE Fling::UI)
+```
+
+### 4. Export the DLL surface
+
+```cpp
+#pragma once
+
+#include "UIAPI.h"
+#include "FlingTypes.h"
+
+namespace Fling
+{
+    class UI_API UISystem
+    {
+    public:
+        void Init();
+        void Draw(float deltaTime);
+    };
+}
+```
+
+```cpp
+#include "UISystem.h"
+
+namespace Fling
+{
+    void UISystem::Init() {}
+    void UISystem::Draw(float deltaTime) { (void)deltaTime; }
+}
+```
+
+- Mark classes/functions that are **defined in this module's `.cpp`** and called
+  from another module with `UI_API`.
+- Header-only templates stay unmarked.
+- Do not use `FLING_LIB_EXPORT` / `FLING_LIB_IMPORT` on engine types; those are
+  only for the generated `*API.h` headers.
+
+### 5. Consume it
+
+```cpp
+#include "UISystem.h"
+
+Fling::UISystem hud;
+hud.Init();
+```
+
+If a target does not link `Fling::UI`, `#include "UISystem.h"` must fail to
+compile. That is the isolation test.
+
+## Checklist for any new module
+
+- [ ] Folder is `FlingEngine/<Name>/{inc,src}` plus `CMakeLists.txt`.
+- [ ] `fling_add_module(<Name> ...)` only; no extra `add_library` / globs.
+- [ ] `add_subdirectory(<Name>)` after every module in `PUBLIC_DEPS` / `PRIVATE_DEPS`.
+- [ ] Public headers include `<Name>API.h` and use `<NAME>_API` on exported types.
+- [ ] Consumers `target_link_libraries(... Fling::<Name>)`. No new
+      `include_directories()` for engine headers.
+- [ ] Gameplay still does not include Graphics headers. Editor stays a leaf
+      (Engine/Graphics do not include Editor). See [`architecture.md`](architecture.md).
+- [ ] Nothing under `external/` is modified.

Skills/architecture.md

@@ -9,11 +9,12 @@ several things that look like cleanups are explicitly deferred or ruled out ther
 ## Today
 
 - `FlingEngine/` — the engine, currently one CMake library (`FlingEngine`) built
-  from almost every source file under this tree via glob. Subfolders already hint
-  at future module boundaries (`Core`, `Graphics`, `Gameplay`, `Resources`, `Utils`,
-  `Platform`, `Editor`, `Foundation`) but CMake/includes still treat it as one target
-  — `FLING_ENGINE_INC()` adds every engine `inc/` dir to consumers, so folder
-  location doesn't currently enforce isolation.
+  from almost every source file under this tree via glob. Subfolders are
+  `Core` (includes former Utils + Platform), `Graphics`, `Gameplay`,
+  `Resources`, and `Editor`. CMake/includes still treat it as one target —
+  `FLING_ENGINE_INC()` adds every engine `inc/` dir to consumers, so folder
+  location doesn't currently enforce isolation. `fling_add_module()` lives in
+  `CMake/FlingModule.cmake` but is not yet used for a real shared module.
 - `Sandbox/` — the sample game + editor, one executable today (editor support is
   toggled by a project-wide `WITH_EDITOR` define, which `docs/BuildModules.md`
   plans to remove in favor of two separate executables).
@@ -37,5 +38,5 @@ several things that look like cleanups are explicitly deferred or ruled out ther
   it describes instead.
 - Don't add a new module folder or CMake target without reading the "Locked
   decisions" section of `docs/BuildModules.md` first — several plausible-looking
-  approaches (per-module PCH, merging Foundation into something else, git
-  submodules per system) are explicitly rejected there.
+  approaches (per-module PCH, git submodules per system) are explicitly rejected there.
+  The how-to (including a UI module example) is [`adding-modules.md`](adding-modules.md).