Open Cloud Engine API for Updating Scripts [Beta]

Hi Creators,

We envision a future where creators have the freedom to customize and automate their workflows. That’s why we’re developing tools and capabilities to allow third-party tools to interact seamlessly with Roblox content.

As a step on this journey, we’re thrilled to announce the beta of Open Cloud Engine API for updating scripts. Previewed at RDC’23, this beta introduces a way to interact with the scripts in your experience outside of the Studio UI. This technology allows you to create integrations with various third party applications. For example, you could use Google Sheets to update items sold in a shop.

This release also previews our new serialization format crafted for defining, persisting, and mutating Roblox content by third-party tools. The format is still in its developmental stage and subject to change. We highly value your feedback as we continue to refine it.

Example of using Open Cloud Engine API to update items sold in a shop from a Google Sheet

How It Works

Our new Open Cloud Engine API allows you to programmatically read and write scripts. Note that this API is only available for Team Create-enabled experiences. To explain the new API, we’d like to clarify some terms:

  • Instance: Instance is the base class for all classes in the Roblox class hierarchy. Every other class that the Roblox engine defines inherits all of the members of Instance. It is not possible to directly create Instance objects. You can read more about Instances here.
  • Instance ID: Instance ID is a unique identifier for each Instance in a place, which is a crucial part of referencing specific Instances in the new API.
  • Instance Types: There are many types of Instances, and while the new API is scoped at the Instance-level, deeper support is provided for four specific Instance Types: Script, LocalScript, ModuleScript, and Folder. Over time, we plan to extend support for more Instance Types.

Now, onto the actual API. The new operations you can perform are:

  • Get Instance: Retrieves metadata about a specific Instance and, for Script, LocalScript, and ModuleScript Instance Types, the actual content of the script.
  • List Children: Lists all children of a specific instance by specifying an instance ID.
  • Update Instance: Update the Source property on Script, LocalScript and ModuleScript instance types. If un-supported instance types are selected, or a property other than Source is chosen, the API will return an error message indicating that the selected item is not available for editing.
  • Get Operation: Provides the current status of the operation.

You can find a comprehensive user guide in the Open Cloud API documentation, which also includes step-by-step instructions to set up a reference implementation that lets you try the functionality with minimal coding.

We’d like to highlight some key aspects to help you harness and navigate the API effectively:

  • It operates asynchronously. This means every operation requires at least two API calls – one for the operation request and another for the operation results.
  • It prevents conflicts by honoring scripting behaviors in Studio, such as Live Scripting. It will return a failure when potential conflict is encountered.

Creator-friendly Serialization Format

As part of this release, we are previewing our new serialization format for defining, persisting, and mutating Roblox content locally or via Open Cloud APIs.

In the Open Cloud API, the serialization format only supports a small subset of Instance Types and Properties (see Open Cloud API documentation), but we intend for it to become a general format that can describe all Roblox content!

Please note that while the format is in preview, it will evolve and likely incur major changes, including changes that break backwards compatibility. We welcome your feedback as you test it through the Open Cloud Engine API beta and other features we have planned this year. We will continue communicating updates on the format and announce when we can commit to its long-term stability.

We will also make a separate announcement dedicated to the format shortly to provide more information about its current state, and our vision for the future.

[
    {
        "Id": "48369942-10f2-4c7d-9bdd-df944d37ccb7",
        "Parent": "844ae97e-06a8-4b62-81f3-a84bf34f7a6e",
        "Name": "MyFolder",
        "Details": {
            "Folder": {}
        }
    },
    {
        "Id": "9f58a468-10d1-494e-b9f4-0879e1a88857",
        "Parent": "48369942-10f2-4c7d-9bdd-df944d37ccb7",
        "Name": "MyModule",
        "Details": {
            "ModuleScript": {
                "Source": "print(\"Hello world!\")\n"
            }
        }
    },
    {
        "Id": "05012dd6-d3b9-4cc4-a928-c655b623653d",
        "Parent": "48369942-10f2-4c7d-9bdd-df944d37ccb7",
        "Name": "MyScript",
        "Details": {
            "Script": {
                "Source": "require(script.parent.MyModule)",
                "RunContext": "Legacy",
                "Enabled": true
            }
        }
    }
]

