Skip to content

Integrating Bloxstrap functionality into your game

Jump to bottom
pizzaboxer edited this page Oct 16, 2024 · 64 revisions

Note

This topic is open for discussion and feedback on the corresponding DevForum article.

If you're a game developer on Roblox, you may be interested in utilizing the features that Bloxstrap has to offer - but how?

Bloxstrap features the ability for one-way data communication between it and Roblox scripts, thanks to activity tracking. This feature is known as BloxstrapRPC, and allows you to send a command from a Roblox script in order to invoke a function inside Bloxstrap. Communication is ratelimited to one command per second.

Here's a video demonstrating how it can be used to set a user's rich presence status from in-game.

If you want to play around with this yourself, see the following places:

The BloxstrapRPC SDK is what you use to interact with BloxstrapRPC from inside of your scripts. It's a script module that provides everything that you will need. Though, be aware that any commands you send must be done from the client-side through a LocalScript. You can download it via the Roblox marketplace, roblox-ts, Wally, or GitHub.

You should be aware of all the types and methods that it makes available. Luau and Typescript linting should help you out, but they're also listed down below for your reference.

BloxstrapRPC SDK Documentation

Type: RichPresence

details:     string?
state:       string?
timeStart:   number?
timeEnd:     number?
smallImage:  RichPresenceImage?
largeImage:  RichPresenceImage?

Type: RichPresenceImage

assetId:    number?
hoverText:  string?
clear:      boolean?
reset:      boolean?

Function: SetRichPresence

SetRichPresence(data: RichPresence)

Used for configuring the user's Discord rich presence activity.

When it comes to structuring a RichPresence type, here's what to keep in mind.

  • A value of nil/no setting indicates that the current value on the rich presence should be kept as what it already is.
  • Therefore, by default, field values will persist. So. you don't need to re-set the entire presence just to update one field.
  • The values for timeStart and timeEnd expect a UTC epoch timestamp in seconds, which can be obtained with os.time().
    • If 'timeEnd' is not specified, then the presence will show the time elapsed since 'timeStart'.
    • Else, it will show time remaining until 'timeEnd'.
  • For erasing fields:
    • string property types can be set as a blank string.
    • number property types can be set as zero.
    • RichPresenceImage property types can have their 'clear' property set to true. (you will need to reset it to have it show again)
  • For reverting fields to their defaults:
    • string property types can be set as "<reset>".
    • RichPresenceImage property types can have their 'reset' property set to true.

Example usage:

local BloxstrapRPC = require(game.ReplicatedStorage.BloxstrapRPC)

local timestamp = os.time()

BloxstrapRPC.SetRichPresence({
    details = "Example details value",
    state = "Example state value",
    timeStart = timestamp,
    timeEnd = timestamp + 60,
    largeImage = {
        assetId = 10630555127,
        hoverText = "Example hover text"
    },
    smallImage = {
        assetId = 13409122839,
        hoverText = "Example hover text"
    }
})

Function: SetLaunchData

SetLaunchData(data: string)

Sets the launch data for invite deeplinks generated by Bloxstrap.

It does this in two places; to allow people to join through Discord Rich Presence, or to create a deeplink that the user can share with their friends to invite them in-game.

This can be used to check if a player is joining through someone's Rich Presence activity, for example.

Implementation

This section details how BloxstrapRPC is implemented on the application side. If you're looking to implement BloxstrapRPC (e.g. with your own custom launcher), you should keep reading.

BloxstrapRPC works by tracing Roblox's log file as it's running, looking for any print entries that are prefixed with [BloxstrapRPC]. After this identifier comes the actual message itself, provided in JSON form, with attributes for command and data. command is the name of the procedeure that should be executed, and data is the data it should use. Fairly straightforward.

This way, scripts are able to send data to external applications simply by just printing a string to the output. To better demonstrate, here's what the SDK is essentially doing whenever you send a message:

print('[BloxstrapRPC] {"command": "SetRichPresence", "data": {"details": "hi"}}')

The aim for BloxstrapRPC is for it to be the standard for Roblox scripts signalling data to external applications, not just for it to be used in Bloxstrap. For example, if you want to make your own Roblox rich presence handler application, while also wanting to implement the ability for games to set their own rich presence, it's best to implement it according to BloxstrapRPC instead of devising your own system, if you can. This way, you don't have to worry too much about the implementation details, and you're able to ensure compatibility with as many Roblox games as possible.

All BloxstrapRPC features heavily rely on knowing the user's current activity state (what game they're in, etc). Bloxstrap handles this through its activity tracker algorithm.

We don't offer any libraries to handle activity tracking (we kind of can't), but you're free to implement it yourself in your programming language of choice. It essentially works a lot like a script interpreter.

Areas of interest:

Something to note is that BloxstrapRPC relies on the existence of nullable types, so that attributes can remain undefined when not set. This is how fields can persist their previous values with SetRichPresence. This may be problematic if your language doesn't support nullable types (like Go, which will assume type defaults).

See something here on this page that is incorrect or you otherwise think should be changed? Please open an issue!

Clone this wiki locally