FFXIV JavaScript Raiding Overlay
Branch: master
Clone or download

README.md

cactbot (ffxiv raiding overlay)

build status

  1. About
  2. Installing
  3. Building From Source
  4. UI Module Overview
  5. Cactbot Customization
  6. Supported Languages

About

cactbot is an ACT overlay that provides raiding tools for Final Fantasy XIV. This project is an overlay plugin for hibiyasleep's OverlayPlugin which itself is a plugin for Advanced Combat Tracker.

cactbot provides these modules:

  • raidboss: built-in timelines and triggers:

timeline screenshot triggers screenshot

  • oopsyraidsy: mistake and death reporting

oopsy screenshot

  • jobs: condensed gauges with buff and proc tracking

rdm jobs screenshot

  • eureka: Eureka NM tracking map

eureka screenshot

  • fisher: Fishing cast time tracking

fisher screenshot

  • dps: extra features for dps meters

xephero screenshot

Video Examples

Installing

Dependencies

Install .NET Framework version 4.6 or above.

You must have DirectX 11 enabled for Final Fantasy XIV.

Install the 64-bit version of Advanced Combat Tracker, if you have not already.

Download and add the most recent version of ravahn's FFXIV ACT plugin to ACT. You must enable parsing from the network and make sure that ACT is not firewalled. Make sure the settings for the FFXIV plugin have the "Include HP for Triggers" button checked. This is under Plugins -> FFXIV Settings -> Parse Options.

You must have the latest x64 version of the hibiyasleep OverlayPlugin installed and working in ACT. You must use the hibiyasleep version of OverlayPlugin and not the original RainbowMage version, as cactbot depends on several features of that version.

fflogs has a good guide to setting up ACT and OverlayPlugin if you prefer video or would like more instructions on how to set these two tools up properly.

Installing cactbot

  1. Find the latest release and download the cactbot-version-number.zip file for that release. (You likely do not want either of the Source zip files.)

  2. Right click on the zip file, go to properties. In the bottom right corner of the properties menu, click "Unblock", and then "OK" to close the menu.

  3. Unzip the release zip file. (If there is no OverlayPlugin\addons\CactbotOverlay.dll file, you downloaded the wrong zip file.)

  4. Close ACT, if it's still running.

  5. Copy the OverlayPlugin\ folder from inside of the unzipped folder into your existing C:\...\Advanced Combat Tracker\ folder.

  6. If you already have an existing OverlayPlugin\ folder, you will be prompted to confirm if you want to merge files with existing files. Click the Do this for the next N conflicts checkbox and then the Move and Replace checkbox. If you end up with an OverlayPlugin\OverlayPlugin\ folder then you have done something wrong.

    The final directory structure should look something like this:

    - C:\...\Advanced Combat Tracker\
      - Advanced Combat Tracker.exe
      - FFXIV_ACT_Plugin.dll
      - OverlayPlugin\
         - OverlayPlugin.dll
         - OverlayPlugin.Common.dll
         - OverlayPlugin.Core.dll
         - etc etc OverlayPlugin files
         - addons\
            - CactbotOverlay.dll
         - cactbot\
            - ui\
            - resources\
            - user\
    

    Note: The cactbot\ folder does not have to be located inside of the OverlayPlugin directory, but that is where it comes by default as part of a cactbot release zip file. It can be located anywhere on disk as long as the entire cactbot\ folder is kept together.

    Note: The OverlayPlugin\ subdirectory can also be named whatever you like.

  7. Restart ACT.

  8. Now add a new overlay in the OverlayPlugin tab in ACT, and choose cactbot as the type.

  9. In the URL field, browse to an html file to load.

    ui/test/test.html is a good place to start to make sure everything is set up properly.

For more instructions about adding and configuring cactbot overlays, see the Adding Overlay Modules section.

Potential errors and workarounds

If you get an error that it can't find FFXIV_ACT_Plugin.dll, make sure the FFXIV_ACT_Plugin.dll is in the same directory as Advanced Combat Tracker.exe.

If you get an error in the OverlayPlugin console similar to Exception in SendFastRateEvents: Method not found: 'Void RainbowMage.HtmlRenderer.Renderer.ExecuteScript(System.String)'. then you are still using the RainbowMage version of OverlayPlugin and need to upgrade to the latest x64 full version of the hibiyasleep OverlayPlugin instead.

If you get an error on the OverlayPlugin console similar to Uncaught TypeError: window.OverlayPluginApi.overlayMessage is not a function, then you are using an earlier version of the OverlayPlugin. You need to be using the latest x64 full version of the hibiyasleep OverlayPlugin.

