Integrating Bloxstrap functionality into your game

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 what it can do, specifically setting a user's rich presence status from in-game. There's also a demo place for demonstrating rich presence configuration specifically, courtesy of 1011025m.

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.

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"
    }
})

Module exports

Types

RichPresence {
	details:     string?,
	state:       string?,
	timeStart:   number?,
	timeEnd:     number?,
	smallImage:  RichPresenceImage?,
	largeImage:  RichPresenceImage?
}

RichPresenceImage {
	assetId:     number?,
	hoverText:   string?,
	clear:       boolean?,
	reset:       boolean?
}

Functions

SendMessage(command: string, data: any)   -- Used for sending an RPC message. Avoid using this, as every command available will have a dedicated function for it.
SetRichPresence(data: RichPresence)       -- Used for configuring the user's Discord rich presence activity.

Additional information

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.

Implementation

This section details how BloxstrapRPC is implemented on the application side. If you're looking to implement BloxstrapRPC (e.g. making a standalone cross-platform rich presence server), 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 BloxstrapRPC Helper Module is essentially doing:

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.

Just a note: All the features that use BloxstrapRPC also require activity tracking to work. So, we're planning to document the logic required for activity tracking, as well as release a library for it. For now, if you need more details about how to implement this yourself, please contact me over Discord.