# 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()`](https://bloxd.io/docs/api-reference/3.md#getVariation) to get the current variation. For the base game, this will be `default`.

You can use [`api.matchmakeToVariation(playerId, variation)`](https://bloxd.io/docs/api-reference/3.md#matchmakeToVariation) 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`](https://bloxd.io/docs/api-reference/4.md#setClientOption) or the [`customVariationTitle`](https://bloxd.io/docs/client-options/1.md#customVariationTitle) for more information.

Player database values (set with [`api.setPlayerDbValue`](https://bloxd.io/docs/api-reference/5.md#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`)

```js

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.

- In the Code Editor, click the three dots on the right to open the `More Options` menu. Here, you can type in a variation and reload the lobby code to test as that variation
- If your code runs `api.matchmakeToVariation`, it will ask you if you want to reload to that variation.