-
Notifications
You must be signed in to change notification settings - Fork 52
Scripts
Scripts are written in Lua and allow you to create new effects. Lua is a very easy to learn, dynamically typed language, meaning writing and testing scripts will be pretty straightforward even for newbies.
Scripts are loaded from the 'Scripts' folder in the directory where you have saved MSIRGB. Any file with a .lua extension in that folder (subdirectories excluded) will be loaded. The name of the script that will appear on MSIRGB is the file name without extension. As a convention, you should use upper camel case and spaces between words for your file names, e.g. 'Hue Wheel', 'Single Colour', 'Edgy Rainbow'.
Scripts, when enabled, run on Windows startup, so you don't have to enable them every time.
It is recommended that scripts set all LED settings on startup because there are no guarantees on their state at that point.
I'm open to pull requests/issues for new scripting functionality.
Scripts are loaded into a Lua 5.2 environment with all of its modules loaded. This means you can use, e.g., require to load third-party code (like Lua bindings for C code) to improve your scripts.
Additionally, there is one extension function to the os package:
os.sleep(number ms)This function pauses the Lua thread for the number of milliseconds specified in 'ms'. 'ms' must be a positive number. Execution stops if an invalid value is passed.
The 'Lighting' module provides the API to control the LEDs. Here follows documentation for each function:
Lighting.SetAllEnabled(boolean enabled)(Introduced in: 1.0.0) This function allows you to enable or disable the LEDs connected to the motherboard. As far as I know, this controls both motherboard and header LEDs.
boolean Lighting.BatchBegin()(Introduced in: 1.1.0) A call to this function enables batching of updates to the LEDs. After calling it, any update to the LEDs is stored and only applied when Lighting.BatchEnd is called. This allows for optimizing the number of driver calls, and therefore, the performance of the script.
Batching calls is encouraged.
This function returns true if it successfully started batching calls, and false if it is already batching calls.
(Release 2.0.0 onwards) This function no longer returns. If BatchBegin is called incorrectly, execution of the script is stopped and an error is thrown. The correct signature of this function is: Lighting.BatchBegin().
boolean Lighting.BatchEnd()(Introduced in: 1.1.0) A call to this function disables batching of updates to the LEDs. A call to this function commits all updates to the LEDs after Lighting.BatchBegin was called.
See Lighting.BatchBegin for why it's encouraged to use this function.
This function returns true if it successfully disabled batching and committed changes, and false if batching calls was not enabled.
(Release 2.0.0 onwards) This function no longer returns. If BatchEnd is called incorrectly, execution of the script is stopped and an error is thrown. The correct signature of this function is: Lighting.BatchEnd().
Lighting.SetColour(number index, number r, number g, number b)(Introduced in: 1.0.0) This function sets the colour of one of the 4 built-in colours.
'index' can be a number between 1 and 4, inclusive. 'r', 'g', 'b' are the R, G, B values between 0 and 255.
Execution stops if any of the arguments is invalid.
Any call to this function that succeeds automatically turns on the LEDs.
(Release 2.0.0 onwards) This function no longer accepts values between 0 and 255. Previously these values were converted to a 12-bit colour internally, but from 2.0.0 onwards this no longer happens. The function will now only accept values between 0 and 15 (0x0 to 0xf), i.e. which fit in 4 bits.
number, number, number Lighting.GetColour(number index)(Introduced in: 1.0.0) This function gets the current colour of one of the 4 built-in colours.
'index' can be a number between 1 and 4, inclusive.
The function returns the R, G, B values (0-255) in that order.
Execution stops if 'index' is invalid.
(Release 2.0.0 onwards): This function no longer returns values in the range 0-255. Instead, it returns values in the range 0 to 15. See documentation for Lighting.SetColour for details.
bool Lighting.GetDefaultColourChannelsInvertedSetting()(Introduced in: 2.4.0) This function returns the default setting for whether colour channels are inverted for this motherboard by default.
Returns a boolean, where true means all 3 channels are inverted, and false where none is.
void Lighting.SetRChannelInverted(boolean inverted)(Introduced in: 2.4.0) This function inverts the R channel on the chip. This allows you to get more vivid colours.
void Lighting.SetGChannelInverted(boolean inverted)(Introduced in: 2.4.0) This function inverts the G channel on the chip. This allows you to get more vivid colours.
void Lighting.SetBChannelInverted(boolean inverted)(Introduced in: 2.4.0) This function inverts the B channel on the chip. This allows you to get more vivid colours.
boolean Lighting.IsRChannelInverted()(Introduced in: 2.4.0) This function returns whether the R channel is currently inverted.
boolean Lighting.IsGChannelInverted()(Introduced in: 2.4.0) This function returns whether the G channel is currently inverted.
boolean Lighting.IsBChannelInverted()(Introduced in: 2.4.0) This function returns whether the B channel is currently inverted.
boolean Lighting.SetBreathingModeEnabled(boolean enabled)(Introduced in: 1.0.0) This function sets the state of the breathing mode.
Breathing mode and flashing mode are exclusive, and the latter will override the former. If flashing mode is enabled at the time of the call, this function will fail and return false, otherwise it returns true.
Any call to this function that succeeds automatically turns on the LEDs.
boolean Lighting.IsBreathingModeEnabled()(Introduced in: 1.0.0) This function returns whether breathing mode is currently enabled.
Lighting.SetFlashingSpeed(number flashingSpeed)(Introduced in: 1.0.0) This function sets the flashing mode speed.
Valid values for 'flashingSpeed' range from 0 to 6, inclusive. A value of '0' means that flashing mode will be disabled. A value of '1' means fastest flashing, while a value of '6' means slowest flashing.
This function will disable breathing mode if it was previously enabled.
Execution stops if 'flashingSpeed' is invalid.
Any call to this function that succeeds automatically turns on the LEDs.
number Lighting.GetFlashingSpeed()(Introduced in: 1.0.0) This function returns the current flashing mode speed. Speeds are as described above for 'SetFlashingSpeed'.
Lighting.SetStepDuration(number stepDuration)(Introduced in: 1.0.0) This function sets the value for step duration.
Step duration is the interval of time between changes in any of the 4 chosen colours.
It is in an arbitrary time unit. Valid values range from 0 to 511, inclusive.
Execution stops if 'stepDuration' is invalid.
Any call to this function that succeeds automatically turns on the LEDs.
number Lighting.GetStepDuration()(Introduced in: 1.0.0) This function returns the current step duration.
This module implements often-used utilities for dealing with different colour spaces.
number, number, number Lighting.ColourUtils.HSVtoRGB(number hue, number saturation, number value)(Introduced in: 2.1.0) This function converts a colour in HSV colour space to RGB. hue, saturation, and value are in the range [0, 1], and it returns RGB values also in the range [0, 1].
If one or more arguments are invalid, script execution is stopped and an error is printed on the script log.
The 'Aida64' module provides a way for scripts to communicate with AIDA64 and query hardware sensor and system data to create effects based on them. Some version of AIDA64 must be installed and running for this module to work, and "Enable writing sensor values to WMI" must be enabled under "External Applications" in AIDA64 preferences. Here follows the documentation for each function from this module. Keep in mind that this module is only available starting in release 1.1.0.
boolean Aida64.IsInstalledAndRunning()(Introduced in: 1.1.0) This function returns true if AIDA64 is installed and running, and false if not. It also returns false if writing sensor values to WMI is not enabled in AIDA64.
number/boolean Aida64.GetSensorValue(string label)(Introduced in: 1.1.0) This function returns the value (as a number) associated to some sensor label. Possible sensor labels are immediately below. If the label is not valid or AIDA64 is not running, execution of the script stops. If you're running a trial version of AIDA64 and the sensor label is not available in that version, or the label is valid but does not apply to this specific hardware (for instance, CPU core info for core > number of cores of your CPU), this function returns false.
Possible sensor labels:
| Label (in regex pattern) | Sensor |
|---|---|
| SCPUCLK | CPU Clock (MHz) |
| SCC-1-([1-9][0-9]*) | CPU Core #n Clock (MHz), where n is the regex pattern that matches any positive integer without leading zeros. Example: SCC-1-1 for core #1, SCC-1-2 for core #2, ... |
| SMEMCLK | Memory Clock (MHz) |
| SCPUUTI | CPU Utilization (percentage) |
| SCPU([1-9][0-9]*)UTI | CPU n Utilization (percentage), where n is the regex pattern that matches any positive integer without leading zeros. Example: SCPU1UTI for CPU #1 |
| SMEMUTI | Memory Utilization (percentage) |
| SVIRTMEMUTI | Virtual Memory Utilization (percentage) |
| SDSK([1-9][0-9]*)ACT | Disk n Activity (percentage), where n is the regex pattern that matches any positive integer without leading zeros. Example: SDSK1ACT for disk #1 |
| SGPU([1-9][0-9]*)CLK | GPU n Clock (MHz), where n is the regex pattern that matches any positive integer without leading zeros. Example: SGPU1CLK for GPU #1 |
| SGPU([1-9][0-9]*)MEMCLK | GPU n Memory Clock (MHz), where n is the regex pattern that matches any positive integer without leading zeros. Example: SGPU1MEMCLK for GPU #1 |
| SGPU([1-9][0-9]*)UTI | GPU n Utilization (percentage), where n is the regex pattern that matches any positive integer without leading zeros. Example: SGPU1UTI for GPU #1 |
| SVMEMUSAGE | Video Memory Utilization (percentage) |
| SGPU([1-9][0-9]*)USEDDEMEM | GPU n Used Dedicated Memory (MB), where n is the regex pattern that matches any positive integer without leading zeros. Example: SGPU1USEDDEMEM for GPU #1 |
| SGPU([1-9][0-9]*)USEDDYMEM | GPU n Used Dynamic Memory (MB), where n is the regex pattern that matches any positive integer without leading zeros. Example: SGPU1USEDDYMEM for GPU #1 |
| TMOBO | Motherboard temperature (degree celsius) |
| TCPU | CPU temperature (degree celsius) |
| TCPUDIO | CPU Diode temperature (degree celsius) |
| TGPU([1-9][0-9]*)DIO | GPU n Diode temperature (degree celsius), where n is the regex pattern that matches any positive integer without leading zeros. Example: TGPU1DIO for GPU #1 |
| THDD([1-9][0-9]*) | HDD temperature (degree celsius), where n is the regex pattern that matches any positive integer without leading zeros. Example: THDD1 for HDD #1. This label is not supported on trial versions of AIDA64. |
| FCPU | CPU fan speed (RPM) |
| FCHA([1-9][0-9]*) | Chassis n fan speed (RPM), where n is the regex pattern that matches any positive integer without leading zeros. Example: FCHA1 for chassis fan #1 |
| FGPU([1-9][0-9]*) | GPU n fan speed (RPM), where n is the regex pattern that matches any positive integer without leading zeros. Example: FGPU1 for GPU fan #1 |
| VCPU | CPU Core voltage (V). This label is not supported on trial versions of AIDA64. |
| VGPU([1-9][0-9]*) | GPU n Core voltage (V), where n is the regex pattern that matches any positive integer without leading zeros. Example: VGPU1 for GPU #1 |
| PCPUPKG | CPU Package power comsumption (W) |
| PCPUVDD | CPU VDD power comsumption (W) |
| PCPUVDDNB | CPU VDDNB power comsumption (W) |
| PGPU([1-9][0-9]*)TDPP | GPU n power comsumption (percentage, in relation to TDP), where n is the regex pattern that matches any positive integer without leading zeros. Example: PGPU1TDPP for GPU #1 |
In order to debug scripts, you can click on 'Open script log' in the 'Scripts' group to open the script log containing errors, warnings and other information from the script. The script can also call 'print' to print information to the log.