GenerationService

Show Deprecated
Not Creatable
Service

GenerationService is a service that allows developers to generate 3D objects from text prompts utilizing Roblox's Cube 3D foundation model.

Mesh generation is a two step process:

  1. GenerateMeshAsync() starts the mesh generation process using a text prompt and other required parameters. It returns a unique identifier (generation ID) that can be used to retrieve the future result.
  2. LoadGeneratedMeshAsync() loads the generated mesh into the experience. The mesh is returned as a MeshPart containing an EditableMesh.

Currently, GenerationService only supports the following usage:

As a result, when a mesh generation request originates from a client, the client must send a signal to the server to initiate generation. Once the server determines that generation is complete, it should notify the appropriate client to call LoadGeneratedMeshAsync() and retrieve the mesh. Note that since the generated mesh is loaded with EditableMesh content and only on the client, it is not replicated to any other clients.

The following code illustrates this design pattern. See this demo experience for a more detailed example. Click the ⋯ button and Edit in Studio.

Code Samples

Adds server-side functionality to handle mesh generation requests from clients.

Server-side mesh generation
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local GenerationService = game:GetService("GenerationService")



-- Create a RemoteEvent for client-server communication

local meshGenerationEvent = Instance.new("RemoteEvent")

meshGenerationEvent.Name = "MeshGenerationEvent"

meshGenerationEvent.Parent = ReplicatedStorage



-- Event to send generation results back to clients

local generationResultEvent = Instance.new("RemoteEvent")

generationResultEvent.Name = "GenerationResultEvent"

generationResultEvent.Parent = ReplicatedStorage



-- Handle mesh generation requests from clients

meshGenerationEvent.OnServerEvent:Connect(function(player, prompt)

    print("Generating mesh for player", player.Name, "with prompt:", prompt)



    -- Generate the mesh on the server

    local success, generationId, contextId = pcall(function()

        return GenerationService:GenerateMeshAsync(

            {["Prompt"] = prompt},

            player,

            {},

            function(intermediateType, intermediateGenerationId, intermediateContextId)

                -- Send intermediate result to the requesting client

                generationResultEvent:FireClient(

                    player,

                    intermediateGenerationId,

                    true -- isIntermediate

                )

            end

        )

    end)



    if success then

        -- Send the final generation ID to the client

        generationResultEvent:FireClient(player, generationId, false)

        print("Successfully generated mesh with ID:", generationId)

    else

        -- Notify the client of failure

        generationResultEvent:FireClient(player, nil, false)

        warn("Failed to generate mesh:", generationId)

    end

end)

Adds client-side functionality to request mesh generation from the server and display the results.

Client-side mesh generation
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local GenerationService = game:GetService("GenerationService")

local Players = game:GetService("Players")



-- Connect to the RemoteEvents

local meshGenerationEvent = ReplicatedStorage:WaitForChild("MeshGenerationEvent")

local generationResultEvent = ReplicatedStorage:WaitForChild("GenerationResultEvent")



-- Local player

local player = Players.LocalPlayer



-- Store generated meshes

local generatedMeshes = {}



-- Function to request mesh generation

local function requestMeshGeneration(prompt)

    print("Requesting mesh generation for prompt: " .. prompt)

    meshGenerationEvent:FireServer(prompt)

end



-- Handle generation results from the server

generationResultEvent.OnClientEvent:Connect(function(generationId, isIntermediate)

    if not generationId then

        print("Generation failed")

        return

    end



    print(isIntermediate and "Loading intermediate result..." or "Loading final result...")



    local mesh = GenerationService:LoadGeneratedMeshAsync(generationId)



    if mesh then

        -- Clean up previous mesh if it exists

        if generatedMeshes[isIntermediate and "intermediate" or "final"] then

            generatedMeshes[isIntermediate and "intermediate" or "final"]:Destroy()

        end



        mesh.Parent = workspace



        -- Position the mesh in front of the player

        local character = player.Character

        if character and character:FindFirstChild("HumanoidRootPart") then

            local rootPart = character.HumanoidRootPart

            mesh:PivotTo(rootPart.CFrame * CFrame.new(0, 0, -10))

        end



        -- Store the mesh for cleanup

        generatedMeshes[isIntermediate and "intermediate" or "final"] = mesh

        print(isIntermediate and "Loaded intermediate result" or "Loaded final result")

    else

        print("Failed to load mesh")

    end

end)



