LuX documentation

LuX is BrickBit’s scripting environment. Existing .lua and .luau scripts and the Bridge API remain supported. Hosted scripts run in BrickBit's game environment.

Everything on this page is the server surface, which runs on the host. Scripts that run in the game client — on bricks, and client scripts — use a different API: see the Client API. The two do not share names, so a script written against one will not work in the other.

Every newly created game now publishes a default starter bundle containing a baseplate and spawnpoint, so new games start from a valid playable map instead of an empty unpublished state.

• Starter Game
• LuX API support and limits
• Script Types
• Bridge API
• Scheduler
• DataStore & Badges
• Example Server Script
• Replicated / Client Delivery
• Client API — services, classes, datatypes and enums

Hosted servers now expose game:GetService() for the services below alongside Bridge. Studio and hosted games do not yet have identical APIs. Unsupported services fail explicitly.

CollectionService currently operates on real Workspace parts. Authored part tags load from the published map; runtime tag changes are server-local, not saved or replicated. Folder/Model metadata is preserved but hosted hierarchy is still flat. Position and Size currently use Bridge-compatible {x, y, z} values.

HttpService offers JSON, GUID and URL utilities only. Network requests are disabled. SoundService audio import/playback remains Studio-local; audio publication and playback on other players’ devices are not implemented. Lighting, rigs and sky metadata can be delivered without implying that every runtime renders them.

Players.LocalPlayer is absent on servers. Use PlayerAdded or GetPlayers instead. Runtime/API compatibility is published at /v1/studio/lux/capabilities on the API domain. This describes the release; running game managers must be updated separately.

New games created from the site or Studio immediately receive a repo-owned starter bundle. That bundle contains:

• A default baseplate map
• A spawnpoint brick
• An empty scripts.manifest.json so hosted scripting metadata is present from day one

You can replace the starter map later by uploading a new BRK, but every game now starts from a real playable base state.

BrickBit stores script metadata in the bundle manifest and extracts it into runtime buckets. The script editor exposes the same script types.

Hosted authoring accepts .lua and .luau scripts.

Hosted LuX scripts interact with the running server through a focused game-service bridge. The bridge is versioned under Bridge.meta.version.

Inbound events

Bridge.on("playerJoin", function(player)
    print("joined", player.username)
end)

Bridge.on("playerLeave", function(player)
    print("left", player.username)
end)

Bridge.on("initialSpawn", function(player)
    print("spawned", player.username)
end)

Bridge.on("chat", function(player, message)
    print(player.username, message)
end)

Bridge.on("brickClick", function(player, brick, secure)
    print("clicked", brick.name, secure)
end)

Bridge.on("heartbeat", function(dt, timestamp)
    -- runs on the hosted heartbeat loop
end)

Outbound methods

The hosted Luau runtime exposes a first-pass scheduler. In the current host, wait-style operations return awaitable promises.

task.spawn(function()
    print("spawned now")
end)

task.delay(3, function()
    print("three seconds later")
end)

task.wait(1):await()
print("after wait")

wait(2):await()
print("after alias wait")

The bridge reuses BrickBit’s existing manager-side DataStore and badge clients. Async bridge calls return awaitable values from the Luau side.

Bridge.on("playerJoin", function(player)
    local visits = Bridge.datastore.getPlayer(player.userId, "visits"):await() or 0
    visits = visits + 1
    Bridge.datastore.setPlayer(player.userId, "visits", visits):await()

    local awarded = Bridge.badges.award(player.userId, 42):await()
    print("badge award result", awarded)
end)

Bridge.on("playerJoin", function(player)
    local visits = Bridge.datastore.getPlayer(player.userId, "visits"):await() or 0
    visits = visits + 1
    Bridge.datastore.setPlayer(player.userId, "visits", visits):await()
    Bridge.messagePlayer(player.userId, "Welcome back! Visits: " .. tostring(visits)):await()
end)

Bridge.on("initialSpawn", function(player)
    Bridge.createBrick({
        name = "SpawnMarker",
        position = { x = 0, y = 4, z = 0 },
        scale = { x = 4, y = 1, z = 4 },
        color = "#4a9eff",
        clickable = true,
    }):await()
end)

The server now writes non-server Luau assets into a stable delivery artifact: runtime/delivery.manifest.json. The manifest groups replicated and client scripts, keeps their order, and records relative paths inside the extracted runtime.

This is intentionally a server-side metadata step only. The native client fetch, ordering, and Luau execution path is still follow-up work and is not implemented in this repo yet.