Example of the serialization format in JSON representing a Folder Instance with a Script and Module Script as its children

This is Just the Beginning

We believe that you should be free to use any tool you desire to unleash your creativity and increase your productivity. We’re working on more solutions that help improve your workflows, and our upcoming roadmap initiatives are:

  • Studio Luau File Sync allows you to export/import scripts between Studio and disk, so that you can use any IDE or version control system.
  • Open Cloud Engine API for running scripts, which enables cloud-based unit testing and Luau code execution.

More broadly, we are investing in extending the Roblox architecture to better facilitate work for large teams, and teams that may have specific third party tools that they prefer. Stay tuned for these updates. We’re really excited about unlocking your creative energy by opening more of our platform through direct Open Cloud APIs.

Your Voice Matters

We’re eager to hear your thoughts and welcome your suggestions. Your input will be instrumental in refining the tools that truly empower creators like never before. Please let us know if you have any questions or feedback as you try this beta.

Thanks to the team who made this happen @twberg, @itsFrank17, @MrMark2u, @bluestann, @eugenekim159, @icemountainrbx, @PureBigMadBoatMan, @DevelopmentDeadline, @flatcharacter, @crowsegg, @yipiokay !

264 Likes

This topic was automatically opened after 11 minutes.

Wow, what an update.

It’s exciting to see roblox embracing open cloud, and hopefully will continue to bring out game-changing features in 2024.

I’m most excited for the long awaited open cloud for group ranking, since the group read methods were released late last year, it’s already changed a lot of stuff for the better, and hopefully the write methods will be even greater!

GG roblox :slight_smile:

29 Likes

Wow awesome, this will definitely be useful for live events! This will also be useful to import data!

11 Likes

Excited to see how developers will use this!

21 Likes

Seems like an exciting feature! Does it synchronize live with open servers or only within studio?

12 Likes

we continue to beg for a headless roblox studio

12 Likes

If anyone is curious, the Rojo team is actively thinking about how to support this going forward but right now we can’t for a few long and boring reasons.

The issue ends up being that Rojo doesn’t persist the IDs of instances, so you’ll have to fetch them before you can use it. This is a problem you might run into without Rojo, but it’ll be a lot more prevalent if you use Rojo. Doubly so if you’re fully managed.

18 Likes

That’s a great update! I already have some use cases in mind where this can be implemented.

5 Likes

It’s long overdue, it’ll be great when they add this mechanic!

7 Likes

Time to write a whole bunch of tooling so that the non-programmers on our team can easily change many constants!

Does the updated code get pushed into live-servers or just studio?

9 Likes

This is amazing to hear! I hope that, however it is implemented, it supports non-game projects. Unit testing libraries is a massive use case, and they are often not tied to a specific game on the platform. A fully offline, command-line version of Studio is still the optimal solution for this particular use case.

10 Likes

This is honestly great, thank god ROBLOX didn’t release another bad update.

8 Likes

Sorry to ask but I just want to be clear, this isn’t an issue as long as we don’t intend to use Open Cloud Engine while using Rojo, right? Or does this somehow cause issues for Rojo users regardless if we intend to implement it into our workflow?

5 Likes

We have lots more coming to Open Cloud in 2024. :slight_smile:

10 Likes

This is an edit-time only API so it read/writes state from the active Team Create server.

9 Likes

There should probably be a way to get this crucial ID from Lua/Roblox Studio

10 Likes

Could this be used to sync scripts across multiple places? If so, then that would be a pretty good use case.

3 Likes

This is only a concern if you want to use this beta alongside Rojo. Rojo itself is fine.

3 Likes

We can’t wait to see what creativity you bring!

4 Likes