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.
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 !
