I'm pleased to release VACCiNE (Volnaiskra's All-purpose Customisable Controller & iNfo Engine). It's a combination of a couple of systems I've developed for my own game Spryke over the past couple of years. I figured they'd be useful to others too, so I've spent the past week or two cleaning it up, adding more features, and commenting everything.
UPDATE Oct 2017: VACCiNE 2 is out. It's a greatly improved version of VACCiNE that looks better, runs faster, does more stuff, and is easier to use. The VACCiNE 2 forum thread is here. You can get VACCiNE 2 at the Clickstore for $3.99. The original VACCiNE still is, and always will be, free.
What is VACCiNE? (the short version)
VACCiNE is a handy bit of Fusion code that makes pretty much every gamepad under the sun work out-of-the-box and flawlessly with your Fusion PC game. It greatly simplifies the work required for your game to have robust gamepad and keyboard controls. It also provides a sophisticated in-game debugging panel that you can fill with useful info, to help you monitor the nuts and bolts of your game. VACCiNE does all this with regular, well-commented Fusion code, and regular Fusion Active Objects, meaning that you can easily enable/disable/customise/expand any part of it to suit your own project. It's designed to be as simple as possible, though an intermediate level of familiarity with Fusion is recommended.
The following gamepads have been confirmed to work out-of-the-box with VACCiNE (tested on win 7 & win 10):
Xbox One Wireless
Xbox One Elite
VACCiNE Overview (watch the video)
What is VACCiNE? (the long version)
Traditionally, getting gamepads to work reliably with Fusion has been a pain. The XBOX Gamepad object is severely limited. The more robust Joystick 2 object is a confusing mess. It's confusing enough with just an Xbox 360 gamepad, but once you throw Xbox One, PS3 & PS4 gamepads into the mix, plus multiple versions of Windows, it becomes a nightmare. Values are all over the place, data labels are meaningless, and everything works differently from everything else, resulting in conflicts and confusion. Let me give you a taste:
The PS4 joystick gives you both 8-directional and 360-degree values. But you have to press the stick significantly harder to register the 8dir one. 8dir starts at 0 but 360deg starts at -1, and while one goes clockwise, the other goes anticlockwise. But at least they both start at east. Unless you're talking about the right joystick, in which case they both start at south. Just for fun, the dpad starts from north. If you want to know how hard you're pressing either of the sticks, you'll need to calculate it yourself from the X and Y values. The X and Y values from the left stick are given as RawX and RawY, and both go from -1000 to 1000. On the other hand, the X and Y values of the right stick are given as RawZ and RawZrotation. Like RawX and RawY, RawZ goes from -1000 to 1000, but RawZrotation (which actually has nothing to do with rotation) likes to really express itself, so goes from 0 to 65535. But at least the use of RawZRotation doesn't conflict with the Xbox gamepads, which the use of RawZ does, since RawZ is what Xbox uses for the triggers (well, unless a player is on Windows 10 with native drivers, in which case their right trigger is measured in RawZrotation). Anyway, the Xbox left stick works much like the PS4 one, complete with inconsistent measurement methods and mismatched deadzones. But the Xbox right stick missed the memo and doesn't bother giving you 8dir, 360deg or analog strength data at all. Well, not real data anyway - it does give you a permanent false positive for 'moving left', so there's that. But it provides X and Y info (from 0 to 65535) so stop interrupting its nap and work it all out for yourself (hope your trigonometry is up to scratch!). Oh, and it has absolutely no deadzone, so you'll need to program one in yourself unless you want erratic micro-movements pretty much nonstop.............Simple, right?
Ok, so VACCiNE takes all that nonsense and consolidates it into logical, user-friendly alterable values. It gives each stick a small, consistent deadzone (big enough to prevent accidental movement; small enough to encourage nuanced analog movement). Then, whatever input the player uses, on whichever gamepad, VACCiNE gives you the appropriate info via these "neat" values:
LeftStickNeatDirection, RightStickNeatDirection, DpadNeatDirection
Always from 0 to 7 (-1 for null), anticlockwise from east - just like Fusion's default behaviour
LeftStickNeatDegrees, RightStickNeatDegrees, DpadNeatDegrees
Always from 0 to 359 (-1 for null), anticlockwise from east - just like Fusion's default behaviour
Always from 0 to 1000
That's much better already, right? But unless you actually need 360degree movement (eg. for a twin-stick shooter), it gets even simpler. VACCiNE elegantly combines gamepad and keyboard controls - with automatic support for both analog and binary controls - and boils everything down to simple values like these:
movementLeft: 0 to 1
movementRight: 0 to 1
movementUp: 0 to 1
movementDown: 0 to 1
These four values will catch the DPAD and Left Joystick of virtually any gamepad, plus WASD and the arrow keys. Binary inputs (keyboard or dpad) will return 0 or 1. Analog inputs (joysticks) will return a decimal figure from 0 to 1 (for example: 0.487 would be almost halfway-pressed).
You might not want the Right Stick controlling character movement, so by default, the Right Stick doesn't affect these movement values (movementLeft, movementRight, etc.). But you probably do want the right stick to work in menus, so it will - along with the left stick, dpad, WASD and arrows - affect a second set of values (menuLeft, menuRight, etc.).
And if your game has camera control, you might want the Right Stick to affect that, so by default the Right Stick (but not the Left Stick, dpad, WASD or arrows) will affect a third set of values (cameraLeft, cameraRight, cameraUp, cameraDown) You'll probably want something on the keyboard to affect the camera too, so by default DEL, PGDN, HOME, END, have been assigned to those same values (cameraLeft, cameraRight, cameraUp, cameraDown)
.... And so on. Basically, most common input types have already been coded in. Once VACCiNE is in your MFA, pressing various keys and buttons will trigger appropriate Alterable Values, ready for you to take advantage of them in your code.
The youtube video will give you a good sense of how it all works. As will simply loading the mfa, hitting ~ to show the debugger and pressing stuff on you keyboard and gamepad to see how VACCiNE deals with it.
That's the other part of VACCiNE: A sophisticated in-game debugger. It's kind of like Fusion's inbuilt debugger, but it's much more convenient because it's in-game (toggle it on and off with keyboard or gamepad), has performance benchmarking features, and is very customisable.
LIST OF FEATURES (INPUT):
* Makes practically any gamepad under the sun work, out of the box, in your PC Fusion game
* Consolidates inputs from myriad gamepads, and keyboard, into a cohesive, universal system exposed in simple Alterable Values that are ready for you to use in your code
* Has a system for movement controls, menu controls, common RPG keys and more.
* Unifies data for all sticks and dpads to include both 360-degree & 8-directional info, using a uniform system that matches Fusion's default behaviour
* Provides straightforward analog data for all sticks and triggers, making it easy to use (or ignore) analog controls in your game.
* Automatically detects whether gamepad or keyboard is being used, and switches code accordingly
* Uses Control X object for keyboard inputs (up to 10 times faster than default keyboard object)
* Provides "stepping" mechanic that allows an input to be triggered repeatedly at short intervals without player needing to release button/key (useful for menus)
* Automatically enables mouse button/wheel support in menus
* Doesn't use problematic "Poll for new devices" option in Joystick 2 object (known to cause stability issues)
* Allows PS4 gamepad to work in your game - no drivers or 3rd party software required
* Heuristically detects incorrect drivers for Xbox One gamepad on Windows 10, and automatically corrects for it
* Adds consistent and appropriate deadzones to all gamepad joysticks
* Uses Joystick 2 object, but extrapolates its data to provide more useful information than was previously given (eg. analog strength of all sticks, 360-degree directional information for right xbox stick)
* Links triggers on PS4 gamepad by default, to match behaviour of Xbox gamepads
* Exposes correct names of all buttons on all major gamepads ("options" on PS4, "start" on 360, "menu" on One, "circle" on PS4 etc.) and stores latest-used one in alterable string
* Well organised and well commented code makes it easy for you to modify/expand/remove whichever elements you want (intermediate understanding of Fusion recommended)
* Is integrated with VACCiNE's debugger to show you real-time data for all gamepad and universal input activity
* And more...
LIST OF FEATURES (DEBUGGER):
* Provides a powerful in-game debugger panel, toggleable with a key or gamepad button
* Easy to customise - just place references to the things you want to monitor into the provided String objects.
* Provides freeze-frame capability for monitoring debugger panel frame by frame
* Provides independent performance benchmarking panel, including FPS, Tick duration, and its own measure, called VAC score.
* Provides infrastructure for two toggleable tests: Place events in one of the provided folders, hit a key to toggle it in-game and see performance impact measurements
* Less performance impact than built-in Fusion Debugger
* Consumes virtually no resources when toggled off
* A layered PSD of the debugger background is provided, to facilitate easy modification
LIST OF FEATURES (GENERAL)
* Almost 1000 lines of commented code - the vast majority of which you can happily ignore if you wish
* All code is contained within a single umbrella group, for easy transportation/deactivation
* All VACCiNE-specific components are on a separate layer, and use a unique visual style and naming convention, to remain separate from the rest of your project
* VACCiNE is totally free to use and modify
THINGS TO BE AWARE OF
* VACCiNE is currently set up for single player games (as many gamepads can be plugged in as you like, but whenever one is used, the others are deactivated). If your game is a local multiplayer game that requires multiple gamepads at once, VACCiNE will still be helpful, but you'll need to customise it a bit.
* VACCiNE is intended for PC games. I don't know how/if it works in the other exporters
* VACCiNE is set up for use in a 1920x1080 game. For other working resolutions, you'll need to shift some stuff around
* VACCiNE requires the Joystick 2 object, Xbox Gamepad object, Control X object, and Layer object
* VACCiNE was designed with custom movements in mind - (it provides input data in the form of alterable values that you then need to make use of in your code). I don't know how useful it is for inbuilt movements, because I'm not very familiar with how they work.
* VACCiNE uses one Qualifier ("Calculation"). If your game uses this qualifer too, you'll need to modify one or the other to use a different qualifier (otherwise stuff in your game will also be made invisible when toggling the benchmarking panel)
* I'm sure I'll need to make updates to VACCiNE from time to time, so check back here occasionally.
* For now, I'd like to restrict the availability of the download to my website (purely to keep updates simple for me). If one day I disappear entirely from the community (not gonna happen any time soon), I give permission for others to host it here or elsewhere and/or take over development of it
* Fun Fact: For now, if you google "Volnaiskra Clickteam Gamepad", the first entry is one of the first threads I ever posted, asking for help with getting gamepads to work, as I had no idea. I've come far
You can get VACCiNE for free at the Clickstore: http://clickstore.clickteam.com/vaccine_universal_gamepad
It's a small ZIP that contains the MFA and an optional PSD file. Before you can use it, you'll need to install the Joystick 2 object, XBOX gamepad object, Control X object, and Layer object, using Fusion's Extension Manager
Feedback, bug reports, etc. are welcome. Also, if you have a non-supported gamepad, let me know and I can try and get it working (it'd be helpful if you provide me with all the RAW values that your gamepad produces). You can contact me via this thread, via PM, or using the contact form on my webiste.
I hope VACCiNE improves your Fusion gamedev experience!