LEDMatrix/docs/PLUGIN_CONFIG_CORE_PROPERTIES.md

Core Plugin Properties

Overview

The LEDMatrix plugin system automatically manages certain core properties that are common to all plugins. These properties are handled by the system and don't need to be explicitly defined in plugin schemas.

Core Properties

The following properties are automatically managed by the system (the list is CORE_PLUGIN_PROPERTIES in src/plugin_system/schema_manager.py):

1. enabled (boolean)

   • Default: true
   • Description: Enable or disable the plugin
   • System-managed by PluginManager

2. display_duration (number)

   • Default: 15
   • Range: 1-300 seconds
   • Description: How long to display the plugin in seconds
   • Can be overridden per-plugin

3. live_priority (boolean)

   • Default: false
   • Description: Enable live priority takeover when plugin has live content
   • Used by DisplayController for priority scheduling

4. vegas_width_pct, vegas_overflow, vegas_max_width_screens (untyped; no default)

   • Description: Vegas mode tuning for this plugin — card width as a percentage of the panel, "rotate" or "truncate" on overflow, and the widest the card may be in screens
   • Read by src/vegas_mode/plugin_adapter.py and BasePlugin, which validate the values themselves and ignore a bad one with a log line

5. vegas_participation (string enum: "scroll", "pause", "exclude"; no default)

   • Description: how this plugin takes part in Vegas mode — its content scrolls by, the scroll pauses for its turn and shows it full screen, or it is left out
   • Overrides the plugin's own default (its manifest's vegas_participation, else what its legacy Vegas hooks say); unset means "use the plugin's default"
   • Deliberately has no default: one would be written into every plugin's config and override what each plugin declares
   • Read by resolve_vegas_participation() in src/plugin_system/base_plugin.py; see PLUGIN_API_REFERENCE.md

6. vegas_live (boolean; no default, unset means on)

   • Description: for a plugin with live Vegas elements (it implements get_vegas_elements()), whether the ticker changes what is already scrolling when the plugin's data changes. false shows each card as it was when drawn, as before live elements existed
   • Ignored by plugins without live elements, and whenever live elements are off for the whole ticker (display.vegas_scroll.live_refresh)
   • Read by PluginAdapter.is_live_capable() in src/vegas_mode/plugin_adapter.py; see PLUGIN_API_REFERENCE.md

skin and skin_options were core properties until the skin system was removed. A plugin config saved with them still loads and saves; the keys are dropped on the next save (see RETIRED_PLUGIN_KEYS in schema_manager.py).

How Core Properties Work

Schema Validation

During configuration validation:

1. Automatic Injection: Core properties are automatically injected into the validation schema if they're not already defined in the plugin's config_schema.json
2. Removed from Required: Core properties are automatically removed from the required array during validation, since they're system-managed
3. Default Values Applied: If core properties are missing from a config, defaults are applied automatically:
   • enabled: true (matches BasePlugin.__init__)
   • display_duration: 15 (matches BasePlugin.get_display_duration())
   • live_priority: false (matches BasePlugin.has_live_priority())

Plugin Schema Files

Plugin schemas can optionally include these properties for documentation purposes, but they're not required:

{
  "properties": {
    "enabled": {
      "type": "boolean",
      "default": true,
      "description": "Enable or disable this plugin"
    },
    "display_duration": {
      "type": "number",
      "default": 15,
      "minimum": 1,
      "maximum": 300,
      "description": "Display duration in seconds"
    },
    "live_priority": {
      "type": "boolean",
      "default": false,
      "description": "Enable live priority takeover"
    }
  },
  "required": []  // Core properties should NOT be in required array
}

Important: Even if you include core properties in your schema, they should NOT be listed in the required array, as the system will automatically remove them during validation.

Configuration Files

Core properties are stored in the main config/config.json file:

{
  "my-plugin": {
    "enabled": true,
    "display_duration": 20,
    "live_priority": false,
    "plugin_specific_setting": "value"
  }
}

Implementation Details

SchemaManager

The SchemaManager.validate_config_against_schema() method:

1. Injects core properties into the schema properties if not present
2. Removes core properties from the required array
3. Validates the config against the enhanced schema
4. Applies defaults for missing core properties

Default Merging

When generating default configurations or merging with defaults:

• Core properties get their system defaults if not in the schema
• User-provided values override system defaults
• Missing core properties are filled in automatically

Best Practices

1. Don't require core properties: Never include enabled, display_duration, or live_priority in your schema's required array
2. Optional inclusion: You can include core properties in your schema for documentation, but it's optional
3. Use system defaults: Rely on system defaults unless your plugin needs specific values
4. Document if included: If you include core properties in your schema, use the same defaults as the system to avoid confusion

Troubleshooting

"Missing required property 'enabled'" Error

This error should not occur with the current implementation. If you see it:

1. Check that your schema doesn't have enabled in the required array
2. Ensure you're using the latest version of SchemaManager
3. Verify the schema is being loaded correctly

Core Properties Not Working

If core properties aren't being applied:

1. Check that defaults are being merged (see save_plugin_config())
2. Verify the schema manager is injecting core properties
3. Check plugin initialization to ensure defaults are applied