The general philosophy of cactbot is that future updates of cactbot will update files inside the ui directory, and any user configuration should go in files in the user directory. This will prevent your changes from being clobbered during future cactbot updates.
All cactbot UI modules can load user settings from the user/ directory. The user/ directory already includes some example configuration files, which you can rename and use. For example the user/raidboss-example.js can be renamed to user/raidboss.js and edited to change the behaviour of the raidboss module.
If you want to do it yourself, then create a user/<name>.css or a user/<name>.js file, where <name> is the name of the UI module, such as raidboss or jobs.
After making any changes to these files, pressing the “Reload overlay” button for the appropriate cactbot in ACT’s OverlayPlugin settings will apply the changes.
The OverlayPlugin config panel has a text field for “Custom User Config Directory”, which lets you specify where your cactbot/user directory. If you don’t specify one, then it will first try to use ../../user relative to the overlay URL. If that doesn’t exist, it will then look for ../cactbot/user/ relative to the CactbotOverlay.dll.
The user/<name>.css file can change positions, sizes, colors, etc. for components of
the UI module. See the ui/<name>/<name>.css to find the names of things you can modify.
For example in ui/raidboss/raidboss.css, you see the
#popup-text-container and #timeline-container which can be changed via user/raidboss.css
to different positions as desired. The size and color of info text alerts can also be changed by
making a CSS rule for the .info-text class such as below:
.info-text {
font-size: 200%;
color: rgb(50, 100, 50);
}
The user/<name>.js file can set options to customize how the UI module works. The
options that can be changed are documented in the Options section at the top of the
ui/<name>/<name>.js file. For example in ui/raidboss/raidboss.js,
you see the BarExpiresSoonSeconds option which controls when timeline bars should be
highlighted. You can change that option from the default value to 5 seconds by editing
user/raidboss.js to say:
Options.BarExpiresSoonSeconds = 5
To disable a text/sound alert that comes built-in for a fight, find the trigger’s id in the files in
ui/raidboss/data/triggers. Then add the id to the Options.DisabledTriggers
in the user/raidboss.js file, such as:
Options.DisabledTriggers = {
'O4S1 Fire III': true,
}
If you want to customize when and what triggers say, there are a few options. For example, you want to change how the twisters callout works in ucob. To start, look up the id for the trigger in the triggers file. This is UCU Twisters. The zoneRegex for this zone is at the top of this file, and is zoneRegex: /The Unending Coil Of Bahamut \(Ultimate\)/,.
Add the following code to your user/raidboss.js file. If you have other existing disabled triggers or triggers, you will need to splice these additions in.
This option disables the original twisters trigger and adds a second trigger that just says Panic! instead. The gives you maximum flexibility, but the downside of this approach is that if the trigger regex ever changes, then when cactbot updates, you will need to update your custom trigger as well. Note that this is fairly unlikely.
Options.DisabledTriggers = {
'UCU Twisters': true,
};
Options.Triggers = [
{
zoneRegex: /The Unending Coil Of Bahamut \(Ultimate\)/,
triggers: [
{
regex: /:26AA:Twintania starts using/,
alarmText: 'Panic!',
},
],
},
];
The other option is to use per trigger options. These override the existing trigger behaviors, without needing to disable the original trigger.
The user/raidboss-example.js file has some examples of how to do this.
If you wanted to change the twister cast to say Panic! as above, you would do the following:
Options.PerTriggerOptions = {
'UCU Twisters': {
'AlertText': '',
'AlarmText': 'Panic!',
},
};
The fields that are valid on PerTriggerOptions are the following:
GroupSpeechAlert: boolean, turn on or off group tts textsSpeechAlert: boolean, turn on or off tts textsSoundAlert: boolean, turn on or off soundsTextAlert: boolean, turn on or off on screen text
AlarmText: function, the string to show as alarm textAlertText: function, the string to show as alert textInfoText: function, the string to show as info textTTSText: function, the string to play as tts textGroupTTSText: function, the string to play for group tts textSoundOverride: function, the path to the sound to play for this triggerVolumeOverride: function, 0-1 value for how loud to play the sound atAll of the functions in the above list override the previous values if they exist. So, if the trigger has an alertText entry and the option specifies an AlertText (even if empty), then it will not play. This is what the example does for twisters above.
If you dislike the built-in sound info, alert, and alarm noises that cactbot uses by default and would prefer to use text to speech (tts), you can set a global option by including this line in your user/raidboss.js file:
// Including this line will make any trigger with text to speech use that instead of other
// noises.
Options.SpokenAlertsEnabled = true;
// If you don't like the on screen text, you can turn that off with this line too:
Options.TextAlertsEnabled = false;
See this options documentation for a full list of options and how to configure text, sound, and tts options on a per trigger basis.
To add a sound alert that can be activated in any zone, for example, add the following to user/raidboss.js:
Options.Triggers = [
{ zoneRegex: /./,
triggers: [
// Trick Attack used.
{ regex: /:\y{Name}:\y{AbilityCode}:Trick Attack:/,
sound: '../../resources/sounds/WeakAuras/RoaringLion.ogg',
},
.. other triggers here ..
],
},
// .. other zones here ..
]
A more sophisticated example that shows an alert message after a 1 second delay, but only when the player’s character name appears in the FFXIV log message:
Options.Triggers = [
// .. other zones here ..
{ zoneRegex: /./,
triggers: [
// .. other triggers here ..
{ regex: /:(\y{Name}) gains the effect of Forked Lightning from/,
delaySeconds: 1,
alertText: 'Forked Lightning: Get out',
condition: function(data, matches) { return matches[1] == data.me; },
},
// .. other triggers here ..
],
},
// .. other zones here ..
]
If you’re familiar with regular expressions you’ll note the the \y{Name} and
\y{AbilityCode} are unfamiliar. These are extensions provided by cactbot for
convenience to avoid having to match against all possible unicode characters
or to know the details of how the FFXIV ACT plugin writes things.
The set of extensions are:
\y{Float}: Matches a floating-point number, accounting for locale-specific encodings.\y{Name}: Matches any character or ability name (including empty strings which the FFXIV ACT plugin can generate when unknown).\y{ObjectId}: Matches the 8 hex character object id in network log lines.\y{AbilityCode}: Matches the FFXIV ACT plugin’s format for the number code of a spell or ability.\y{TimeStamp}: Matches the time stamp at the front of each log event such as [10:23:34.123].\y{LogType}: Matches the FFXIV ACT plugin’s format for the number code describing the type of log event, found near the front of each log event.See this cactbot-user git repo for more examples.
To build a cactbot ui, you need to make a .html file and point cactbot at it. There are a number of helpful things in the resources/ directory.
Include the resources/defaults.css file to get some of the default
look and feel of other cactbot uis, then use the .text class on any HTML elements which contain
text. You may add the .hide class to elements you do not want shown, and remove it when they
should be visible.
Include the resources/resize_handle.css and resources/resize_handle.js files to give visual feedback to the user when the module is unlocked for moving and resizing.
Include the resources/unicode.js file to use unicode categories in regular expressions in order to support non-english characters.
There are a number of web components that provide widgets for building your ui, including the
timerbar, timerbox or
resourcebar. Include the file and then instatiate it by making an
element of that type, such as <timer-bar></timer-bar> or <resource-bar></resource-bar>.
The set of Javascript events that can be listened for via document.addEventListener is found
in CactbotOverlay/JSEvents.cs. The public fields of each event
type will be members of the event’s detail. See the
ui/test/test.html ui module for a simple example of
listening to and using the Javascript events.