Important Note: please submit new bugs from the Github page, which automatically emails me, so I can respond more quickly.

XIVCrossbar

A Gamepad Macro Addon (github link)

I had never planned on releasing this--because I thought nobody would care--but when I showed off my crossbar UI in the "Share your custom FFXI UI" thread, I got such a reaction that I decided it would be worth it to clean it up and make it publicly available. Due to work complications, it took a few weeks for me to get it ready for release, but here we are, and now it's ready.

What is XIVCrossbar?

XIVCrossbar is a recreation of FFXIV's crossbar gamepad macros...




...in FFXI.

Under the hood, XIVCrossbar is a heavily modified version of the (excellent) XIVHotbar by SirEdeonX. It uses a different name and different bindings such that the two can be used simultaneously, if you're into that.

How does XIVCrossbar work?

If you're already used to XIV's crossbar, go ahead and skip to the "How do I set up XIVCrossbar?" section; you probably know everything I'm about to explain.

The long and short of it is that you hold down your left/right trigger, then press either a dpad button or a face button in order to activate the action that has been bound to that button combination. While the previous screenshot of XIVCrossbar shows how it corresponds to XIV's actual crossbar, a screenshot of it with compact mode turned off should make things more clear. As an example: with the below crossbar setup, if I were to press B while holding the left trigger, I would cast Magic Fruit. If I were holding the right trigger instead, I would use Expiacion.



Having only 16 actions per crossbar set would be pretty limiting, so I took a cue from XIV's actual crossbar and gave the option to add a 3rd crossbar by holding down both left and right triggers. When you do that, the main 2 crossbars disappear and a 3rd appears in the center to replace them. So if I were to press B while holding down both triggers, I would cast Sweeping Gouge.



If 24 actions per crossbar set still isn't enough, then you can change settings.global.Hotbar.Number from 3 to 4 in your settings.xml, which will up you to having 4 crossbars per set, for a total of 32 actions per crossbar set. In this case, holding both triggers still brings up a new crossbar, but whether it is #3 or #4 depends on the order you press the triggers. R -> L shows crossbar #3, and L -> R shows crossbar #4. (This was also cribbed from FFXIV)

Update: I also added double-tap crossbars that you can enable by increasing settings.global.Hotbar.Number to 6 in settings.xml. You can jump to these crossbars by hitting one of the triggers twice in quick succession (like double-clicking a mouse), which means you can now have up to 48 bindings per crossbar set.

What's the advantage of using a crossbar over FFXI's native macros?

Well, if you're a keyboard-only user, then nothing. If you use a gamepad like me, though, then two words: muscle memory. FFXI isn't a particularly fast-paced game, but when you're in a hard fight, dpadding left and right in your macros to select the right one does take time and concentration. But having L -> B bound to Magic Fruit on all my BLU crossbars means that when I see my HP is low, I don't need to find the right macro and then execute it, I just hold the left trigger and press B.

How do I set up XIVCrossbar?

Everything you need to know is in the README file, but a high-level view is something like this:

1. Download the zip file from github, and extract it to your addons folder, as usual

