Programmatically Update Configs: The Open Cloud Configs API

Updates Announcements
,
1

Hi Creators,

Managing configs in your experience just got a lot more flexible. Today we’re launching the Open Cloud configs API, a new addition to our Cloud API suite that lets you manage your experience configs programmatically, including third-party apps that have an API key with the correct permissions, or OAuth 2.0 enabled.

ICYMI, last year we launched configs that let you dynamically change values in your experience without having to publish a new build and kick all of your active players from the experience.

Previously, updating experience-wide variables meant manual tweaks in the Creator Hub or Studio. With this update, you can now automate your live ops, build custom internal tools, or integrate your game’s balancing directly into your own external dashboards.

What’s New?

The Open Cloud configs API lets you create, read, and update configs through code. You also have access to a full history of who changed a config, what they changed, and when it happened. The API also comes with a variety of helpful methods alongside code snippets that you can check out in our documentation.

What can I use this for?

You can use this API in a variety of ways to dynamically update or publish new configs for your experience, from both inside and outside your experience using the Open Cloud API; this means you can create apps that update configs from outside Roblox.

Examples of what you can do include:

  • Adjust the balance of items, weapons, or abilities: Change the availability of items or values of abilities (ie. cooldowns, damage) through a custom third-party application that you use to manage your experience. Pro tip: you can also see how tuning changes impact your metrics in Creator Analytics by selecting Show Annotations > Versions at the top of the charts you are interested in (retention, engagement, monetization, etc.)
  • Schedule a ‘drop’ or release in your game: Build hype for new features or UGC items by scheduling their release for a specific UTC date and time. To ensure a fair experience for all players, avoid using simple true/false toggles; instead, use a timestamp to trigger the update simultaneously across all servers.
  • Create a rollback safety net: Testing new balance changes or variables? You can now set up a safety net for your configs. If a specific criterion is met (like a crash rate spike or a massive dip in earnings), you can easily rollback to a previous “safe” version (by republishing it), preventing a small tweak from breaking your entire game.

How do I get started?

Before you start, you should take a read through our Cloud API documentation; you’ll need to generate an API key or configure the app you’re building to use OAuth 2.0. If you only need to read a config’s current or past value, you’ll need to set the scope of your API key to universe:read. If you want to draft and publish new configs or update existing ones, you’ll need to set its scope to universe:write.

Once you’ve either setup an API key or OAuth 2.0, you should be able to programmatically access the API with whatever app you’re building; take a look through our documentation for some example code snippets.

82 Likes
2

This topic was automatically opened after 10 minutes.

3

That’s actually quite a nice step forward! It’s definitely useful for the people who use the API, even though I haven’t happened to use it myself yet..

12 Likes
4

Will we ever see improvements to configs, perhaps things like transferring between places, JSON Schemas for more complex item data, or anything of the sort?

6 Likes
5

This is a massive update! It would be incredibly powerful if we could call this API directly in-experience via HttpService with an API key. This would allow for real-time global admin panels, automated dynamic difficulty balancing based on player data, or even universe-wide events triggered by player votes. These are just a few use cases off the top of my head, but I’m sure the possibilities for live-ops are endless when the game can programmatically manage its own configs.

5 Likes
6

this is awesome! so many systems can be implemented easier with this,
i do have a suggestion though, i think it would be best to make a group payouts cloud api that requires OAuth2 key instead of your cookie so developers can automate payouts!

4 Likes
7

The open cloud configs API is a universal leap for roblox creators because it takes config management out of manual adjustments and moves it into simple programmable workflows, making live updates smoother and more flexible. do ya think this change will lead more developers to build external automation tools, or will most still stick with the builtin Studio methods? :o

4 Likes
8

Can’t this already be done using MessagingService? Or are you talking about other stuff such as Discord integrations?

6 Likes
9

I don’t use this one bit so I’m neutral

7 Likes
10

Hey! Mind elaborating on what you mentioned? Configs are currently experience-wide, are you referring to publishing configs from one experience to another experience?

And what kind of complex item data?

4 Likes
11

I apologize, yes transferring to another experience is what I really meant to say. Personally I have an experience which is used for testing / development, and being able to quickly move those to the live place during updates would be ideal. It’s painful to go back and forth and add new configs, perhaps we should just move our dev place to be a sub-place of the live game.

The thing stopping me from using configs for things like my item data, is mostly just the way that they are structured currently. Maybe this isn’t even the correct use, but I’d personally love to have a way to store JSON in what is essentially one key, without having to just have a giant JSON array for say my items in the game.

I’d like to basically have a key that holds multiple JSON entries, so I could have it be separate items without just doing a giant array. Currently I just use Rojo to convert .json files into module scripts in my game, and have a .json file for each item. I don’t love this approach, so being able to use configs in their place would be great.

Another concern I have is keeping that JSON data up to date as my game transforms and adds properties to items. My item data is a lot more complex, so I use JSON schemas and such and an automatic script to update and add missing properties.

