Gamepad APIs: Cross-Platform Button Support

[NoUniqueAddress]

Hi Developers,

We recently announced that Roblox will be widely available to users on PlayStation on October 10. We also announced that we will be upgrading the Roblox Xbox app, enabling a new look, frequent updates (with access to the latest features), improved content recommendations, and an improved user experience. This opens up another opportunity for you to create and share your experiences with millions of people instantly on Xbox and soon, PlayStation.

We are excited to bring you two APIs to help make sure your experiences can easily support gamepad icons.

• Updated UserInputService:GetStringForKeyCode to support Gamepad KeyCodes.
• New API UserInputService:GetImageForKeyCode

These changes will initially work on Xbox, PlayStation, and Windows (using a gamepad), with other platforms planned in the future. Please note that calling these APIs on other platforms will return a default mapping/image for the KeyCode.

Try it now!

Connecting a PlayStation 4 Controller to Studio on Windows will allow you to test and see PlayStation icons with these APIs today! Please use this to test your experiences and update them ahead of the PlayStation launch!

Studio also has a PS4 emulation mode that you can use alongside these APIs to test.

GetStringForKeyCode:

This API currently exists to help developers translate the US query KeyCodes to other keyboard layouts. It has been updated to support Gamepad KeyCodes. This will take the KeyCode provided and map it based on the most recently connected gamepad type. If the connected controller is not supported, the function returns the default string conversion for the requested key code.

Controller Mapping:

These mappings are also how the PlayStation controller is mapped to the Roblox KeyCodes. For example, if you want a user to press ButtonTriangle, you should use KeyCode.ButtonY.

KeyCode	PlayStation Return Value	Xbox Return Value
KeyCode.ButtonA	ButtonCross	ButtonA
KeyCode.ButtonB	ButtonCircle	ButtonB
KeyCode.ButtonX	ButtonSquare	ButtonX
KeyCode.ButtonY	ButtonTriangle	ButtonY
KeyCode.ButtonL1	ButtonL1	ButtonLB
KeyCode.ButtonL2	ButtonL2	ButtonLT
KeyCode.ButtonL3	ButtonL3	ButtonLS
KeyCode.ButtonR1	ButtonR1	ButtonRB
KeyCode.ButtonR2	ButtonR2	ButtonRT
KeyCode.ButtonR3	ButtonR3	ButtonRS
KeyCode.ButtonStart	ButtonOptions	ButtonStart
KeyCode.ButtonSelect	ButtonTouchpad and ButtonShare	ButtonSelect

Example:

This example shows how you can map custom assets for KeyCode.ButtonA.

local userInputService = game.UserInputService
local imageLabel = script.Parent
local key = Enum.KeyCode.ButtonA

local mappings = {
    ButtonA = "rbxasset://BUTTON_A_ASSET", -- Replace with the desired ButtonA asset
    ButtonCross = "rbxasset://BUTTON_CROSS_ASSET" -- Replace with the desired ButtonCross asset
}

local mappedKey = userInputService:GetStringForKeyCode(key)
local image = mappings[mappedKey]

imageLabel.Image = image

Notes:

• Directional pad KeyCodes do not have any differences and will map to their Enum.KeyCode.Name value.
• KeyCode.ButtonSelect has slightly different behavior in some cases. Use both PlayStation mappings to ensure users see the correct buttons.

GetImageForKeyCode

If you don’t want to use the above API, you can use GetImageForKeyCode. This API is much simpler. This API will return a Roblox provided icon for the requested key code. This API is more geared for developers who just want it to work and can be slotted in alongside existing code for easy drop in replacement. The mapping rules will be the same as the above table.

Example:

local userInputService = game.UserInputService
local imageLabel = script.Parent
local key = Enum.KeyCode.ButtonA

local mappedIcon = userInputService:GetImageForKeyCode(key)
imageLabel.Image = mappedIcon

Known Issues:

• The APIs will not work on iOS or Android, a fix is currently pending.
• The images do not fully fill the image rectangle, this will be fixed soon.

Feedback

The API was the top request we received from the community on this feature.

If you have additional feedback or issues, please reply with the details in a comment on this post. Also, if you use these APIs in your experience, please leave a link to it below as we’d like to test it out in your game!

We are particularly interested in hearing whether you were interested in this feature and if the API suits your needs.

Your feedback will help us continually improve this feature.

Thank you.

[bluebxrrybot (blueberry)]

@NoUniqueAddress

GetImageForKeyCode

If you don’t want to use the above API, you can use GetImageForKeyCode. This API is much simpler. This API will return a Roblox provided icon for the requested key code.

I love this! Now I don’t have to use a hacky spritesheets and messy code to fix gamepad icons in images, whilst also allowing icons to show keyboard icons!

I ask, though; What will these icons look like exactly? Can we customize them?

(edit): It doesn’t work for keyboard yet, but the documentation says it supports windows!

(edit 2): Just saw @TheNexusAvenger’s post, and saw the icons. They’re… well, pretty ugly to say the least. (don’t hit me)

local userInputService = game.UserInputService
local key = Enum.KeyCode.ButtonA
local mappedIconImage = userInputService:GetImageForKeyCode(key)
print(mappedIconImage) --> rbxasset://textures/ui/Controls/DefaultController/ButtonA.png

local userInputService = game.UserInputService
local key = Enum.KeyCode.E
local mappedIconImage = userInputService:GetImageForKeyCode(key)
print(mappedIconImage) --> (empty string)

