UI Rework

.github/workflows/engine-build.yml

@@ -81,10 +81,12 @@ jobs:
           # The artifact carries what a downloaded build needs to run and debug itself, so it
           # names those files rather than taking the output directory wholesale. The symbol
           # file answers everything the linker map would, and is what the crash handler reads.
+          # The ui directory travels whole: the game resolves its files by name at runtime.
           engine=Game
           if [ "${{ matrix.configuration }}" = "Debug" ]; then engine=GameD; fi
           built=build/bin/${{ matrix.configuration }}
           cp "${built}/${engine}.exe" "${built}/${engine}.pdb" "${built}/Language.dll" artifact/
+          cp -r "${built}/ui" artifact/ui
           cp LICENSE.md THIRD_PARTY_NOTICES.md artifact/
           mkdir -p artifact/OpenTS_THIRD_PARTY_LICENSES
           cp thirdparty/bgfx.cmake/bgfx/LICENSE artifact/OpenTS_THIRD_PARTY_LICENSES/bgfx.txt
@@ -100,6 +102,15 @@ jobs:
           cat thirdparty/licenses/khronos-vulkan-notice.txt \
               thirdparty/bgfx.cmake/bimg/3rdparty/astc-encoder/LICENSE.txt \
               > artifact/OpenTS_THIRD_PARTY_LICENSES/khronos-vulkan.txt
+          cp thirdparty/RmlUi/LICENSE.txt artifact/OpenTS_THIRD_PARTY_LICENSES/rmlui.txt
+          cp thirdparty/RmlUi/Include/RmlUi/Core/Containers/LICENSE.txt artifact/OpenTS_THIRD_PARTY_LICENSES/rmlui-containers.txt
+          cat thirdparty/freetype/LICENSE.TXT thirdparty/freetype/docs/FTL.TXT \
+              > artifact/OpenTS_THIRD_PARTY_LICENSES/freetype.txt
+          cp thirdparty/licenses/freetype-zlib.txt artifact/OpenTS_THIRD_PARTY_LICENSES/zlib.txt
+          cp thirdparty/imgui/LICENSE.txt artifact/OpenTS_THIRD_PARTY_LICENSES/dear-imgui.txt
+          cp thirdparty/licenses/stb-imgui.txt artifact/OpenTS_THIRD_PARTY_LICENSES/stb-imgui.txt
+          cp thirdparty/licenses/stb-image.txt artifact/OpenTS_THIRD_PARTY_LICENSES/stb-image.txt
+          cp ui/OFL.txt artifact/OpenTS_THIRD_PARTY_LICENSES/open-sans.txt
 
       - name: Upload runtime files
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2

.github/workflows/engine-release.yml

@@ -43,7 +43,7 @@ jobs:
             # prefix itself contains a hyphen, so count the fields from the end.
             platform="$(basename "${dir}" | awk -F- '{print $(NF-2)}')"
             ( cd "${dir}" && zip -r "${GITHUB_WORKSPACE}/OpenTS-${TAG}-${platform}.zip" \
-                Game.exe Game.pdb Language.dll \
+                Game.exe Game.pdb Language.dll ui \
                 LICENSE.md THIRD_PARTY_NOTICES.md OpenTS_THIRD_PARTY_LICENSES )
           done
 

.github/workflows/engine.yml

@@ -8,6 +8,7 @@ on:
       - "cmake/**"
       - "tests/**"
       - "thirdparty/**"
+      - "ui/**"
       - "CMakeLists.txt"
       - ".gitmodules"
       - ".github/msvc-problem-matcher.json"
@@ -20,6 +21,7 @@ on:
       - "cmake/**"
       - "tests/**"
       - "thirdparty/**"
+      - "ui/**"
       - "CMakeLists.txt"
       - ".gitmodules"
       - ".github/msvc-problem-matcher.json"

.gitmodules

@@ -4,3 +4,12 @@
 [submodule "thirdparty/miniaudio"]
 	path = thirdparty/miniaudio
 	url = https://github.com/mackron/miniaudio.git
