GenerationService
*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.
GenerationService é um serviço que permite que os desenvolvedores gerem objetos 3D a partir de prompts de texto utilizando o modelo de fundação de Cubo 3D da Roblox.
A geração de malha é um processo de dois passos:
- GenerateMeshAsync() inicia o processo de geração de malha usando um prompt de texto e outros parâmetros necessários.Ele retorna um identificador exclusivo (ID de geração) que pode ser usado para recuperar o resultado futuro.
- LoadGeneratedMeshAsync() carrega a malha gerada na experiência. A malha é retornada como uma MeshPart que contém um EditableMesh.
Atualmente, o GenerationService só suporta o seguinte uso:
- GenerateMeshAsync() deve ser chamado de scripts do servidor.
- LoadGeneratedMeshAsync() deve ser chamado de scripts de cliente.
Como resultado, quando um pedido de geração de malha se origina de um cliente, o cliente deve enviar um sinal ao servidor para iniciar a geração.Uma vez que o servidor determine que a geração está completa, ele deve notificar o cliente apropriado para chamar LoadGeneratedMeshAsync() e recuperar a malha.Observe que, uma vez que a malha gerada é carregada com conteúdo EditableMesh e apenas no cliente, ela não é replicada para outros clientes.
O seguinte código ilustra esse padrão de design.Veja esta experiência de demonstração para um exemplo mais detalhado.Clique no botão ⋯ e Editar no Studio .
Amostras de código
Adds server-side functionality to handle mesh generation requests from clients.
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.
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
Métodos
- GenerateMeshAsync(inputs : Dictionary,player : Player,options : Dictionary,intermediateResultCallback : function?):Tuple
Inicia a geração de uma nova malha 3D a partir de um prompt de texto e retorna IDs exclusivos usados para rastrear e recuperar o resultado.Após a geração estar concluída, use LoadGeneratedMeshAsync() para carregar e exibir a malha gerada.
Recupera e carrega uma malha gerada por GenerationService:GenerateMeshAsync() usando o fornecido generationId. A malha é retornada como uma MeshPart com conteúdo EditableMesh.
Propriedades
Métodos
GenerateMeshAsync
Inicia a geração de uma nova malha 3D a partir de um prompt de texto e retorna IDs exclusivos usados para rastrear e recuperar o resultado.Você pode opcionalmente receber resultados intermediários, como o mesh sem textura, fornecendo uma função intermediateResultCallback.Após a geração estar concluída, use LoadGeneratedMeshAsync() para carregar e exibir a malha gerada.
Limites de velocidade Há um limite de taxa de 5 gerações por minuto por experiência.Se você exceder esse limite, solicitações de geração adicionais são bloqueadas até o próximo minuto.
Códigos de erro | Erro | Descrição | Ação de desenvolvedor recomendada | | ------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | Limite de taxa excedido | O número máximo de gerações de malha foi excedido para o minuto.| Espere até que o limite de taxa seja redefinido. | | Falha de moderação | A geração de malha foi sinalizada para moderação.| Revise e modifique o prompt para garantir que ele adira às diretrizes de moderação do Roblox.| | Erro interno do servidor | Um problema inesperado ocorreu no servidor.| Tente novamente a solicitação mais tarde ou verifique o status do servidor para problemas.| | Limite de caracteres excedido | A duração do prompt de entrada para esta solicitação de geração excedeu o limite.| Reduza o número de caracteres na string Prompt do dicionário input. |
Parâmetros
Um dicionário que contém os prompts de geração de malha.Atualmente, a única chave suportada é a Prompt (string / cadeia / texto) que descreve a malha para gerar.
Opções adicionais de geração. Atualmente, nenhuma opção é suportada.
Uma função de retorno de chamada ativada com resultados de geração intermediários. Útil para recuperar versões de malha anteriores (por exemplo, antes que as texturas sejam aplicadas).
Devolução
Um tuple de ID de geração e ID de contexto.
- ID de geração: Um ID exclusivo retornado para cada invocação de GenerateMeshAsync() .
- ID de contexto: Não é usado atualmente.
Amostras de código
Simple example showing how to use GenerateMeshAsync() to generate a mesh from a prompt.
local generationId, contextId = GenerationService:GenerateMeshAsync({["Prompt"] = "toaster"}, player, {})
Example showing how to use GenerateMeshAsync() with a callback for intermediate results.
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().
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
Recupera e carrega uma malha gerada por GenerationService:GenerateMeshAsync() usando o ID de geração fornecido.A malha é retornada como uma MeshPart com conteúdo EditableMesh.Como malhas editáveis não são replicadas, a malha carregada não é replicada para nenhum outro cliente e só pode ser carregada uma vez por generationId .
Parâmetros
O ID exclusivo retornado por GenerateMeshAsync() . Identifica a malha a ser carregar.
Devolução
A malha gerada, retornada como um MeshPart contendo um EditableMesh .
Amostras de código
Example showing how to load a generated mesh using LoadGeneratedMeshAsync().
-- Take your generation ID generated on the server and load your generation
local mesh = GenerationService:LoadGeneratedMeshAsync(generationId)
mesh.Parent = workspace