Table of Contents

- About
- Usage
- Universe
- setApiKey
- setUniverseId
- DataStores
- GetDataStore
- GetOrderedDataStore
- SetScope
- GetAsync
- SetAsync
- UpdateAsync
- IncrementAsync
- RemoveAsync
- ListDataStoresAsync
- ListAsync
- MessagingService
- PublishAsync
- Place Management
- PublishAsync
- SaveAsync
- Pagination
- GetNextPageAsync
- GetPreviousPageAsync
- Assets
- GetOperation
- SetCreator
- SetPrice
- CreateAsset
- UpdateAsset

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.

$3

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:

universeId | Number | Id of the universe.
apiKey | String | The api key to use.

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

Universe

The Universe class holds services within itself and caches your api key, so you don't have to reuse it over and over again, but you can also change specific options when you create it.

$3

| Option | Type | Description |
| -------- | -------- | -------- |
| useMomentJs | Boolean | Will convert any times to Moment.js classes. |
| useDataStoreCache | Boolean | Determines whether DataStoreService should cache keys / values. |
| cacheUpdateInterval | Number | Determines how often the cache should update. |
| dataStoreScope | String | Changes the scope of the DataStore. |
| hideWarnings | Boolean | Hides warnings from the console. |

`js
const myUniverse = new Universe(00000000, "API_KEY", {
useMomentJs: false,
useDataStoreCache: true,
cacheUpdateInterval: 120000, // 2 minutes
dataStoreScope: "global"
});
`

$3

This function will overwrite the current apiKey

Key | String | The new api key.

`js
Universe.setApiKey("NEW-API-KEY");
`

$3

This function will overwrite the current universeId for the new one. If you don't want that, I recommend creating a new universe.

universeId | Number | The new universe id.

`js
Universe.setUniverseId(00000);
`

DataStores

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

$3

dataStoreName | String | Name of the datastore.
scope | String | Scope of the datastore.

`js
const CoinDataStore = Universe.DataStoreService.GetDataStore("Coins", "coins");
const GemsDataStore = Universe.DataStoreService.GetDataStore("Gems", "global");
`

$3

dataStoreName | String | Name of the datastore.
scope | String | Scope of the datastore.

`js
const coinOrderedDataStore = Universe.DataStoreService.GetOrderedDataStore("Coins", "coins");
`

$3

Lists the entries in the datastore based off the sort order and filters. Returns a Pages class.

sortOrder | String | The sort order of the datastore.
limit | Number | The limit of the datastore.
filters | String | The filters of the datastore.

`js
const myCoins = await coinOrderedDataStore.ListAsync("Asc", 10, "entry>=1&&entry<=10");
`

$3

This function will overwrite the current scope for the new one.

scope | String | The new scope.

`js
CoinDataStore.SetScope("global");
GemsDataStore.SetScope("global");
`

$3

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.

Key | String | The key to fetch.

`js
try {
const myCoins = await CoinDataStore.GetAsync("my-datastore-key");
console.log(myCoins.data);
} catch(err) {
console.error(err);
}
`

$3

To update a datastore entry, just use SetAsync.

Key | String | The key to set.
Value | any | Value to set.

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

$3

UpdateAsync uses 2 parameters to update a datastore entry. The first parameter is the key, the second is a function that will be ran on the current value.

Key | String | The key to update.
Function | function | Function to run on the current value (must return a value aswell).

`js
try {
await CoinDataStore.UpdateAsync("my-datastore-key", (oldValue) => {
return oldValue + 100;
});
} catch(err) {
console.error(err);
}
`

$3

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

Key | String | The key to increment.
incrementBy | Number | The value to increment by.

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

$3

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

Key | String | The key to remove.

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

$3

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!

`js
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.

$3

Topic | String | The topic of the message.
Message | String | The message to send.

`js
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.

$3

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.

placeId | Number | Id of the place to publish to.
routeToRbxFile | String | File's location.

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

$3

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

placeId | Number | Id of the place to save to.
routeToRbxFile | String | File's location.

`js
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.

$3

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.

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

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

$3

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

`js
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);
};
`

Assets

This section allows for developers to upload assets to Roblox's library and manage them.

$3

Gets an operation's id by it's asset name. Caching is required.

`js
const operationId = Universe.Assets.GetOperationId("MyAsset");
`

$3

Operations are automatically cached by this wrapper, you can access them by using GetOperationId with the asset's name. Then you can use this method to get the operation's information.

`js
Universe.Assets.GetOperation(operationId).then(console.log).catch(console.error);
`

$3

This method is required for using CreateAsset, it sets the creator of the asset.

creatorType | String | The type of creator to set. (User or Group)
creatorId | Number | The id of the creator.

`js
Universe.Assets.SetCreator("User", 000000);
`

$3

This method is required for using CreateAsset, it sets the price of the asset.

price | Number | The price of the asset.

`js
Universe.Assets.SetPrice(0);
``

$3

$3