Game Blur

Screen blur rectangle system - manages groups of blur regions rendered each frame via the ScreenBlurFX post-effect.

Overview

ui_gameBlur maintains named groups of blur rectangles that are submitted to the engine's ScreenBlurFX object every frame. UI elements use this to blur the background behind panels, menus, and overlays.

Extension path: lua/ge/extensions/ui/gameBlur.lua

Exports (M)

Data Fields

Internals

Blur Rect Format

Each blur rect is a table of 5 numbers: {x1, y1, x2, y2, alpha}. Coordinates are normalized (0,0) top-left to (1,1) bottom-right.

-- Blur the bottom half of the screen at 80% strength
ui_gameBlur.replaceGroup("myPanel", {
  [1] = {0, 0.5, 1, 1, 0.8}
})

Per-Frame Rendering

On each onPreRender, the module iterates all groups and submits rects to the engine:

local function onPreRender()
  if not extensions.ui_visibility.getCef() then return end
  if render_openxr and render_openxr.isSessionRunning() then return end
  local maskedBlurFX = scenetree.ScreenBlurFX
  if maskedBlurFX and maskedBlurFX.obj then
    for _, list in pairs(M.blurRects) do
      for _, data in pairs(list) do
        maskedBlurFX.obj:addFrameBlurRect(data[1], data[2], data[3], data[4], ColorF(1, 1, 1, data[5]))
      end
    end
  end
end

Blur is skipped when CEF UI is hidden or when an OpenXR (VR) session is active.

Group Management

Groups are arbitrary string keys. Typical usage:

-- Set blur behind a menu
ui_gameBlur.replaceGroup("mainMenu", {
  [1] = {0, 0.15, 1, 0.85, 1.0}
})

-- Remove blur when menu closes
ui_gameBlur.removeGroup("mainMenu")

-- Clear everything on state change
ui_gameBlur.removeAllGroups()

How It Works

1. UI code calls replaceGroup with a named group and blur rect data
2. Each frame, onPreRender iterates all stored groups
3. For each rect, addFrameBlurRect is called on the engine's ScreenBlurFX post-effect
4. When UI closes, removeGroup or removeAllGroups cleans up
5. Blur is suppressed in VR mode and when CEF is hidden

Additional Exports

The following exports are available but not yet documented in detail:

• M.onPreRender
• M.removeAllGroups
• M.removeGroup
• M.replaceGroup