FlexLove/docs/MODULE_DEPENDENCIES.md

FlexLöve Module Dependencies

This document provides a comprehensive overview of module dependencies in FlexLöve, helping you understand which modules are required and which are optional.

Dependency Graph

Core Required Modules

These modules are always required and cannot be excluded:

FlexLove.lua
├── ErrorHandler        (error logging & handling)
├── ModuleLoader        (safe module loading)
├── BuildProfile        (profile management)
├── utils               (utility functions & enums)
├── Units               (unit parsing & resolution)
│   └── requires: Context, ErrorHandler
├── Context             (global state & viewport)
├── StateManager        (immediate mode state persistence)
├── Color               (color utilities)
│   └── requires: ErrorHandler
├── InputEvent          (input event abstraction)
├── TextEditor          (text input handling)
├── LayoutEngine        (flexbox layout calculations)
│   └── requires: ErrorHandler, Performance (optional)
├── Renderer            (canvas rendering)
├── EventHandler        (event routing & callbacks)
│   └── requires: ErrorHandler, Performance (optional), InputEvent, utils
├── ScrollManager       (scroll behavior)
├── Element             (UI element primitives)
│   └── requires: ALL core modules + optional modules
├── RoundedRect         (rounded rectangle rendering)
└── Grid                (grid layout utilities)

Optional Modules

These modules can be excluded to reduce bundle size:

Animation Module

Animation
├── requires: ErrorHandler, Color
├── used by: Element (for animations)
└── size impact: ~15% of total

What you lose:

• element.animation property
• FlexLove.Animation API
• Transition effects
• Keyframe animations

Image Modules

ImageRenderer
├── requires: ErrorHandler, utils
└── used by: Element (for image rendering)

ImageScaler
├── requires: ErrorHandler
└── used by: ImageRenderer

ImageCache
└── used by: Element (for image caching)

NinePatch
├── requires: ErrorHandler
└── used by: Element (for 9-patch rendering)

What you lose:

• element.image property
• element.imageFit property
• element.imageRepeat property
• 9-patch image support
• Image caching

Theme Module

Theme
├── requires: ErrorHandler, Color, utils
└── used by: Element (for theming)

What you lose:

• FlexLove.Theme API
• element.theme property
• element.themeComponent property
• Preset theme styles
• Theme-based component styling

Blur Module

Blur
└── used by: Element (for backdrop blur effects)

What you lose:

• element.backdropBlur property
• Glassmorphic effects

Performance Module

Performance
├── requires: ErrorHandler
└── used by: LayoutEngine, EventHandler, FlexLove

What you lose:

• FlexLove._Performance API
• Performance HUD (F3 toggle)
• Performance monitoring
• Frame timing metrics
• Memory profiling

GestureRecognizer Module

GestureRecognizer
└── used by: Element (for gesture detection)

What you lose:

• Touch gesture recognition
• Swipe detection
• Pinch/zoom gestures
• Multi-touch support

Module Loading Order

FlexLöve loads modules in this order:

1. ErrorHandler - Must be loaded first for error reporting
2. ModuleLoader - Loads modules safely with null-object fallbacks
3. BuildProfile - Registers and manages build profiles
4. Core modules - Required for basic functionality
5. Optional modules - Loaded with ModuleLoader.safeRequire()

Profile-Specific Dependencies

Minimal Profile (~70%)

Only includes core required modules. No optional dependencies.

Slim Profile (~80%)

Adds image, animation, gesture support:

• Animation
• ImageRenderer
• ImageScaler
• ImageCache
• GestureRecognizer

Default Profile (~95%)

Adds theme and visual effects:

• All Slim modules
• Theme
• NinePatch
• Blur

Full Profile (100%)

Includes all modules:

• All Default modules
• Performance

Checking Module Availability

You can check if a module is loaded at runtime:

local ModuleLoader = require("modules.ModuleLoader")

-- Check if Animation is available
if ModuleLoader.isModuleLoaded("modules.Animation") then
  -- Use Animation module
  local anim = FlexLove.Animation.new({ ... })
else
  -- Animation not available, use fallback
  print("Animation module not loaded")
end

Dependency Injection Pattern

FlexLöve uses dependency injection to handle optional modules:

-- In Element.lua
function Element.init(deps)
  -- Core dependencies (required)
  Element._utils = deps.utils
  Element._ErrorHandler = deps.ErrorHandler
  
  -- Optional dependencies (may be null objects)
  Element._Animation = deps.Animation  -- May be a no-op stub
  Element._Theme = deps.Theme          -- May be a no-op stub
end

If a module is missing, ModuleLoader returns a null object that:

• Has the same method names as the real module
• Returns safe default values
• Prevents crashes from missing dependencies

Custom Build Profiles

You can create custom profiles with specific module combinations:

local BuildProfile = require("modules.BuildProfile")

-- Register a custom profile
BuildProfile.register({
  name = "my-game",
  description = "Custom profile for my game",
  size = 75,
  modules = {
    -- Core modules (required)
    "utils", "Units", "Context", "StateManager",
    "ErrorHandler", "Color", "InputEvent", "TextEditor",
    "LayoutEngine", "Renderer", "EventHandler",
    "ScrollManager", "Element", "RoundedRect", "Grid",
    
    -- Optional: Add Animation but not Theme
    "Animation",
    "ImageRenderer",
    "ImageScaler",
    "ImageCache",
  }
})

-- Set active profile
BuildProfile.setActive("my-game")

Best Practices

1. Start with Default Profile - Use the default profile unless you have specific bundle size requirements

2. Profile Before Optimizing - Measure your actual bundle size before excluding modules

3. Test Without Optional Modules - If excluding modules, test thoroughly to ensure no features break

4. Use ModuleLoader Checks - Always check if optional modules are loaded before using them

5. Document Your Profile - If creating a custom profile, document which features are disabled

See Also

• BUILD_PROFILES.md - Detailed profile information
• README.md - Getting started guide
• ModuleLoader.lua - Source code for module loading