GenerationService

Mostrar obsoleto

Não criável

Serviço

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:

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.
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:

GenerateMeshAsync() must be called from server scripts.
LoadGeneratedMeshAsync() must be called from client scripts.

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.

Amostras de código

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

Resumo

Propriedades

Ver todos os herdados de Instance

Ver todos os herdados de Object

Métodos

GenerateMeshAsync(inputs : Dictionary,player : Player,options : Dictionary,intermediateResultCallback : function?):Tuple
Rendimentos
Starts the generation of a new 3D mesh from a text prompt and returns unique IDs used to track and retrieve the result. After the generation is complete, use LoadGeneratedMeshAsync() to load and display the generated mesh.
LoadGeneratedMeshAsync(generationId : string):MeshPart
Rendimentos
Retrieves and loads a mesh generated by GenerationService:GenerateMeshAsync() using the provided generationId. The mesh is returned as a MeshPart with EditableMesh content.

Ver todos os herdados de Instance

Ver todos os herdados de Object

Eventos

Ver todos os herdados de Instance

Ver todos os herdados de Object

Propriedades

Ver todos os herdados de Instance

Ver todos os herdados de Object

Métodos

GenerateMeshAsync

Tuple

Rendimentos

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

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

Parâmetros

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).

Devolução

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.

Amostras de código

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

Rendimentos

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.

Parâmetros

generationId: string

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

Devolução

MeshPart

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

Amostras de código

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

Ver todos os herdados de Instance

Ver todos os herdados de Object