I would find it very tedious to have to edit an entire JSON array filled with hundreds of items to just edit one item. It is also tedious to have many keys for just item data, and I don’t even think there is a way to do that properly.

Here is an example of some item data in my game.

{
	"ID": "681e4ddbe6a4557d41c05732",
	"ParentId": "684c627ffc0de7bce31026d3",
	"Name": "M4A1",
	"Type": "Item",
	"Info": {
		"Name": "Name",
		"ShortName": "ShortName",
		"Description": "Description"
	},
	"Properties": {
		"BackgroundColor": "Black",
		"Width": 5,
		"Height": 2,
		"Weight": 3.5,
		"ModelPath": "Models/Items/Weapons/AssaultRifles/Standard/M4A1",
		"Caliber": "Caliber556x45mm",
		"Grids": [],
		"FireModes": ["SemiAutomatic", "Automatic"],
		"MaxDurability": 100,
		"Slots": [
			{ "ID": "OpticMod", "Filter": "687150f936e636a20395daec" },
			{ "ID": "Chamber", "Filter": "68713fe5942650fb1625c318" },
			{ "ID": "MagazineMod" }
		],
		"FireRate": 800,
		"RecoilForceBack": 25,
		"RecoilForceUp": 35,
		"RecoilAngle": 15,
		"RecoilDispersion": 8,
		"AddSizeDown": 0,
		"AddSizeRight": 0,
		"Ergonomics": 100
	}
}

Sorry if this just ended up being a giant feature request, I feel like I am basically just requesting a giant database at this point…

4 Likes
12

Gotcha. Yeah we are looking into #1. Part of the open cloud api is that you can also read your config values from your dev experience and push that entirely over the production experience to automate this process.

I’m confused about what you mean by a way to store multiple JSON in one key. What is your ideal scenario in storing and accessing this data? Can you provide some examples on what you might want to see?

5 Likes
13

Well, lets say I have item data stored for items in a complex game that are all objects. With this system, the only way to do this currently is to use the JSON object, but that would force me to have a JSON array which is just a giant list of my items, and for me personally editing that and keeping it up to date is a lot more tedious.

What I propose would be some form of perhaps a new type which just an array of JSON objects built it with some form of schema validation. It would make it far easier to edit the data of.

Currently the best way I can think of doing this is just compiling all my items together into one big array while keeping them in separate files.

Think of a game like Minecraft for example, if I was making that and using this to store my item data, I’d be forced to store it like

[
	{
		"Name": "Dirt",
		"Texture": "dirt.png",
		"Hardness": 0.5,
	},
	{
		"Name": "Stone",
		"Texture": "stone.png",
		"Hardness": 1.5,
	},
	{
		"Name": "Wood",
		"Texture": "wood.png",
		"Hardness": 0.8,
	},
	{
		"Name": "Water",
		"Texture": "water.png",
		"Hardness": 0.0,
	}
]

What I suggest is way to store it through the UI such as

Key: Items

+ Add Entry                  [Search:       ]

* Sub Key: Dirt
Value: {
		"Name": "Dirt",
		"Texture": "dirt.png",
		"Hardness": 0.5,
	   },
* Sub Key: Stone
Value: {
		"Name": "Stone",
		"Texture": "stone.png",
		"Hardness": 0.5,
	   },

Perhaps instead of JSON data in this case, we could even just have UI for this, like checkboxes for booleans and input fields for numbers / strings

and so on

This way I can query one key, get all my item data, and then be able to easily edit one item at a time and even be able to do things like search.

Having some form of JSON Schema validation just to make sure every entry fits a certain requirement would just be the icing on top to make sure its very usable and easy to keep potentially hundreds or thousands of items up to date

Again, maybe this is not the correct use of configs, but its certainly something I think would be super useful on Roblox for managing items as opposed to doing it all through modules.

The thought of doing this is what initially made configs so exciting when I heard they were in development.

5 Likes
14

This scope unfortunately doesn’t yet appear to be supported for OAuth 2.0 apps. Just wondering if this is expected to be supported in the short-term future?

3 Likes
15

Thank you! This is a great feature.

3 Likes
17

So cool to see how far Open Cloud has come & the range of APIs it supports now. Much love to you and your entire team for streamlining an actual good way for devs to interface with Roblox’s APIs. I remember the days of having to track down all the different swagger doc domains by looking on the site :frowning: was not fun to document all that

6 Likes
18

Hi! Thanks for reporting this. We’ve just enabled universe:read access for OAuth apps. You should be able to see it now. Let us know if you have any other issues here!

1 Like
19

Hey, thanks for the feature request. We’ve actually just enabled these config endpoints to now be callable via HttpService with API keys! You should see the docs updated accordingly soon

3 Likes
20

Any plans for publishing configs to rollout instantly instead of taking up to 5 minutes?

image
image963×140 17.7 KB

2 Likes