If you get an error in the OverlayPlugin console similar to Error: (overlay): C:\Program Files (x86)\Advanced Combat Tracker\OverlayPlugin\addons\CactbotOverlay.dll: System.IO.FileNotFoundException: Could not load file or assembly 'Newtonsoft.Json, Version=10.0.0.0, Culture=neutral, PublicKeyToken=30ad4fe6b2a6aeed' or one of its dependencies. The system cannot find the file specified. then you have likely installed the wrong version of the OverlayPlugin. Please reinstall the latest x64 full version of the hibiyasleep OverlayPlugin.

If you get a CAS policy error on starting the OverlayPlugin, such as "An attempt was made to load an assembly from a network location which would have caused the assembly to be sandboxed in previous version of the .NET Framework." then this means that you have forgotten to unblock some/all of your DLLs (either hibiyasleep or cactbot). First, stop ACT. Then, unblock everything; the easiest way is to unblock the original zip file and re-extract rather than unblocking every file individually. Finally, restart ACT again.

If you get an overlay plugin error similar to Error: (overlay): Exception in SendFastRateEvents: Could not load file or assembly 'FFXIV_ACT_Plugin, Version=(version), Culture=neutral, PublicKeyToken=null' or one of its dependencies. The system cannot find the file specified. then you likely need to unblock the ffxiv plugin. See the instructions above for unblocking DLLs.

If you get an ACT dialog that says "Invalid Plugin" and "This assembly does not have a class that implements ACT's plugin interface", then you are loading the plugin incorrectly. Cactbot is an overlay and not a direct ACT plugin. Plugins like FFXIV_ACT_PLUGIN.dll and OverlayPlugin.dll are ACT plugins and are loaded via ACT -> Plugins -> Plugin Listing -> Add/Enable Plugin. Cactbot is an overlay plugin. You load it via going to Plugins -> OverlayPlugin.dll -> New. See the adding overlay modules section for more details.

If triggers or pieces of the UI do not work, ensure that "Disable Parsing from Network Data" is not checked in the FFXIV plugin settings. Network data is required for accurate trigger timing.

Building from source

Follow all the steps above for installing cactbot first.

  1. Follow the instructions in the dummy.txt file in CactbotOverlay/ThirdParty/OverlayPlugin.
  2. Follow the instructions in the dummy.txt file in CactbotOverlay/ThirdParty/ACT.
  3. Open the solution in Visual Studio (tested with Visual Studio 2017).
  4. Build for "Release" and "x64".
  5. The plugin will be built as bin/x64/Release/CactbotOverlay.dll.
  6. Copy the plugin to the Advanced Combat Tracker\OverlayPlugin\addons\ directory

UI module overview

The ui/ directory contains cactbot's ui modules. If you installed cactbot following the instructions above, this will most likely be C:\...\Advanced Combat Tracker\OverlayPlugin\cactbot\ui.

Each cactbot ui module should be added as a separate overlay. See the Adding Overlay Modules section for more details about setup.

raidboss module

To use this module, point cactbot at ui/raidboss/raidboss.html.

This module provides a visual timeline of upcoming events in a fight, as well as text and audio notifications to help increase raid awareness. Text and sound alerts can be based on the fight timeline, or come from log messages that occur in the game, similar to ACT's "Custom Triggers". The module is designed to look and feel similar to the BigWigs Bossmods addon for World of Warcraft.

Fight timelines are provided in files designed for the ACT Timeline plugin, documented here with some extensions.

There are three levels of text alerts, in order of escalating importance: info, alert, and alarm. Text messages will be in one of these, and more important levels are larger and more eye grabbing colors. Text-to-speech can be configured if you prefer that over on screen text.

Timeline files are found in ui/raidboss/data/timelines. Triggers for text and sound alerts are found in ui/raidboss/data/triggers.

In this screenshot, the raidboss module is highlighted, with the timeline circled in red, and the text alerts circled in yellow, with an alert-level text message visible.

raidboss screenshot

oopsyraidsy module

To use this module, point cactbot at ui/oopsyraidsy/oopsyraidsy.html.

This module provides mistake tracking and death reporting. Oopsy raidsy is meant to reduce the time wasted understanding what went wrong on fights and how people died. During the fight, only a limited number of mistakes are shown (to avoid clutter), but afterwards a full scrollable list is displayed.

When somebody dies, the last thing they took damage from is listed in the log. For example, if the log specifies: "💀 Poutine: Iron Chariot (82173/23703)" this means that Poutine most likely died to Iron Chariot, taking 82173 damage and having 23703 health at the time. The health value itself is not perfect and may be slightly out of date by a ~second due to a hot tick or multiple simultaneous damage sources.

When mistakes are made that are avoidable, oopsy logs warning (⚠️) and failure (🚫) messages, explaining what went wrong.

Mistake triggers are specified for individual fights in the ui/oopsyraidsy/data folder.

oopsy screenshot

jobs module

