UI Apps Manager

Core manager for UI app discovery, layout loading/saving, and layout versioning.

Overview

ui_apps scans the virtual filesystem for app.json descriptors, manages UI app layouts (save/load/delete/version), and keeps the UI informed of changes via guihooks.

Extension path: lua/ge/extensions/ui/apps.lua
App directory: /ui/modules/apps/
Layout paths: /settings/ui_apps/layouts/, /settings/ui_apps/originalLayouts/

Exports (M)

Internals

App Discovery

getAvailableAppList() scans for app.json files recursively under /ui/modules/apps/. Each app gets:

• official - isOfficialContentVPath() check
• previews - Up to 3 preview images (app.png, app2.png, app3.png)
• typesTranslated - Translated category labels
• typesLookup / typesTranslatedLookup - Lookup dicts for fast filtering

Apps missing domElement, directive, or appName are logged as errors and skipped.

Layout Versioning

Layouts support two migration strategies:

1. Whole-layout version - If origLayout.version > userLayout.version, the entire user layout is replaced
2. Per-app version - Individual apps with appVersion are updated/added/removed independently

-- Per-app update logic
for _, originalApp in ipairs(origLayout.apps) do
  if originalApp.appVersion then
    local userAppIndex = getAppIndexByName(userLayout, originalApp.appName)
    if userAppIndex then
      if userApp.appVersion < originalApp.appVersion then
        userLayout.apps[userAppIndex] = originalApp  -- update
      end
    else
      table.insert(userLayout.apps, originalApp)  -- add new
    end
  end
end

Removed apps are tracked in layout.removedApps to prevent re-adding.

Save Flow

When saving, updateData() synchronizes appVersion from the original layout and tracks removed apps, then writes to JSON:

local function saveLayout(data)
  updateData(data)
  jsonWriteFile(filename, data, true)
  requestUIAppsData()  -- notify UI
end

How It Works

1. On load, getAvailableAppList() scans VFS for all app.json files
2. getAvailableLayouts() merges original + user layouts, migrating versions
3. UI requests data → requestUIAppsData() triggers onUIAppsData guihook
4. User edits layout → saveLayout() persists changes and refreshes UI
5. Filesystem changes in /ui/modules/apps/ auto-trigger data refresh

Additional Exports

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

• M.deleteLayout
• M.getAvailableLayouts
• M.getUIAppsData
• M.isAppOnLayout
• M.onFilesChanged
• M.requestUIAppsData
• M.saveLayout

See Also

• ui/ambientSound - Ambient Sound Stream Player - Related reference
• UI Audio - Related reference
• Bindings Legend - Related reference
• UI System Guide - Guide