+[submodule "thirdparty/RmlUi"]
+	path = thirdparty/RmlUi
+	url = https://github.com/mikke89/RmlUi.git
+[submodule "thirdparty/freetype"]
+	path = thirdparty/freetype
+	url = https://github.com/freetype/freetype.git
+[submodule "thirdparty/imgui"]
+	path = thirdparty/imgui
+	url = https://github.com/ocornut/imgui.git

CMakeLists.txt

@@ -60,10 +60,12 @@ set(OPENTS_GAME_DIR "${CMAKE_SOURCE_DIR}/Run" CACHE PATH "Tiberian Sun game data
 # The version resources, the version displays, and the debug log's opening banner all report
 # the version and commit that produced the binary. Stamping runs once here so the headers exist
 # before the first compile, and again per build through OpenTSBuildStamp so that committing does
-# not require a reconfigure to be reflected.
+# not require a reconfigure to be reflected. The UI shell's string-name table is generated from
+# language.h on the same schedule.
 set(OPENTS_GENERATED_DIR "${CMAKE_BINARY_DIR}/generated")
 set(OPENTS_VERSION_HEADER "${OPENTS_GENERATED_DIR}/opents_version.h")
 set(OPENTS_STAMP_HEADER "${OPENTS_GENERATED_DIR}/opents_build.h")
+set(OPENTS_STRINGS_HEADER "${OPENTS_GENERATED_DIR}/opents_strings.h")
 file(MAKE_DIRECTORY "${OPENTS_GENERATED_DIR}")
 
 set(OPENTS_STAMP_ARGS
@@ -79,11 +81,19 @@ set(OPENTS_STAMP_ARGS
     -P "${CMAKE_SOURCE_DIR}/cmake/GitStamp.cmake"
 )
 
+set(OPENTS_STRINGS_ARGS
+    "-DOPENTS_LANGUAGE_HEADER=${CMAKE_SOURCE_DIR}/code/language/language.h"
+    "-DOPENTS_STRINGS_HEADER=${OPENTS_STRINGS_HEADER}"
+    -P "${CMAKE_SOURCE_DIR}/cmake/StringTable.cmake"
+)
+
 execute_process(COMMAND ${CMAKE_COMMAND} ${OPENTS_STAMP_ARGS})
+execute_process(COMMAND ${CMAKE_COMMAND} ${OPENTS_STRINGS_ARGS})
 
 add_custom_target(OpenTSBuildStamp ALL
     COMMAND ${CMAKE_COMMAND} ${OPENTS_STAMP_ARGS}
-    COMMENT "Stamping the build identity"
+    COMMAND ${CMAKE_COMMAND} ${OPENTS_STRINGS_ARGS}
+    COMMENT "Stamping the build identity and the string-name table"
     VERBATIM
 )
 

THIRD_PARTY_NOTICES.md

@@ -16,6 +16,15 @@ remains under its own license and copyright notices.
 | [miniaudio](https://github.com/mackron/miniaudio)                  | Audio device output, resampling, and WAV, FLAC, and MP3 decoding | MIT-0 or Unlicense |
 | [stb_vorbis](https://github.com/nothings/stb)                      | Ogg Vorbis decoding, bundled with miniaudio | MIT or Unlicense |
 | [LZO](https://www.oberhumer.com/opensource/lzo/)                   | LZO1X compression for maps, saves, and network blocks | GPL-2.0-or-later |
+| [RmlUi](https://github.com/mikke89/RmlUi)                          | User interface documents, styling, and layout | MIT |
+| [robin_hood](https://github.com/martinus/robin-hood-hashing)       | Hash map bundled with RmlUi               | MIT          |
+| [itlib](https://github.com/iboB/itlib)                             | Containers bundled with RmlUi             | MIT          |
+| [FreeType](https://freetype.org)                                   | Font rasterization used by RmlUi          | FTL          |
+| [zlib](https://zlib.net)                                           | Compressed font support, bundled with FreeType | zlib |
+| [Dear ImGui](https://github.com/ocornut/imgui)                     | Developer overlays                        | MIT          |
+| [stb](https://github.com/nothings/stb)                             | Rectangle packing, text editing, and TrueType headers bundled with Dear ImGui | MIT or Unlicense |
+| [stb_image](https://github.com/nothings/stb)                       | PNG and TGA decoding for the UI, bundled with bimg | MIT or Unlicense |
+| [Open Sans](https://github.com/googlefonts/opensans)               | The UI font                               | OFL-1.1      |
 
 The source checkout keeps the license texts under `thirdparty/`. Binary
 packages reproduce the license texts for the components used by OpenTS under

cmake/CheckToolkitHeaders.cmake

@@ -0,0 +1,50 @@
+# Checks that no engine header outside code/ui/rml/ includes a UI toolkit or renderer header,
+# and that no engine source outside code/ui/ includes RmlUi or Dear ImGui. docs/UI_DESIGN.md
+# owns the rule; this script only enforces it.
+#
+# Expects OPENTS_SOURCE_DIR to be set. Run with `cmake -DOPENTS_SOURCE_DIR=<root> -P`.
+
+if(NOT DEFINED OPENTS_SOURCE_DIR)
+    message(FATAL_ERROR "CheckToolkitHeaders.cmake: OPENTS_SOURCE_DIR is not set.")
+endif()
+
+set(TOOLKIT_INCLUDE "^[ \t]*#[ \t]*include[ \t]*[<\"](RmlUi/|imgui|bgfx/|bx/|bimg/|stb_)")
+set(UI_TOOLKIT_INCLUDE "^[ \t]*#[ \t]*include[ \t]*[<\"](RmlUi/|imgui)")
+
+set(violations "")
+
+file(GLOB_RECURSE headers RELATIVE "${OPENTS_SOURCE_DIR}"
+    "${OPENTS_SOURCE_DIR}/code/*.h"
+    "${OPENTS_SOURCE_DIR}/code/*.hh"
+    "${OPENTS_SOURCE_DIR}/code/*.hpp"
+)
+foreach(header IN LISTS headers)
+    if(header MATCHES "^code/ui/rml/")
+        continue()
+    endif()
+    file(STRINGS "${OPENTS_SOURCE_DIR}/${header}" hits REGEX "${TOOLKIT_INCLUDE}")
+    foreach(hit IN LISTS hits)
+        list(APPEND violations "${header}: ${hit}")
+    endforeach()
+endforeach()
+
+file(GLOB_RECURSE sources RELATIVE "${OPENTS_SOURCE_DIR}"
+    "${OPENTS_SOURCE_DIR}/code/*.cpp"
+    "${OPENTS_SOURCE_DIR}/code/*.c"
+)
+foreach(source IN LISTS sources)
+    if(source MATCHES "^code/ui/")
+        continue()
+    endif()
+    file(STRINGS "${OPENTS_SOURCE_DIR}/${source}" hits REGEX "${UI_TOOLKIT_INCLUDE}")
+    foreach(hit IN LISTS hits)
+        list(APPEND violations "${source}: ${hit}")
+    endforeach()
+endforeach()
+
+if(violations)
+    list(JOIN violations "\n  " text)
+    message(FATAL_ERROR "Toolkit headers included outside their module:\n  ${text}")
+endif()
+
+message(STATUS "No toolkit header leaks outside code/ui/rml/.")

cmake/StringTable.cmake

@@ -0,0 +1,64 @@
+# Writes the string-name table the UI shell uses to resolve [[TXT_NAME]] references in its
+# documents. language.h defines the string identifiers as macros and keeps no name table, so
+# every `#define TXT_NAME id` line becomes one entry here.
+#
+# Run at configure time and once per build, so an edit to language.h reaches the table without
+# a reconfigure. The header is only rewritten when its contents change, so an ordinary rebuild
+# does not force a recompile.
+#
+# Expects OPENTS_LANGUAGE_HEADER and OPENTS_STRINGS_HEADER to be set.
+
+if(NOT EXISTS "${OPENTS_LANGUAGE_HEADER}")
+    message(FATAL_ERROR "StringTable.cmake: ${OPENTS_LANGUAGE_HEADER} does not exist.")
+endif()
+
+file(STRINGS "${OPENTS_LANGUAGE_HEADER}" lines REGEX "^#define TXT_[A-Za-z0-9_]+[ \t]+[0-9]+")
+
+set(entries "")
+set(count 0)
+foreach(line IN LISTS lines)
+    string(REGEX REPLACE "^#define (TXT_[A-Za-z0-9_]+)[ \t]+([0-9]+).*$" "\\1;\\2" parts "${line}")
+    list(GET parts 0 name)
+    list(GET parts 1 id)
+    string(APPEND entries "\t{ \"${name}\", ${id} },\n")
+    math(EXPR count "${count} + 1")
+endforeach()
+
+if(count EQUAL 0)
+    message(FATAL_ERROR "StringTable.cmake: ${OPENTS_LANGUAGE_HEADER} defines no TXT_ identifiers.")
+endif()
+
+set(content
+"/*******************************************************************************
+ *                                O P E N  T S
+ *******************************************************************************
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ * Copyright 2026 OpenTS contributors
+ *
+ * See LICENSE.md for applicable additional terms and warranty disclaimers.
+ ******************************************************************************/
+
+/* Generated by cmake/StringTable.cmake from language.h. Edits are overwritten by the next build. */
+
+#pragma once
+
+struct OpenTSStringName
+{
+	char const * Name;
+	int Id;
+};
+
+inline constexpr OpenTSStringName OpenTSStringNames[] = {
+${entries}};
+
+inline constexpr int OpenTSStringNameCount = ${count};
+")
+
+set(existing "")
+if(EXISTS "${OPENTS_STRINGS_HEADER}")
+    file(READ "${OPENTS_STRINGS_HEADER}" existing)
+endif()
+
+if(NOT existing STREQUAL content)
+    file(WRITE "${OPENTS_STRINGS_HEADER}" "${content}")
+endif()

code/CMakeLists.txt

@@ -144,26 +144,45 @@ target_include_directories(OpenTS PRIVATE
 # The generated build stamp has to exist before anything compiles.
 add_dependencies(OpenTS OpenTSBuildStamp)
 
-# Only the renderer's own translation unit sees bgfx, so its headers and the shaders it
-# embeds are put on that file rather than on the whole target.
+# Only the renderer's own translation unit and the UI overlay renderer see bgfx, so its
+# headers and the shaders they embed are put on those files rather than on the whole target.
 set(BGFX_ROOT "${CMAKE_SOURCE_DIR}/thirdparty/bgfx.cmake/bgfx")
-set_source_files_properties("${CMAKE_CURRENT_SOURCE_DIR}/bgfxbackend.cpp" PROPERTIES
+set(OPENTS_BGFX_SOURCES
+    "${CMAKE_CURRENT_SOURCE_DIR}/bgfxbackend.cpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/ui/rml/rmlrender.cpp"
+)
+set_source_files_properties(${OPENTS_BGFX_SOURCES} PROPERTIES
     INCLUDE_DIRECTORIES
-        "${BGFX_ROOT}/include;${CMAKE_SOURCE_DIR}/thirdparty/bgfx.cmake/bx/include;${BGFX_ROOT}/examples/common/imgui"
+        "${BGFX_ROOT}/include;${CMAKE_SOURCE_DIR}/thirdparty/bgfx.cmake/bx/include"
     COMPILE_DEFINITIONS
         "BX_CONFIG_DEBUG=$<IF:$<CONFIG:Debug>,1,$<BOOL:${BX_CONFIG_DEBUG}>>"
     COMPILE_OPTIONS "/Zc:preprocessor"
 )
 
+# The frame quad's shaders come from the imgui example and the overlay's from the debug
+# draw example. The imgui example directory also carries an imgui.h that would shadow Dear
+# ImGui's, so only the file that needs those shaders sees it.
+set_property(SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/bgfxbackend.cpp" APPEND PROPERTY
+    INCLUDE_DIRECTORIES "${BGFX_ROOT}/examples/common/imgui"
+)
+set_property(SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/ui/rml/rmlrender.cpp" APPEND PROPERTY
+    INCLUDE_DIRECTORIES "${BGFX_ROOT}/examples/common/debugdraw"
+)
+
 # bx rewrites __stdcall while its headers are being parsed by clang-cl.  Force the
-# compatibility header into the renderer translation unit as well as bx/bgfx so the
+# compatibility header into the renderer translation units as well as bx/bgfx so the
 # MSVC standard-library headers that follow still see the Win32 calling convention.
 if(OPENTS_EXPERIMENTAL_CLANG_CL AND CMAKE_SIZEOF_VOID_P EQUAL 4)
-    set_property(SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/bgfxbackend.cpp" APPEND PROPERTY
+    set_property(SOURCE ${OPENTS_BGFX_SOURCES} APPEND PROPERTY
         COMPILE_OPTIONS "/FI${CMAKE_SOURCE_DIR}/thirdparty/bx-clang-compat.h"
     )
 endif()
 
+# The image decoder is a header bimg carries; only the texture loader compiles it.
+set_property(SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/ui/rml/rmltexture.cpp" APPEND PROPERTY
+    INCLUDE_DIRECTORIES "${CMAKE_SOURCE_DIR}/thirdparty/bgfx.cmake/bimg/3rdparty/stb"
+)
+
 message(STATUS "${PROJECT_NAME}: Adding compilier definitions...")
 target_compile_definitions(OpenTS PRIVATE
     WIN32
@@ -196,6 +215,8 @@ target_link_libraries(OpenTS PRIVATE
     bimg
     miniaudio
     lzo
+    RmlUi::Core
+    imgui
     comctl32
     dbghelp
     iphlpapi
@@ -270,6 +291,20 @@ source_group("Interface Files" FILES
 source_group("Source Files" REGULAR_EXPRESSION ".*\\.(c|cpp)$")
 source_group("Header Files" REGULAR_EXPRESSION ".*\\.(h|hpp)$")
 
+#
+# ---------------------------------------------------------
+# UI files
+# ---------------------------------------------------------
+#
+# The UI documents, styles and font are read beside the executable, like Language.dll. Their
+# own target copies them, so an edited document reaches the output without a relink.
+add_custom_target(OpenTSUIFiles ALL
+    COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_SOURCE_DIR}/ui" "$<TARGET_FILE_DIR:OpenTS>/ui"
+    COMMENT "Copying the UI files beside the executable"
+    VERBATIM
+)
+add_dependencies(OpenTS OpenTSUIFiles)
+
 #
 # ---------------------------------------------------------
 # Visual Studio startup project

code/_ui.cpp

@@ -0,0 +1,29 @@
+/*******************************************************************************
+ *                                O P E N  T S
+ *******************************************************************************
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ * Copyright 2026 OpenTS contributors
+ *
+ * See LICENSE.md for applicable additional terms and warranty disclaimers.
+ ******************************************************************************/
+
+#include "always.h"
+
+#include "_ui.h"
+
+#include "ui/rml/rmlfile.h"
+#include "ui/rml/rmlrender.h"
+#include "ui/rml/rmlsystem.h"
+#include "ui/uienginehost.h"
+#include "ui/uishell.h"
+
+#include <memory>
+
+
+// The one UI shell, over the engine's window, renderer and file search chain. Its
+// constructor stores what it is given and touches none of it, so the order in which the
+// program's globals are built does not matter to it.
+UIShellClass UIShell(UI_Engine_Host(),
+					 std::make_unique<UIRmlSystemClass>(UI_Engine_Host()),
+					 std::make_unique<UIRmlFileClass>(),
+					 std::make_unique<UIRmlBgfxRenderClass>());

code/_ui.h

@@ -0,0 +1,14 @@
+/*******************************************************************************
+ *                                O P E N  T S
+ *******************************************************************************
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ * Copyright 2026 OpenTS contributors
+ *
+ * See LICENSE.md for applicable additional terms and warranty disclaimers.
+ ******************************************************************************/
+
+#pragma once
+
+class UIShellClass;
+
+extern UIShellClass UIShell;