To use this module, point cactbot at ui/jobs/jobs.html

This module provides health, mana, and tp bars, as well as icons and timer bars for big raid buffs such as The Balance and Trick Attack. It also features a food buff warning to keep up your food buff when leveling or raiding, and a visual pull countdown.

It has more fleshed out support for some jobs but is strongly a Work In Progress for others.

  • Red Mage: Shows white/black mana, tracks procs for Verstone, Verfire and Impact, and shows the state of the melee combo in progress.
  • Warrior: Shows the beast amount, and tracks the remaining Storm's Eye buff time in gcds.
  • Monk: Shows chakra count, remaining greased lightning time, and tracks monk buffs and debuffs.

In this screenshot, the jobs module is highlighted for the Red Mage job. The health and mana bars, as well as Red Mage white/black mana tracking is circled in purple, with the large raid buff tracking pointed to beside it in orange. The first step of the melee combo has been executed, which is displayed as the yellow box above the health bar. The proc tracking is circled below in green.

jobs screenshot

eureka module

To use this module, point cactbot at ui/eureka/eureka.html

This module provides automatic tracking of NMs that are popped or have been killed. It shows gales/night timers and any local tracker link that has been pasted in chat. Any flags in chat are also temporarily included on the map.

It currently does not read the tracker information directly. However, if you click on the left/red "Copy killed NMs" button in the tracker to copy the list of currently dead NMs, you can paste it in game, e.g. /echo ★ NMs on cooldown: Serket (7m) > Julika (24m) > Poly (54m)

If you do not see the emoji, make sure you have installed this Windows update.

eureka screenshot

fisher module

To use this module, point cactbot at ui/fisher/fisher.html

When you cast your line at a fishing hole, this module keeps track of when you reel in particular fish so that you know what you might be getting when you hook it.

fishing screenshot

dps meters

cactbot can be used with any dps meter overlay designed for OverlayPlugin's miniparse addon, with the option to build out more features through cactbot's additional Javascript APIs. cactbot also auto-stops fights on wipes, so you can configure ACT's fight time to infinity.

The xephero dps meter is based on the same dps meter built for miniparse, with the additional ability to do per-phase dps tracking, displayed in additional columns. In the screenshot below the phases are named B1, B2, B3. These autogenerate from dungeon bosses, but could be used to differentiate raid fight phases.

xephero screenshot

The rdmty dps meter is based on the same dps meter for miniparse, and updated for Stormblood jobs and recolored to match fflogs.

rdmty screenshot

pull counter module

This small module sticks the current pull count for raiding bosses on screen. This is primarily for folks who stream a lot and want to review video footage. Having a number on screen makes it easy to scrub through video and find particular pulls to review.

pull counter screenshot

test module

To use this module, point cactbot at ui/test/test.html

This module is just an onscreen test of cactbot variables and is not meant to be used while playing. It can be useful to try out to make sure everything is working as expected or to use to help debug writing your own module.

test screenshot

Adding overlay modules

Here's an example of how to set up the raidboss overlay module. Adding other modules is exactly the same, except you need to point the URL to a different HTML file for that specific module.

To add a cactbot module is the same as adding any overlay plugin.

  1. Open ACT.

  2. Navigate to the Plugins tab of ACT and then the OverlayPlugin.dll tab inside it.

    overlay plugin tab screenshot

  3. Click the "New" button and then select Cactbot in the "Type" dropdown.

    new overlay plugin screenshot

  4. Type in any name you'd like as the name of this overlay, e.g. raidbossy.

  5. A good example to start with is the raidboss module. Set the filename to be ui/raidboss/raidboss.html. Your config should look like this.

    raidboss plugin config

  6. At this point, you should see some bunched up test UI appear on screen. cactbot provides default test UI and a blue background to help with resizing and placing overlays on screen. These all go away when the overlay is locked in the config panel for the overlay.

    raidboss plugin sizing

  7. Uncheck the Enable Clickthru box on the config panel. Then, in FFXIV, click and drag the lower right corner of the raidboss overlay to resize it. Click and drag anywhere else on the raidboss overlay to move it. This will make it look a lot better. You can configure this with CSS if you want even more control. It should look something like this:

    raidboss plugin final

  8. Once the overlay is in the right place, check the Lock Overlay and the Enable Clickthru boxes.

    The "Test bar", "ALARM TEXT", and shaded blue background will disappear once the overlay has been locked.

  9. If you want to test the raidboss plugin, teleport to Summerford Farms, and follow these instructions.

Cactbot Customization

See this documentation for more details.

Supported Languages

cactbot is tested and works with the English, German and French versions of Final Fantasy XIV.

Unicode characters are supported thoughout, through the use of the helpers in the resources/regexes.js file. However timelines and log event triggers may be incorrect if names that appear in the ACT log events are different.