-- Example usage

requestMeshGeneration("toy robot")

Summary

Methods

View all inherited from Instance
View all inherited from Object

Properties

View all inherited from Instance
View all inherited from Object

Methods

GenerateMeshAsync

Tuple
Yields

Starts the generation of a new 3D mesh from a text prompt and returns unique IDs used to track and retrieve the result. You can optionally receive intermediate results, such as the untextured mesh, by providing an intermediateResultCallback function. After the generation is complete, use LoadGeneratedMeshAsync() to load and display the generated mesh.

Rate limits

There is a rate limit of 5 generations per minute per experience. If you exceed this limit, further generation requests are blocked until the next minute.

Error codes

ErrorDescriptionRecommended developer action
Rate limit exceededThe maximum number of mesh generations has been exceeded for the minute.Wait until the rate limit resets.
Moderation failureThe mesh generation was flagged for moderation.Review and modify the prompt to ensure it adheres to Roblox's moderation guidelines.
Internal server errorAn unexpected issue occurred on the server.Retry the request later or check server status for issues.
Character limit exceededThe input prompt length for this generation request exceeded the limit.Reduce the number of characters in the Prompt string of the input dictionary.

Parameters

inputs: Dictionary

A dictionary containing the mesh generation prompts. Currently, the only supported key is the Prompt (string) that describes the mesh to generate.

player: Player

The Player requesting the generation.

options: Dictionary

Additional generation options. Currently, no options are supported.

intermediateResultCallback: function

A callback function triggered with intermediate generation results. Useful for retrieving early mesh versions (e.g. before textures are applied).


Returns

Tuple

A tuple of generation ID and context ID.

  • Generation ID: A unique ID returned for each invocation of GenerateMeshAsync().
  • Context ID: Not currently used.

Code Samples

Simple example showing how to use GenerateMeshAsync() to generate a mesh from a prompt.

Basic usage
local generationId, contextId = GenerationService:GenerateMeshAsync({["Prompt"] = "toaster"}, player, {})

Example showing how to use GenerateMeshAsync() with a callback for intermediate results.

Intermediate results callback
local generationId, contextId = GenerationService:GenerateMeshAsync({["Prompt"] = prompt}, player, {}, function(intermediateType, generationId, contextId)

    -- Add your logic here

end)

Example showing how to handle errors when generating meshes with GenerateMeshAsync().

Server-side generation with error handling
local success, generationIdOrError, contextId = pcall(function()

    return GenerationService:GenerateMeshAsync(

        {["Prompt"] = "robot toy"},

        player,

        {},

        function(intermediateType, intermediateId, intermediateContextId)

            -- Notify client about intermediate result

            generationResultEvent:FireClient(player, intermediateId, true)

        end

    )

end)



-- Handle a specific error code

if generationIdOrError == "Rate limit exceeded" then

    -- Wait for the rate limit to reset

elseif success then

    -- Send the final generation ID to the client

    generationResultEvent:FireClient(player, generationIdOrError, false)

end

LoadGeneratedMeshAsync

MeshPart
Yields

Retrieves and loads a mesh generated by GenerationService:GenerateMeshAsync() using the provided generationId. The mesh is returned as a MeshPart with EditableMesh content. Because editable meshes are not replicated, the loaded mesh is not replicated to any other clients and can only be loaded once per generationId.

Parameters

generationId: string

The unique ID returned by GenerateMeshAsync(). Identifies the mesh to load.


Returns

MeshPart

The generated mesh, returned as a MeshPart containing an EditableMesh.

Code Samples

Example showing how to load a generated mesh using LoadGeneratedMeshAsync().

LoadGeneratedMeshAsync - Load generated mesh
-- Take your generation ID generated on the server and load your generation

local mesh = GenerationService:LoadGeneratedMeshAsync(generationId)

mesh.Parent = workspace
View all inherited from Instance
View all inherited from Object

Events

View all inherited from Instance
View all inherited from Object