This page as Markdown: https://bloxd.io/docs/how-to-variations.md. Every page of these docs, for AI agents: https://bloxd.io/docs/llms.txt

Variations

Custom games now support *variations*, which allow you to create your own alterations of gameplay.

Custom Games

In custom games, you can use api.getVariation() to get the current variation. For the base game, this will be default.

You can use api.matchmakeToVariation(playerId, variation) to connect a player to a different variation of your custom game. Use default to matchmake back to the original

Variation names must be between 1 and 32 characters. They can only contain letters, numbers, hyphens and underscores.

You can set the variation title using api.setClientOption(playerId, "customVariationTitle", "My Variation"). View the docs for the api.setClientOption or the customVariationTitle for more information.

Player database values (set with api.setPlayerDbValue, including persistent currencies) are shared across all variations of your custom game, so progress a player earns in the hub carries into 1v1, 2v2, etc. If you want a value to differ per variation, include the variation name in the key (e.g. `wins_${api.getVariation()}`).

Example

Here's an example inspired by the lobby arenas of games such as Clutch and Containment Breach. It creates a hub variation (default) and then variations for two different modes: Solos (1v1) and Duos (2v2)


let initialised = false
const variation = api.getVariation()

tick = () => {
    if (initialised) {
        return
    }

    if (api.getBlock(0, 0, 0) === "Unloaded") {
        // Wait for chunk to load
        return
    }


    if (variation === "default") {
        // Create platforms to matchmake players
        api.setBlockRect([0, 0, 0], [2, 0, 2], "Red Concrete") // 1v1
        api.setBlockRect([4, 0, 0], [6, 0, 2], "Blue Concrete") // 2v2
    }
    initialised = true
}

onPlayerJoin = (playerId) => {
    if (variation === "default") {
        api.setPosition(playerId, 3, 5, -3)
        api.setCameraDirection(playerId, [0, 0, 1])
    }
    else if (variation === "1v1") {
        api.setClientOption(playerId, "customVariationTitle", "Solos")
    } else if (variation === "2v2") {
        api.setClientOption(playerId, "customVariationTitle", "Duos")
    }
}

// Don't matchmake people if they've already been matchmade
/** @type {Record<PlayerId, boolean>} */
const playerHasMatchmade = {}

onBlockStandStart = (playerId, _x, _y, _z, blockName) => {
    if (variation !== "default") {
        return
    }
    if (playerHasMatchmade[playerId]) {
        return
    }

    if (blockName === "Red Concrete") {
        api.matchmakeToVariation(playerId, "1v1")
        playerHasMatchmade[playerId] = true
    } else if (blockName === "Blue Concrete") {
        api.matchmakeToVariation(playerId, "2v2")
        playerHasMatchmade[playerId] = true
    }
}

Worlds

Due to worlds being their own lobby, there is no possibility for variations. However, to test out custom games, you can reload lobby code as a specific variation. There are two main ways of doing this, however both require you to have at least Coder permissions or higher.

Logo