Advanced Cactbot Usage (2024)

1. Configuring UI Modules
2. Customizing Appearance
3. Customizing Behavior
4. Text To Speech
5. Adding Custom Triggers
6. Regular Expression Extensions
7. Writing a cactbot UI Module

Configuring UI modules

The general philosophy of cactbot is that future updates of cactbot will update files insidethe ui directory, and any user configuration should go in files in the user directory. Thiswill 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.jsand 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>.jsfile, where <name> is the name of the UI module, such as raidboss orjobs.

After making any changes to these files, pressing the “Reload overlay” button for theappropriate cactbot in ACT’s OverlayPlugin settings will apply the changes.

User Directory

The OverlayPlugin config panel has a text field for “Custom User Config Directory”, whichlets you specify where your cactbot/user directory. If you don’t specify one, thenit will first try to use ../../user relative to the overlay URL. If that doesn’texist, it will then look for ../cactbot/user/ relative to the CactbotOverlay.dll.

Customizing Appearance

The user/<name>.css file can change positions, sizes, colors, etc. for components ofthe 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.cssto different positions as desired. The size and color of info text alerts can also be changed bymaking a CSS rule for the .info-text class such as below:

.info-text { font-size: 200%; color: rgb(50, 100, 50);}

Customizing Behavior

The user/<name>.js file can set options to customize how the UI module works. Theoptions that can be changed are documented in the Options section at the top of theui/<name>/<name>.js file. For example in ui/raidboss/raidboss.js,you see the BarExpiresSoonSeconds option which controls when timeline bars should behighlighted. You can change that option from the default value to 5 seconds by editinguser/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 inui/raidboss/data/triggers. Then add the id to the Options.DisabledTriggersin the user/raidboss.js file, such as:

Options.DisabledTriggers = { 'O4S1 Fire III': true,}

Per Trigger Options

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\)/,.

Option 1: disable the original, write your own

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!', }, ], },];

Option 2: per trigger options to modify/override behavior

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 texts
• SpeechAlert: boolean, turn on or off tts texts
• SoundAlert: boolean, turn on or off sounds

• TextAlert: boolean, turn on or off on screen text

• AlarmText: function, the string to show as alarm text
• AlertText: function, the string to show as alert text
• InfoText: function, the string to show as info text
• TTSText: function, the string to play as tts text
• GroupTTSText: function, the string to play for group tts text
• SoundOverride: function, the path to the sound to play for this trigger
• VolumeOverride: function, 0-1 value for how loud to play the sound at

All 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.

Text To Speech

If you dislike the built-in sound info, alert, and alarm noises that cactbot uses by default and wouldprefer to use text to speech (tts), you can set a global option by including this linein 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 andhow to configure text, sound, and tts options on a per trigger basis.

Adding Custom Triggers

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, butonly 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 ..]

Regular Expression Extensions

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 forconvenience to avoid having to match against all possible unicode charactersor 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.

Writing a cactbot UI module

To build a cactbot ui, you need to make a .html file and point cactbot at it. There are anumber of helpful things in the resources/ directory.

Include the resources/defaults.css file to get some of the defaultlook and feel of other cactbot uis, then use the .text class on any HTML elements which containtext. You may add the .hide class to elements you do not want shown, and remove it when theyshould be visible.

Include the resources/resize_handle.css andresources/resize_handle.js files to give visual feedback to theuser when the module is unlocked for moving and resizing.

Include the resources/unicode.js file to use unicode categories inregular expressions in order to support non-english characters.

There are a number of web components that provide widgets for building your ui, including thetimerbar, timerbox orresourcebar. Include the file and then instatiate it by making anelement 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 foundin CactbotOverlay/JSEvents.cs. The public fields of each eventtype will be members of the event’s detail. See theui/test/test.html ui module for a simple example oflistening to and using the Javascript events.