feat: Add BitmapFont support and modular font compilation

- Add BitmapFont class for lightweight font rendering without FreeType
- Add pack_bitmap_font.py tool to generate font atlases from TTF
- Add CMake options ES_FEATURE_SDF_FONT and ES_FEATURE_BITMAP_FONT
- Update UIBatchRenderer with conditional font rendering methods
- Update all widgets (Label, Button, TextField, etc.) for font modularity
- FreeType dependency is now optional (only needed for SDF fonts)

This enables building lightweight versions for playable ads and
WeChat mini-games where package size is critical (<5MB).

Author: esengine

CMakeLists.txt

@@ -12,6 +12,10 @@ option(ES_BUILD_EXAMPLES "Build examples" ON)
 option(ES_BUILD_TESTS "Build tests" ON)
 option(ES_BUILD_EDITOR "Build editor (native only)" OFF)
 
+# Feature options (modular compilation)
+option(ES_FEATURE_SDF_FONT "Enable SDF font rendering (requires FreeType)" ON)
+option(ES_FEATURE_BITMAP_FONT "Enable bitmap font rendering (lightweight)" ON)
+
 # Include custom CMake modules
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 include(ESEngineConfig)
@@ -41,7 +45,6 @@ set(ESENGINE_SOURCES
     # UI System
     src/esengine/ui/UIContext.cpp
     src/esengine/ui/rendering/UIBatchRenderer.cpp
-    src/esengine/ui/font/SDFFont.cpp
     src/esengine/ui/layout/StackLayout.cpp
     src/esengine/ui/layout/WrapLayout.cpp
     src/esengine/ui/widgets/Widget.cpp
@@ -62,6 +65,15 @@ set(ESENGINE_SOURCES
     src/esengine/ui/docking/DockLayoutSerializer.cpp
 )
 
+# Font sources (conditional)
+if(ES_FEATURE_SDF_FONT)
+    list(APPEND ESENGINE_SOURCES src/esengine/ui/font/SDFFont.cpp)
+endif()
+
+if(ES_FEATURE_BITMAP_FONT)
+    list(APPEND ESENGINE_SOURCES src/esengine/ui/font/BitmapFont.cpp)
+endif()
+
 set(ESENGINE_HEADERS
     src/esengine/ESEngine.hpp
     src/esengine/core/Types.hpp
@@ -111,7 +123,6 @@ set(ESENGINE_HEADERS
     src/esengine/ui/layout/Layout.hpp
     src/esengine/ui/layout/StackLayout.hpp
     src/esengine/ui/rendering/UIBatchRenderer.hpp
-    src/esengine/ui/font/SDFFont.hpp
     src/esengine/ui/icons/Icons.hpp
     src/esengine/ui/widgets/Widget.hpp
     src/esengine/ui/widgets/Panel.hpp
@@ -133,6 +144,15 @@ set(ESENGINE_HEADERS
     src/esengine/ui/docking/DockLayoutSerializer.hpp
 )
 
+# Font headers (conditional)
+if(ES_FEATURE_SDF_FONT)
+    list(APPEND ESENGINE_HEADERS src/esengine/ui/font/SDFFont.hpp)
+endif()
+
+if(ES_FEATURE_BITMAP_FONT)
+    list(APPEND ESENGINE_HEADERS src/esengine/ui/font/BitmapFont.hpp)
+endif()
+
 # Platform-specific sources
 if(ES_BUILD_WEB OR ES_BUILD_WXGAME)
     list(APPEND ESENGINE_SOURCES
@@ -244,8 +264,19 @@ if(NOT ES_BUILD_WEB AND NOT ES_BUILD_WXGAME)
     target_include_directories(esengine SYSTEM PRIVATE ${QUICKJS_INCLUDE_DIR})
 endif()
 
-target_link_libraries(esengine PUBLIC glm freetype)
-target_include_directories(esengine PUBLIC ${CMAKE_SOURCE_DIR}/third_party/freetype/include)
+# Core dependencies
+target_link_libraries(esengine PUBLIC glm)
+
+# FreeType dependency (only needed for SDF fonts)
+if(ES_FEATURE_SDF_FONT)
+    target_link_libraries(esengine PUBLIC freetype)
+    target_include_directories(esengine PUBLIC ${CMAKE_SOURCE_DIR}/third_party/freetype/include)
+    target_compile_definitions(esengine PUBLIC ES_FEATURE_SDF_FONT=1)
+endif()
+
+if(ES_FEATURE_BITMAP_FONT)
+    target_compile_definitions(esengine PUBLIC ES_FEATURE_BITMAP_FONT=1)
+endif()
 
 # Platform-specific settings
 if(ES_BUILD_WEB OR ES_BUILD_WXGAME)

src/esengine/ui/UIContext.cpp

@@ -14,10 +14,17 @@
 #include "../events/Dispatcher.hpp"
 #include "../renderer/RenderCommand.hpp"
 #include "../renderer/RenderContext.hpp"
-#include "font/SDFFont.hpp"
 #include "rendering/UIBatchRenderer.hpp"
 #include "widgets/Widget.hpp"
 
+#if ES_FEATURE_SDF_FONT
+#include "font/SDFFont.hpp"
+#endif
+
+#if ES_FEATURE_BITMAP_FONT
+#include "font/BitmapFont.hpp"
+#endif
+
 #include <glm/gtc/matrix_transform.hpp>
 
 namespace esengine::ui {
@@ -55,7 +62,12 @@ void UIContext::shutdown() {
     if (!initialized_) return;
 
     root_.reset();
+#if ES_FEATURE_SDF_FONT
     fonts_.clear();
+#endif
+#if ES_FEATURE_BITMAP_FONT
+    bitmapFonts_.clear();
+#endif
     theme_.reset();
 
     if (renderer_) {
@@ -107,9 +119,10 @@ void UIContext::setTheme(Unique<Theme> theme) {
 }
 
 // =============================================================================
-// Font Management (SDF-based)
+// Font Management
 // =============================================================================
 
+#if ES_FEATURE_SDF_FONT
 SDFFont* UIContext::loadFont(const std::string& name, const std::string& path, f32 fontSize,
                               f32 sdfSpread) {
     auto font = SDFFont::create(path, fontSize, sdfSpread);
@@ -140,6 +153,36 @@ SDFFont* UIContext::getDefaultFont() {
 SDFFont* UIContext::getIconFont() {
     return getFont("icons");
 }
+#endif  // ES_FEATURE_SDF_FONT
+
+#if ES_FEATURE_BITMAP_FONT
+BitmapFont* UIContext::loadBitmapFont(const std::string& name, const std::string& atlasPath,
+                                       const std::string& metricsPath) {
+    auto font = BitmapFont::load(atlasPath, metricsPath);
+    if (!font) {
+        ES_LOG_ERROR("Failed to load bitmap font: {} / {}", atlasPath, metricsPath);
+        return nullptr;
+    }
+
+    BitmapFont* ptr = font.get();
+    bitmapFonts_[name] = std::move(font);
+
+    ES_LOG_INFO("Loaded bitmap font '{}' from {}", name, atlasPath);
+    return ptr;
+}
+
+BitmapFont* UIContext::getBitmapFont(const std::string& name) {
+    auto it = bitmapFonts_.find(name);
+    if (it != bitmapFonts_.end()) {
+        return it->second.get();
+    }
+    return nullptr;
+}
+
+BitmapFont* UIContext::getDefaultBitmapFont() {
+    return getBitmapFont(defaultFontName_);
+}
+#endif  // ES_FEATURE_BITMAP_FONT
 
 // =============================================================================
 // Update and Render

src/esengine/ui/UIContext.hpp

@@ -33,12 +33,22 @@ class Dispatcher;
 
 namespace ui {
 
+#if ES_FEATURE_SDF_FONT
 class SDFFont;
+#endif
+
+#if ES_FEATURE_BITMAP_FONT
+class BitmapFont;
+#endif
+
 class UIBatchRenderer;
 class Widget;
 
-// Alias for backward compatibility - Font now means SDFFont
+#if ES_FEATURE_SDF_FONT
 using Font = SDFFont;
+#elif ES_FEATURE_BITMAP_FONT
+using Font = BitmapFont;
+#endif
 
 // =============================================================================
 // UIContext Class
@@ -136,42 +146,32 @@ class UIContext {
     const Theme& getTheme() const { return *theme_; }
 
     // =========================================================================
-    // Font Management (SDF-based)
+    // Font Management
     // =========================================================================
 
+#if ES_FEATURE_SDF_FONT
     /**
      * @brief Loads a font from file (uses SDF rendering)
-     * @param name Name to register the font as
-     * @param path Path to the TTF font file
-     * @param fontSize SDF glyph size (recommended: 32-64)
-     * @param sdfSpread SDF spread in pixels (default: 8)
-     * @return Pointer to the loaded font or nullptr on failure
      */
     SDFFont* loadFont(const std::string& name, const std::string& path, f32 fontSize = 48.0f,
                       f32 sdfSpread = 8.0f);
 
-    /**
-     * @brief Gets a loaded font by name
-     * @param name Font name
-     * @return Pointer to the font or nullptr if not found
-     */
     SDFFont* getFont(const std::string& name);
-
-    /**
-     * @brief Gets the default font
-     * @return Pointer to the default font or nullptr
-     */
     SDFFont* getDefaultFont();
-
-    /**
-     * @brief Gets the icon font (Lucide icons)
-     * @return Pointer to the icon font or nullptr
-     */
     SDFFont* getIconFont();
+#endif
 
+#if ES_FEATURE_BITMAP_FONT
     /**
-     * @brief Sets the default font name
+     * @brief Loads a bitmap font from atlas and metrics files
      */
+    BitmapFont* loadBitmapFont(const std::string& name, const std::string& atlasPath,
+                                const std::string& metricsPath);
+
+    BitmapFont* getBitmapFont(const std::string& name);
+    BitmapFont* getDefaultBitmapFont();
+#endif
+
     void setDefaultFontName(const std::string& name) { defaultFontName_ = name; }
 
     // =========================================================================
@@ -343,7 +343,14 @@ class UIContext {
     Unique<Widget> root_;
     Unique<Theme> theme_;
 
+#if ES_FEATURE_SDF_FONT
     std::unordered_map<std::string, Unique<SDFFont>> fonts_;
+#endif
+
+#if ES_FEATURE_BITMAP_FONT
+    std::unordered_map<std::string, Unique<BitmapFont>> bitmapFonts_;
+#endif
+
     std::string defaultFontName_ = "default";
 
     u32 viewportWidth_ = 0;

src/esengine/ui/docking/DockTabBar.cpp

@@ -14,7 +14,14 @@
 #include "DockPanel.hpp"
 #include "../UIContext.hpp"
 #include "../rendering/UIBatchRenderer.hpp"
+
+#if ES_FEATURE_SDF_FONT
 #include "../font/SDFFont.hpp"
+#endif
+
+#if ES_FEATURE_BITMAP_FONT
+#include "../font/BitmapFont.hpp"
+#endif
 
 #include <cmath>
 
@@ -166,12 +173,21 @@ void DockTabBar::renderTab(UIBatchRenderer& renderer, const DockTabInfo& tab, us
         tab.bounds.height
     };
 
+#if ES_FEATURE_SDF_FONT
     SDFFont* font = ctx->getDefaultFont();
     if (font) {
         renderer.drawTextInBounds(tab.title, textBounds, *font,
                                    theme.typography.fontSizeSmall, textColor,
                                    HAlign::Left, VAlign::Center);
     }
+#elif ES_FEATURE_BITMAP_FONT
+    BitmapFont* font = ctx->getDefaultBitmapFont();
+    if (font) {
+        renderer.drawTextInBounds(tab.title, textBounds, *font,
+                                   theme.typography.fontSizeSmall, textColor,
+                                   HAlign::Left, VAlign::Center);
+    }
+#endif
 
     if (tab.closable) {
         glm::vec4 closeColor = tab.closeHovered