2. Install AutoHotKey (free)
   (But if you're playing on Steam Deck, skip AutoHotKey and just set up FFXI_Input.sh from the Github repo to run when you run FFXI)
   

3. Open FFXI Controller Config and make your setup look like this:

   

   (Check the XInput box if you normally do)
   

4. Log into FFXI

5. Load xivcrossbar

6. Follow the setup dialog shown

When I'm in battle, sometimes a horizontal red or green bar appears above my crossbar. What is that?

It's a skillchain window indicator. When the bar is red, the window is not yet open. When it's green, the window is open. The bar expands while it's red, and then shrinks while it's green. When the green bar has shrunk completely and disappears, the skillchain window has closed.

Sometimes my weaponskill icons change to a different icon, and a yellow marching-ant border appears. What's going on?

That's to notify you that if you use that weaponskill right now, you'll make a skillchain. The icon of the weaponskill changes to the icon of the skillchain you would make if you used it. Naturally, this only happens when the skillchain window indicator is green.

Any weird quirks I should know about?

Unfortunately, yes.

The first quirk is that due to the way we're capturing gamepad input, we can't actually stop button presses from reaching the game, even if they're only intended to interact with XIVCrossbar menus. The way we handle this is to make the game capture and discard the dpad presses for us, by keeping the regular macro system open. This is why the macro palettes need to be mapped to the triggers. So, when you're interacting with XIVCrossbar dialogs like the gamepad mapper or the action binder, you will need to have one or both triggers held down in order for it to read your input. Since this is already how the crossbars work--even in FFXIV itself--it's unnoticeable during gameplay, but you'll need to keep note of it for when you're tweaking your crossbar sets. However, I highly, highly recommend setting aside a completely blank macro book in FFXI and using it when you're using XIVCrossbar so you can button mash as much as you want without accidentally firing off any vanilla FFXI macros.

The second quirk is that due to the way we're passing gamepad input to FFXI, we unbind any existing keybinds on Ctrl+F1 through Ctrl+F12. Under the hood, a gamepad button combo like L -> DpadLeft is sent as a button combination like Ctrl+F1+F12, which would fire both Ctrl+F1 and Ctrl+F12 bindings, if they existed. The plus side of this is that regular F1 through F12, Alt+F1 through Alt+F12 and Shift+F1 through Shift+F12 are unaffected. I will look into a way of porting over existing keybindings such that this is transparent once it's been set up, but I currently don't have it implemented. I have added a way to rebind Ctrl+F1 through Ctrl+F8 (Ctrl+F9 through Ctrl+F12 are still reserved). Just move your bindings for those into the command strings found in addons/xivcrossbar/function_key_bindings.lua.

The current status of feature work is as follows:

Planned:
Priority #1 - Light Arts/Dark Arts auto-swapping (Done)
Priority #2 - Addition of <stpc> to actions that normally only use <me> (Done)
Priority #3 - Roll/Double-Up combo action (available on experimental git branch)
Priority #4 - JA + WS Bindings ("Sneak Attack + WS" in one action) (available for XML editing folks on experimental git branch)
Priority #5 - Attack/Switch Target combo action

"Messing around in the shop"/non-functional:
- Multiple JOB-Default crossbars/Weapon-specific crossbars
- GearSwap Mode Changers (currently, nothing you couldn't do with ex commands)

On the drawing board:
- Display charges for abilities alongside recast (e.g. Strategems, Flourishes, Quick Draw)
- Equip weapon action
- Equip set action
- "Timer" XML attribute (overrides the default timer/lack of timer for an action's icon)
- Integration actions (e.g. EasyNuke)
- Refactoring/code cleanup
- Rendering code optimization
- Slot swap UI
- Hide/Show commands
- Follow command

Known bugs:
- Abilities on cooldown retain the "Job Default Set" or "Default Set" overlay when binding dialog is opened then closed
- Using the "Move Crossbar" UI makes icons appear in the corner of their slot until the addon reloads

Note that this isn't a promise to deliver these features in this order; it's just how I'm currently thinking things will go.

XIVCrossbar Advanced Topics

This addon uses AutoHotKey; couldn't that be used to steal login information?

Yes, this is possible. Though I personally promise that I will not steal your account, make any attempt to record your login information, or do anything else that would breach your trust, I encourage you to not take my word for it. If you're a programmer or have a programmer friend, please inspect the code to your hearts' content and verify that I am not keeping a record of keystrokes, and am not transmitting them anywhere except into FFXI. Addons are open source, after all.

(The only thing I ask is that you not judge me too harshly for the quality of the code. I hacked it together initially without ever intending to share it with anyone outside my own house, and it really shows in some places.)

This brings up an important point, though, which is that because the addon is open source on Github, anyone can make a fork of it, and a bad actor absolutely could release their own modified version of it that steals your password. So I encourage you to only download it from my Github, and to verify the MD5 hash of the AutoHotKey scripts on your system before you run them. (If you edit the files, the MD5 will change, so verify before you change them.) You can get the MD5 hash of a file in Windows by opening a command prompt and typing this:

The MD5 hash of ffxi_xinput.ahk is "6222b03366e5643ccc4032675c28820a", and the MD5 hash of ffxi_directinput.ahk is "a76d6ee4093d702251f782ee2b7c0801". If you download the addon and the MD5 values are different, don't run it. Come here and yell at me until I either confirm that the files were somehow modified without my knowledge (and that you should delete them until I upload a fixed version), or that I updated them and just forgot to update this post with the new MD5 values (in which case you're clear to use them, but feel free to look at the changes yourself before you run them).

Can I set up action bindings that run arbitrary commands?

Yes! You'll have to edit the crossbar XML, but it's completely doable. The most important action types in this case are "ex" (Execute Windower Command) and "ct" (Custom Type). If you've used these in XIVHotbar, they work exactly the same here. In short, if you wanted to add a crossbar action to cycle your gearswap offense mode, you could do:<alias> and <icon> are optional on all bindings, and you can also include <target> if needed. <target> takes any valid FFXI target like <stnpc>, but with the < and > removed. So an Expiacion binding looks like:
"ct" is used when you want to input a FFXI command directly. In that case, the type is "ct", and the action is the FFXI command with the leading slash removed. So if you wanted to create a binding that says "Hello!" in party chat, you could do:

Is there an easy way to include some of the same bindings in every crossbar set?

Yes! By using the Default, Job Default, and All Jobs Default crossbar sets, you can quickly and easily add actions across multiple crossbars. It works like this: when you have any crossbar set selected, we show the actions bound to each of its slots. But sometimes slots are empty, and that's where the different kinds of default sets come in.



Think of it like you're stacking some different colored stencils: the red bottom layer (All Jobs Default) goes down first.



Then the next layer (Job Default) which is orange is laid down. You can only see red in places where there's an empty space in the orange layer.



Then the next layer (Default)--which is yellow--is laid down. Now you can only see orange in places where there is an empty space in yellow, and you can only see red in places where there's an empty space in both yellow and orange.



The final, green, layer (a regular crossbar set) is laid down last, and everywhere that layer is non-empty is now green.



That's how the default sets work: the more specific layers are added last, which keeps the All Jobs Default set from overwriting all the others; because it's always the bottom layer. The rest of them change depending on your job and your specific job+subjob combination.

The TL;DR version is: add stuff to your Default sets to put them everywhere, and then leave those slots empty in your regular sets in order to keep the default bindings, or overwrite them on a case-by-case basis if you prefer.

You have nice looking icons for some WSes/JAs/spells, but plain icons or no icons for others. Are you going to add icons for everything?

Well, I'm a programmer, not an artist. All the nice (and plain) looking icons were someone else's work (either already in XIVHotbar, or ripped from FFXIV). I might have tweaked some of them at most. (I did do the MS Paint-looking icons). I am absolutely on board to incorporate icons submitted to me into this, but I'm not likely to create more myself. You can look at FFXIV's icons for inspiration if you want to add some of your own.

How can I add icons of my own?

If you want to add them directly to the default icon pack, that's located in addons/xivcrossbar/images/icons/iconpacks/default and has the following folder structure:

But if you want to set up your own icon pack that you can share easily, create a new folder under addons/xivcrossbar/images/icons/iconpacks/ with the above structure, and fill it with your own icons. The naming convention of image files is as follows: lowercase, with hyphens replacing any spaces, all punctuation removed, and .png file extension. So an icon for Tachi: Fudo should be called tachi-fudo.png and should reside in <your-pack>/weaponskills/great-katana/, whereas an icon for Assassin's Charge should be called assassins-charge.png and should reside in <your-pack>/abilities/. You will need to change the iconpack value from "default" to "your-pack" in settings.xml in order to use your icon pack, but other than that, the addon will automatically use any properly-named icons you have added, and will use the XIVHotbar default icons for any icons you haven't specified.

Does this work on Steam Deck?

It sure does! I've added FFXI_Input.sh and FFXI_Input.py to the Github repo, which replace the need to have Autohotkey (only works on Linux!), so as long as you can get Windower running on your Deck, you can use XIVCrossbar! Just make sure to start FFXI_Input.sh when you start FFXI, and it should just work! I did this by adding the line (requires Run plugin) to my init.txt Windower script, right after loading linuxfix.

XIVCrossbar Troubleshooting

I followed the instructions but the setup dialog in-game isn't seeing my button presses. What should I do?

Usually this is due to needing to run your AHK scripts as Administrator. If Windower is running as Administrator, then they should be automatically run as Administrator as well (the addon starts the AHK scripts each time it loads), but if they aren't, manually doing so should fix things.

Another possibility is (non-XInput controller users only) your DirectInput button numbers are different than my presets. In that case, you will need to modify the button numbers used in ffxi_directinput.ahk. You can use the AHK script at https://www.autohotkey.com/docs_1.0/scripts/JoystickTest.htm to determine what your button numbers are. In ffxi_directinput.ahk you shouldn't need to change any lines other than changing lines like 'Joy10::' to 'Joy4::', and any corresponding lines like 'if GetKeyState("Joy10")' to 'if GetKeyState("Joy4")', and so forth. Everything else can be configured through the addon in-game.

If you've updated your button numbers to match and you're still not seeing them in XIVCrossbar, check your joystick (not button) number using the same test script as before and prepend that number to all the button handlers/getters (e.g. if you're using Joystick 2, change "Joy1::" to "2Joy1::", if Joystick 3, then "Joy1::" becomes "3Joy1::" and so on).

I'm running FFXI on an old computer/graphing calculator/potato, and this addon tanks my FPS. Can I reduce the resource burden of this addon?

Yes, you can. Go into addons/xivcrossbar/data/settings.xml and change FrameSkip from 0 to a higher value. This will cause the UI to be drawn less often, which should get your in-game FPS back up, at the cost of making XIVCrossbar animate less smoothly. Note that FrameSkip makes XIVCrossbar's UI choppier, but does not affect the speed of the underlying button mapping functionality. What this means is that you can still do your button combos at full speed; you don't ever need to wait for the UI to catch up as long as you know what your button combos do without needing to read the UI.

What different FrameSkip values specifically do is tell XIVCrossbar how many animation frames it should skip before rendering again. A value of 0 means never skip, 1 means skip every other frame, 2 means skip 2 frames in between each render, and so on.

I use FFXI vanilla macros with equipsets, not Gearswap, and gamepad-bound actions don't use equipsets, so I'm not swapping gear when I use this addon. Is there a way to make XIVCrossbar work with equipsets?

Yes, but this addon wasn't written with that functionality in mind, so it will take some setup. Basically, you will want to go through the normal binding process to get your crossbars looking the way you want, and then you'll need to go into your XML and do some editing. (Your XML is located at addons/xivcrossbar/data/hotbar/<Your FFXI server>/<Your Character Name>/NIN-WAR.xml (change to your job + subjob). The default set is in that XML, your Job Default set is in NIN-DEFAULT.xml (change to your job), and your All Jobs Default set is in ALL-JOBS-DEFAULT.xml.)

Once you have the XML open, you'll need to change the XML for each ability/spell you want to add equipsets to from this:
To this
and then add sange.txt to your windower/scripts folder with the following contents:

Other than the burden of needing to create all of these script files, you also won't see icons for abilities/spells mapped this way unless that ability/spell has a custom icon in your current icon pack. Unfortunately, there isn't really a way around this without me making big structural changes to how icons are loaded, so my advice is to cobble together an icon pack that covers what you need, or possibly try to crowdsource a community icon pack.

I may (no promises) be able to whip something up that automatically generates these script files if enough people are interested in this feature, but you'll still need to plug in your own equipset numbers. I'm extremely hesitant to go any further down that road, though, because this could very easily feature-creep into becoming a Gearswap alternative--which is something I have zero interest in maintaining.

If you use a controller to play, this is a game changer.

Awesome addon, thanks for sharing this!

It's a shame that you have to use workarounds to make the gamepad work in Windower 4. Any idea if Windower 5 will have native gamepad support?
It might be possible to write a native plugin that reads gamepad inputs directly and passes them on to a lua addon like the Binder plugin. But with Windower 4 core being closed source and documentation for native plugins non-existent, this might not be worth the trouble.

I'm not sure. If Windower 5 does support native access, though, I'll definitely drop the workarounds in favor of that.

I have heard that this is a planned feature for windower5, but I don't believe it has been implemented yet. If I see it go live I will definitely give you a shout. XD

This works with manual macros too?

Do you mean normal vanilla macro bars?
You are still able to use vanilla macros. Just you may navigate away from them using the hotbar.

What are you hoping to do?

Added support for Assist bindings, and updated intro post to explain the skillchain icons and skillchain window indicator.

Added ability to keep your normal Ctrl+F1 through Ctrl+F8 bindings by moving the commands to be bound into addons/xivcrossbar/function_key_bindings.lua.

Edit: there was a bug in the initial version of this, but it has now been fixed.

i dont play this game with lua scripts everything is manual this would help i am a keyboard user my hands hurt from manual macros lol

That's...not the point of the XIV Crossbar....

Setting aside that this addon literally is a bunch of lua scripts, if I'm understanding you correctly, you want your (for example) Provoke macro to just do "/ja Provoke <t>", with no fancy Gearswap lua or Spellcast xml funny business going on. Is that right?

If so, that's exactly what this addon does. There is an action binder that you can access with the Back button (if you're using Xbox controller) that lists out your Job Abilities/Spells/etc, and allows you to assign them to your button combos. If you want to use Gearswap with this, you can, but it is by no means mandatory to do so.

I get the feeling that he doesn't use Windower at all, which is a prerequisite for this to work anyway.

I could be wrong though.

use windower for the addons but not the gear swaps, i use manual vanilla swaps. anyway thanks seems like it works i will meddle with it tomorrow

Ah. In that case, you wouldn't be able to use it.

does the "enable hat switches" option need to be turned on? its greyed out with XInput and I can't get past the confirm button setup

That should be fine, the image shown is for DirectInput controllers.

What's happening during the confirm button setup?

Does this addon work if you don't use lua?

Hi great addon, my issue is — I use a Xboxone controller and for the life of me I just can’t get the triggers to work when I try to set up the controller to the same setup in your guide, the xinput checkbox won’t let me tick it and I can’t find anyway of making the left and right triggers to work on the controller, any advice would be greatly appreciated ? if there’s no current workaround? Guess I’ll have to buy a new controller that works without this issue I’m experiencing!
Thanks

Setting aside that this addon literally is just a bunch of Lua (and some other stuff), I'm going to assume you mean Lua macros for changing gear like Gearswap. If that's what you mean, then yes. It wasn't really designed with this use case in mind, but it can work.

However, you'll have to customize it to make it support the gear changes you want because right now it just inputs plain JA/Spell commands. I'm assuming you use FFXI native equipsets, so what you can do is go through the binding process to get all your abilities/spells where you want them on the crossbar, and then open up your crossbar XML file (addons/xivcrossbar/data/hotbar/Lakshmi/Buuki/NIN-WAR.xml, or w/e job this is for) and take each ability/spell you want to use from this:
To this
and then add sange.txt to your windower/scripts folder with the following contents:

It's not exactly vanilla macros, but it avoids you needing to write any Lua. It will probably take an hour or two to get all your macros ported over, but a lot of it will just be easy copy/paste work.

Good news, the triggers being mapped aren't required due to an earlier refactor I forgot to take into account. You should be able to make everything work without it. For a quick test, just try loading the addon when you're logged in, but it worked for me when I tried it without the triggers mapped in XIConfig.

Edit: updated example config image to make this clear.

Also, added settings to control the colors of the skillchain window indicator, because I temporarily forgot being colorblind was a thing when I decided to make the waiting/ready colors red and green.

Potentially silly question.

In your controller config it says leave the 4 face buttons unmapped.

Does that mean you cannot use then for menus etc?
Confirm cancel menu etc.

This is exactly what I was looking for. Thanks. With 100 equipsets, it would take a week of time to copy and paste it all over, but maybe i'll try the addon with just one job macros and see how I like it. Thank you.

Not a silly question!

This was a big hurdle I had to overcome to get this addon to work. I'm going to give an in-depth answer in a second, but TL;DR you can still use them for menus. The addon setup dialog lets you map Confirm, Cancel, Main Menu, and Active Window to your face buttons however you see fit.

So, fun fact: in FFXI, the gamepad's Cancel button and the Escape key do exactly the same thing. It wouldn't surprise me if they literally do nothing except call the same function in the FFXI client code. Same with the Enter key and the gamepad's Confirm button, but they're only 99% similar. NumpadMinus and NumpadPlus are very, very similar to the gamepad's Main Menu and Active Window buttons. This addon takes advantage of that.

Basically, when you press the a face button, the AHK script sends a different key depending on if you have the triggers pressed or not. So once you've mapped your face buttons in the setup dialog, if you press (for example) A when no triggers are held, it will send an Enter keypress. On the other hand, if the left trigger is held while you press A, it will send (something like) Ctrl+F11+F5. It's the same for Cancel, Main Menu, etc.. The main area where you'll see some slight weirdness is if you use the Main Menu or Active Window buttons while typing in the chat bar. In that case, the curtain hiding how everything works slips a bit, and you will see plusses and minuses added to your text. But you usually won't be messing with the menu while typing a message, so you won't encounter this problem unless you go looking for it.

Dude first of all wow this is amazing a complete game changer not only with crossbar functionality but skillchain tracking. Amazing QoL for a new/returner like myself.

However that being said, I'm running XIV on a laptop with no GPU and already struggle to stay between 15-29FPS. This addon seems to kill my frame rate by half.

I am currently playing at 1366x720 resolution

I have noticed that it has to do specifically with the UI and the skill icons.

With no crossbar displayed the frame rate is normal as usual at around 29fps. (such as when interacting with a home point)

With the crossbar displayed with no skills on it this drops to about 24fps

With the crossbar displayed with 8 skills placed on it this plummets the frame rate to 11-15fps

I have enabled compact mode and this did bring a minor improvement.

The frame rate also improves when only one crossbar is displayed (R2+L2)

Do you have any recommendations for what I could do to increase the frame rate? I tried deleting the ability icons but this only brought a very minor increase. Is there a way to resize the crossbar? Its quite large right now, I'm thinking if I were to shrink it a bit that could bring a gain. Im not sure?

I get a prompt that says to hold the right trigger then press the button you want to map to Confirm/Submit. When I do that though nothing happens.

I'm also using DS4Windows and a PS4 controller but it acts like a xbox controller to the game/computer with the hide option



-- Nevermind figured it out I had to run the ahk script as admin which let it interact with ffxi

Thank you :)