C++ Creative Scripts

Script packages that support Creative can load a native Windows DLL as well as a Python Creative script. Use the CreativeSDK.hpp, CreativeABI.h, and example CMake project supplied for that script package. This is a Creative extension, with different entry points from a standalone Helios CV C++ script.

Minimal Script

cpp
#include "CreativeSDK.hpp"

class MyCreativeScript final : public Creative::Script {
public:
    void iterate(const Creative::FrameContext& frame) override {
        if (frame.actual(Creative::BUTTON_14) > 0.0) {
            frame.controller().setButton(Creative::BUTTON_1, 100.0);
            frame.controller().setAxis(Creative::STICK_1_X, 37.5);
        }
    }
};

CREATIVE_EXPORT_SCRIPT(MyCreativeScript)

scan() and iterate() run once per frame, in the order shown in the package’s Creative scripts list. Implement the callbacks you need; ordinary output changes belong in iterate().

Build and Load

From the supplied Creative example directory, use its CMake project with a compatible Windows x64 C++20 toolchain and CMake 3.28 or newer:

powershell
cmake -S . -B build -A x64
cmake --build build --config Release

Copy the resulting creative_script.dll into the script package’s userdata/creative folder and add creative_script to its Creative scripts list. If both creative_script.py and creative_script.dll exist, the Python file takes precedence. Use a distinct name when testing the DLL alongside a Python version.

Read and Write Controls

  • frame.actual(id) reads the input value; frame.value(id) reads the reported value.
  • frame.controller().setButton(id, value) sets BUTTON_1 through BUTTON_17 using 0..100.
  • frame.controller().setAxis(id, value) sets the four STICK_* axes using -100..100, preserving fractional values.

BUTTON_18 through BUTTON_21 can be read but are not Creative output controls. They are not alternate stick identifiers. Use named constants from the SDK.

Frames and Live State

frame.frame() provides the current BGR8 image. Its pixels are writable for the callback. Changes in scan() are visible to later processing; changes in iterate() are visible to later Creative scripts and the displayed frame. Do not retain the view or pixel pointers after the callback.

frame.liveState("state_name") accesses package-specific live state. Use the package’s documented state and field names with the typed boolean, integer, number, and string readers and their set... counterparts. Primitive arrays have typed array accessors. Only use fields the package documents for Creative extensions.

Troubleshooting

  • Build against the SDK supplied for the package and keep its headers together.
  • Confirm the DLL is x64 and uses CREATIVE_EXPORT_SCRIPT.
  • Check the filename in the Creative list and whether a Python file with the same name is taking precedence.
  • Test the minimal example before adding optional libraries or package-specific state.
  • Review the package’s log or Output Panel when loading or a callback fails.
← PreviousHelper Reference