opencloud.js

Table of Contents

• About
• Usage
  • DataStores
    • GetAsync
    • SetAsync
    • IncrementAsync
    • RemoveAsync
    • ListDataStoresAsync
  • MessagingService
  • Place Management
    • PublishAsync
    • SaveAsync
  • Pagination
    • GetNextPageAsync
    • GetPreviousPageAsync

About

opencloud.js is an api wrapper meant to simplify the complexities with requesting to roblox's opencloud apis. This wrapper is built to mimic roblox's luau functions.

Installing

Use node package manager to install the package for use.

npm i @itsrune/opencloud.js

Usage

To start, you need to create a new Universe using the package. This is simple as demonstrated below:

const OpenCloud = require('@itsrune/opencloud.js');
const Universe = new OpenCloud(000000, "API_KEY");

This Universe class holds services within itself and caches your api key, so you don't have to reuse it over and over again.

DataStores

Datastores work just like with roblox. First we need to get the datastore itself then we are able to use it.

const DataStore = Universe.DataStoreService.GetDataStore("Coins");

GetAsync

Once you've gotten the datastore, you can then increment / set / get async to it. All requests to the api are asynchronous, make sure you handle their Promise's appropriately.

DataStore.GetAsync("my-datastore-key").then((myCoins) => {

}).catch(err => console.error);

SetAsync

To update a datastore entry, just use SetAsync.

try {
    await DataStore.SetAsync("my-datastore-key", 100);
} catch(err) {
    console.error(err);
}

IncrementAsync

In this case we could use IncrementAsync to update this datastore due to Coins being an integer.

try {
    await DataStore.IncrementAsync("my-datastore-key", 5); // Adds 5 coins.
} catch(err) {
    console.error(err);
}

RemoveAsync

Let's say we want to delete an entry, how would we do that? Well, this is where RemoveAsync would be used.

try {
    await DataStore.RemoveAsync("my-datastore-key");
} catch(err) {
    console.error(err);
}

GetDataStores

Too lazy to go into studio? Want to list your datastores on a front-end application? No problem! ListDataStoresAsync would be your function for this!

try {
    const DataStorePages = await Universe.DataStoreService.ListDataStoresAsync();
} catch(err) {
    console.error(err);
}

Note: This function will return the json data from the request, it will not be formatted. View the documentation for more information on how it's formatted.

Messaging Service

Messaging via external applications are incredibly powerful when it comes to roblox apps. Example of use: You have an update coming up and want to alert users before a shutdown occurs.

At the moment MessagingService has only 1 asynchronous function, PublishAsync, which takes 2 string parameters; The topic and the message to send.

const Universe = new OpenCloud(000000, "API_KEY");
const MessagingService = Universe.MessagingService;

try {
    await MessagingService.PublishAsync("Topic", "Hello World!");
} catch(err) {
    console.error(err);
};

Place Management

The place management api is a powerful api that allows developers to publish / save roblox games to an experience's place from an external source.

PublishAsync

Publishing a place is as simple as it seems. Go to the Place Management service within the Universe (Universe.PlaceManagementService) and call PublishAsync with a placeId and routeToRbxFile.

try {
    await PlaceManagementService.PublishAsync(0000, `${__dirname}/place.rbxlx`);
} catch(err) {
    console.error(err);
}

SaveAsync

SaveAsync works just like PublishAsync except instead it saves the place rather than instantly publishing it. This takes the same parameters as PublishAsync

try {
    await PlaceManagementService.SaveAsync(0000, `${__dirname}/place.rbxlx`);
} catch(err) {
    console.error(err);
}

Pagination

Pagination is the process that is used to divide a large data into smaller discrete pages. Roblox uses pagination with almost all apis that require a Cursor parameter within their urls.

GetNextPageAsync

This function is responsible for getting the next page of data and returning both it's data and the cursor associated to that data. This data will always be returned as an Array.

try {
    const DataStore = (new Universe(00000, "APIKEY")).DataStoreService;
    const pages = await DataStore.ListDataStoresAsync();

    const data = await pages.GetNextPageAsync();
} catch(err) {
    console.error(err);
}

GetPreviousPageAsync

Unlike GetNextPageAsync, this function gets the previous page. Note: Using this function before grabbing the next page will throw an error!

try {
    const DataStore = (new Universe(00000, "APIKEY")).DataStoreService;
    const pages = await DataStore.ListDataStoresAsync();

    const nextData = await pages.GetNextPageAsync();
    const prevData = await pages.GetPreviousPageAsync();
} catch(err) {
    console.error(err);
};