Dynamic Parameter System

The matrixapplication framework (version 0.4.0+) introduces a powerful Dynamic Parameter System designed to allow real-time configuration of running matrix applications.

This system bridges the gap between the C++ backend and the new CubeWebapp frontend, allowing applications to expose adjustable parameters (like speed, color, spawn rate, etc.) automatically to the web interface.

Core Concepts

The parameter system consists of several levels:

  1. AnimationParams: A C++ class that holds the schema and current values for an application’s parameters.

  2. MatrixApplication Integration: The base class for all applications seamlessly handles incoming network requests for parameter updates and queries.

  3. Protobuf Messages: Data definition language used for transmitting schema and values over WebSockets.

  4. CubeWebapp UI: The web frontend that dynamically generates UI controls based on the application’s configuration.

How to Use

To expose parameters in your custom application, follow these steps:

1. Register Parameters in the Constructor

Within your application’s constructor (derived from CubeApplication or MatrixApplication), register the parameters you wish to expose. They must be registered before the application’s main loop begins.

MyApplication::MyApplication() : CubeApplication("MyApplication") {
    // Register an integer parameter
    params.registerIntParam("Speed", "Animation Speed", 1, 10, 5);

    // Register a float parameter
    params.registerFloatParam("Gravity", "Gravity Multiplier", 0.1f, 2.0f, 1.0f);

    // Register a boolean parameter
    params.registerBoolParam("EnableSparkles", "Enable Sparkles", true);

    // Register an enum (dropdown) parameter
    params.registerEnumParam("ColorMode", "Color Mode", {"Rainbow", "Solid", "Pulse"}, "Rainbow");
}

2. Read Parameters in Your Loop

During your application’s tick() or main rendering loop, retrieve the current values. Accesses are thread-safe and will immediately reflect any changes made by the user in the CubeWebapp UI.

void MyApplication::tick() {
    int speed = params.getIntParam("Speed");
    float gravity = params.getFloatParam("Gravity");
    bool sparkles = params.getBoolParam("EnableSparkles");
    std::string mode = params.getStringParam("ColorMode");

    // Use parameters to drive animation
    // ...
}

Supported Parameter Types

  • Integer: registerIntParam(id, name, min, max, default) - Rendered as a slider in the UI.

  • Float: registerFloatParam(id, name, min, max, default) - Rendered as a fine-grained slider.

  • Boolean: registerBoolParam(id, name, default) - Rendered as a checkbox.

  • String/Enum: registerEnumParam(id, name, options_vector, default) - Rendered as a dropdown selector.

Presets

The CubeWebapp frontend includes a robust preset management system. Users can save combinations of parameter configurations as JSON files across different applications. When a preset is loaded, the frontend transmits the saved values to the active C++ application automatically, instantly updating its state without requiring a restart.

Network Communication

Parameter synchronization happens transparently via the matrixserver network protocol. When the CubeWebapp requests the active schema, the server queries the running application via an appParamValues message. Parameter changes from the web interface are dispatched as setAppParam commands, which safely update the AnimationParams object in the C++ backend.