[EpicSharkMan33 (DeadFry42)]

This is a great new addition!

I guess this means the end of searching for a button icon to throw into the game, this is incredibly helpful!

My only question is if this would go well with other developers, and if they would fit into certain games.

Edit - for KeyCode.ButtonSelect, why return both ButtonTouchpad AND ButtonShare? Wouldn’t that complicate things? Also, isn’t Share a button that is not meant to be used by games?

[TheNexusAvenger (Nexus)]

This is great to see. Being able to have a native API for getting an image for a key is a great improvement. I’m not happy with how low-quality the provided images are though.

While 200x200 is probably overkill, the image looks fuzzy to me at a more reasonable 48x48.

With how fuzzy they appear, I will stick with the official gamepad image library released in 2016 for now. I hope this can be addressed - I want to use this.

Edit: Also, while the all-white looks bland, thanks for doing it that way. It makes it very easy to customize with ImageColor3.

[Abcreator]

@NoUniqueAddress

GetImageForKeyCode

This API only works with Gamepad KeyCodes.

Why does this limitation exist, seems a bit counter-intuitive since now developers have to mix-match the Roblox-made icons with developer-made ones for literally every other key that isn’t on a controller, creating a mix-match in UI styles? And to make it clear, these images already exist under the ProximityPrompt system so it’s not like these icons do not exist.

[Abcreator]

@TheNexusAvenger

While 200x200 is probably overkill, the image looks fuzzy to me at a more reasonable 48x48.

Appears that the wrong image is being used! It’s using the 1x sized version when it should be using the 3x sized version, simply change .png to @3x.png in the image string to get a way higher quality version.

[NoUniqueAddress]

@TheNexusAvenger @bluebxrrybot

Hi! Thanks for the feedback, yes we’re aware the icons are lower resolution than expected, a fix for this is already in progress, here’s what ButtonA should look like once the update goes out. Please let me know if this looks/works better!

@Abcreator You are right! You can use the @2x and @3x versions if you’d like. However, all the assets currently had more padding than we want, so in addition to the resolution getting better, the icons should fill more of the image as well.

[moo1210]

Ouch… I’m not a fan of those image sizes. (I see they just addressed this above)
I’m not a fan of them not being colored per the console’s controller either, as most players would expect that. Them being solid white, while providing easy customization, doesn’t match the controller’s look or feel at all. I would much rather see the letters/symbols have the same color as the controller.

[TheNexusAvenger (Nexus)]

Good to hear it is being looked into. That 96x96 icon looks much better.

Any rough idea when this fix will be released? Do you think the fix will be out for the October 10th release of the PlayStation version of Roblox?

[NoUniqueAddress]

Re: customization.

All the images should be transparent with white pixels, so the normal ImageColor3 and BackgroundColor3 should work as expected. Please let me know if they don’t.

If you want full custom assets, you should use this example and upload your own images, using the mappings listed in the post.

[AdvancedOpenGL (charlie)]

@NoUniqueAddress

|KeyCode.ButtonY|ButtonTriangle|ButtonY|
|KeyCode.ButtonL1|ButtonL1|ButtonLB|

the mix of playstation and xbox button names is kinda confusing and it make make more sense to either have both avaliable as keycodes but do the same thing or use directional button names to avoid the confusing

[raymondschonfeld (Raymond)]

Will there be a feature to automatically determine the image by what device they are currently on? Or in general, a way to get DeviceType without weird methods.

[Abcreator]

@NoUniqueAddress

All the images should be transparent with white pixels, so the normal ImageColor3 and BackgroundColor3 should work as expected

I think the main concern is the future usability of the API (IE: if Roblox implements new controllers) since any hardcoded controller icons won’t update, it makes more functional sense to use the Roblox provided image API however since the image API does not return any color (not even an extra Color3 value of an appropriate color to use on ImageColor3?) it is difficult to appropriately adjust this color value correctly across devices.

[Quenty]

Awesome! Time to update my input library to support this!

Question: What if there’s multiple gamepads plugged into the computer? Is there a way to specify for each gamepad what the input mode should be?

[Dyllon3761 (SuperPenguin34)]

Nice.

The GetImageForKeycode function was something I was watching for a while after it was added.

[NoUniqueAddress]

Hi!

What’s your use case for having multiple controllers plugged in at once? Is this primarily for testing?

Currently, the system works on the most recently connected device, but I plan to update this to be whatever device sent the most recent input. There’s no timeline on when that will happen though.

[NoUniqueAddress]

Hey,

We talked about this a bit internally, for now no. The DeviceType won’t be exposed, but there is a future where it could be.

What issues do you see with the current API though that you would want the DeviceType instead?

Thanks

[NoUniqueAddress]

Hey!

I understand it can be confusing to have to look at the mappings for the KeyCodes. However, this is better than increasing the KeyCodes for every platform Roblox might ship on. Directional button names are a good idea but become much harder when you consider VR controllers. If you have good directional names please suggest them! We may revisit this idea in the future.

Thanks

[2jammers]

There should be an optional number param which ranges from 1-3, with the default being 1.

Anyways great update! I would like if this method was also supported for all keycodes, as I use these a lot in my UI.

@NoUniqueAddress

What’s your use case for having multiple controllers plugged in at once? Is this primarily for testing?

I’ve been experimenting with a 2D game, which uses multiple controllers as sort of a split-screen play.