DataModel
*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.
O Modelo de Dados (comumente conhecido como game) é a raiz da hierarquia pai-filho do Roblox.Seus filhos diretos são serviços, como Workspace e Lighting, que atuam como os componentes fundamentais de um jogo do Roblox.
Amostras de código
Demonstrates using game, the root instance of DataModel, to get services such as Workspace and Lighting.
local Workspace = game:GetService("Workspace")
local Lighting = game:GetService("Lighting")
-- Examples of modifying properties of these services
Workspace.Gravity = 20
Lighting.ClockTime = 4
Resumo
Propriedades
Descreve o ID do usuário ou grupo que possui o local.
Descreve o Enum.CreatorType do local, se o local é de propriedade de um usuário ou de um grupo.
Descreve o ID da experiência a que o local que está rodando no servidor pertence.
Não funcional. Historicamente descreveu o Enum.Genre do local como definido no site do Roblox.
Um identificador exclusivo para a instância do servidor de jogos em execução.
Representa como os jogadores no servidor são tratados pelo matchmaking.
Descreve o ID do local rodando no servidor.
Descreve a versão do local em que o servidor está rodando.
Descreve o ID do servidor privado do servidor, se o servidor for um servidor privado ou um reserved server.
Descreve o UserId do Player que possui o servidor privado se o servidor for privado.
Uma referência ao serviço Workspace de referência.
Métodos
Vincula uma função a ser chamada antes que o servidor desligue.
Retorna uma tabela que contém informações básicas sobre os empregos realizados pelo Agendadorde tarefas.
Retorna um array de Instances associado ao URL de conteúdo dado.
Retorna verdadeiro se o cliente terminou de carregar o jogo pela primeira vez.
Define o DataModel.PlaceId da instância de jogo atual para o ID de local dado placeId.
Define o DataModel.GameId da instância de jogo atual para o universoId dado.
Retorna o serviço especificado pela classe dada se já for criado, erros por um nome inválido.
Retorna o serviço com o nome de classe solicitado, criando-o se não existir.
Eventos
Incêndios quando o usuário solicita e aumenta ou diminui a qualidade gráfica usando os atalhos de teclado.
Incêndios no cliente quando o jogo termina de carregar pela primeira vez.
Dispara quando o local atual é saído.
Dispedido quando um serviço é criado.
Dispedido quando um serviço está prestes a ser removido.
Propriedades
CreatorId
Essa propriedade descreve o ID do usuário ou grupo que possui o local.Se a propriedade DataModel.CreatorType for 'Usuário', então o CreatorId será o Player.UserId do Proprietáriodo lugar.Se o DataModel.CreatorType for 'Grupo', então o CreatorId será o ID do grupo que possui o local.
Amostras de código
This code sample will print an output when the user that owns the game, or a member of the group that owns the game joins the server.
To run this script, place it inside a Script in ServerScriptService
local Players = game:GetService("Players")
Players.PlayerAdded:Connect(function(player)
if game.CreatorType == Enum.CreatorType.User then
if player.UserId == game.CreatorId then
print("The place owner has joined the game!")
end
elseif game.CreatorType == Enum.CreatorType.Group then
if player:IsInGroup(game.CreatorId) then
print("A member of the group that owns the place has joined the game!")
end
end
end)
CreatorType
Essa propriedade descreve o Enum.CreatorType do local, se o local é de propriedade de um usuário ou de um grupo.
Se o Enum.CreatorType for 'Usuário', então a propriedade DataModel.CreatorId descreverá o UserId da conta que possui o jogo.Se o tipo de Criador for 'Grupo', então ele descreverá o ID do grupo.
Amostras de código
This code sample will print an output when the user that owns the game, or a member of the group that owns the game joins the server.
To run this script, place it inside a Script in ServerScriptService
local Players = game:GetService("Players")
Players.PlayerAdded:Connect(function(player)
if game.CreatorType == Enum.CreatorType.User then
if player.UserId == game.CreatorId then
print("The place owner has joined the game!")
end
elseif game.CreatorType == Enum.CreatorType.Group then
if player:IsInGroup(game.CreatorId) then
print("A member of the group that owns the place has joined the game!")
end
end
end)
Environment
GameId
Essa propriedade descreve o ID da experiência a qual o local em execução no servidor pertence.
Veja também
- DataModel.PlaceId , que descreve o ID do local rodando no servidor
- DataModel.JobId , que é um identificador exclusivo para a instância do jogo do servidor em execução
- TeleportService , que é um serviço que pode ser usado para transportar Players entre jogos
Genre
Essa propriedade está quebrada e não deve ser usada.
Essa propriedade descreveu historicamente o Enum.Genre do local como definido no site do Roblox.
Essa propriedade, juntamente com DataModel.GearGenreSetting , não funciona mais corretamente devido aos gêneros existentes no site do Roblox que não estão refletidos no Enum.Genre enum.Como resultado, tentar ler essa propriedade pode gerar um erro.
JobId
Essa propriedade é um identificador exclusivo para a instância do servidor de jogos em execução.É um identificador universalmente exclusivo (UUID), o que significa que nenhum dois servidores, passados ou presentes, nunca terão o mesmo ID.
Padrão para uma string vazia no Studio.
Veja também
- TeleportService:GetPlayerPlaceInstanceAsync() que pode ser usado para recuperar o DataModel.JobId do servidor atual de um usuário.
- TeleportService:TeleportToPlaceInstance() que pode ser usado para teletransportar um Player para um servidor específico.
- DataModel.PrivateServerId descreve o ID do servidor privado ao qual a instância do servidor de jogos pertence.
- HttpService:GenerateGUID() , uma função que pode ser usada para gerar seus próprios UIDs.
MatchmakingType
Essa propriedade representa como os jogadores no servidor são tratados pelo matchmaking.Jogadores com diferentes MatchmakingTypes não podem estar em ou se teletransportar para o mesmo servidor.
Observe que essa propriedade só é válida no servidor DataModel e será o valor Enum.MatchmakingType.Default para todos os clientes, então só faça referência a essa propriedade dentro de um lado do servidor Script .
PlaceId
Essa propriedade descreve o ID do local rodando no servidor.
Se o local não foi publicado no Roblox, esse ID corresponderá ao modelo usado.
Veja também
- DataModel.GameId , que descreve o ID da experiência a que o local atual pertence
- DataModel.JobId , que é um identificador exclusivo para a instância do jogo do servidor em execução
- TeleportService , que é um serviço que pode ser usado para transportar Players entre locais
PlaceVersion
Essa propriedade descreve a versão do local em que o servidor está rodando.
Este número de versão corresponde ao número de versão mostrado na seção Histórico de Versões das configurações do local.Não é a versão atual do cliente Roblox.Essa propriedade é 0 para todas as experiências não publicadas.
Quando uma instância de servidor é criada para um local, ela usa a versão atual do local.Se o local for atualizado mais tarde enquanto este servidor estiver em execução, o servidor permanecerá em sua versão atual.
Essa propriedade pode ser usada para exibir um ScreenGui mostrando a versão atual do jogo para Players para ajudar com a depuração.
Amostras de código
This code sample will place a simple GUI in the StarterGui showing the place version the server is running at.
To use this sample, place it inside a Script in ServerScriptService.
local StarterGui = game:GetService("StarterGui")
local versionGui = Instance.new("ScreenGui")
local textLabel = Instance.new("TextLabel")
textLabel.Position = UDim2.new(1, -10, 1, 0)
textLabel.AnchorPoint = Vector2.new(1, 1)
textLabel.Size = UDim2.new(0, 150, 0, 40)
textLabel.BackgroundTransparency = 1
textLabel.TextColor3 = Color3.new(1, 1, 1)
textLabel.TextStrokeTransparency = 0
textLabel.TextXAlignment = Enum.TextXAlignment.Right
textLabel.TextScaled = true
local placeVersion = game.PlaceVersion
textLabel.Text = string.format("Server version: %s", placeVersion)
textLabel.Parent = versionGui
versionGui.Parent = StarterGui
PrivateServerId
Essa propriedade descreve o ID do servidor privado do servidor, se o servidor for um servidor privado.
Se o servidor não for um servidor privado, então esta propriedade será uma string / cadeia / textovazia.
Servidores privados
Servidores privados se referem ao seguindo:
- Servidores privados que os usuários podem comprar na página de jogos
- Servidores reservados, servidores privados criados pelo desenvolvedor usando TeleportService:ReserveServer()
PrivadoServidorId vs JobId
O PrivateServerId de um servidor é diferente do DataModel.JobId. O JobId é o identificador exclusivo da instância atual do servidor.
Servidores privados (servidores privados ou reservados) podem ter várias instâncias de servidor associadas a eles ao longo do tempo.Isso ocorre porque, embora apenas uma instância de servidor possa estar rodando de cada vez para um servidor privado, novas instâncias de servidor podem abrir e fechar à medida que os jogadores entram e saem do jogo.Por exemplo, nenhuma instância de servidor está rodando quando ninguém está jogando no servidor.O PrivateServerId será consistente em todas essas instâncias de servidor e o DataModel.JobId será único para cada uma delas.
Veja também:
- DataModel.PrivateServerOwnerId , uma propriedade que descreve o proprietário de um servidor privado
- TeleportService:ReserveServer() , uma função que cria um servidor reservado
Amostras de código
DataModel.PrivateServerId and DataModel.PrivateServerOwnerId can be used to detect if the current server instance is a standard server, a VIP server or a reserved server.
local function getServerType()
if game.PrivateServerId ~= "" then
if game.PrivateServerOwnerId ~= 0 then
return "VIPServer"
else
return "ReservedServer"
end
else
return "StandardServer"
end
end
print(getServerType())
PrivateServerOwnerId
Essa propriedade descreve o UserId do Player que possui o servidor privado se o servidor for privado.
Se o servidor for um servidor padrão ou reservado, então esta propriedade será definida como 0.
Essa propriedade poderia ser usada para identificar se um Player é o proprietário do servidor privado, por exemplo:
local Players = game:GetService("Players")
-- este é um servidor privado?
if game.PrivateServerId ~= "" and game.PrivateServerOwnerId ~= 0 then
-- ouça por novos jogadores sendo adicionados
Players.PlayerAdded:Connect(function(player)
-- verifique se o jogador é o proprietáriodo servidor
if player.UserId == game.PrivateServerOwnerId then
print("The private server owner has joined the game")
end
end)
end
Veja também:
- DataModel.PrivateServerId , uma propriedade que descreve o ID exclusivo de privado e reserved servers
Amostras de código
DataModel.PrivateServerId and DataModel.PrivateServerOwnerId can be used to detect if the current server instance is a standard server, a VIP server or a reserved server.
local function getServerType()
if game.PrivateServerId ~= "" then
if game.PrivateServerOwnerId ~= 0 then
return "VIPServer"
else
return "ReservedServer"
end
else
return "StandardServer"
end
end
print(getServerType())
Métodos
BindToClose
Vincula uma função a ser chamada antes que o servidor desligue.Se a função vinculada aceitar um parâmetro, ela passa Enum.CloseReason especificando a razão para o desligamento do servidor.
Você pode vincular múltiplas funções chamando BindToClose() repetidamente. Funções vinculadas são chamadas em paralelo e executadas ao mesmo tempo.
O servidor de experiência aguarda 30 segundos para todas as funções vinculadas pararem de executar antes de desligar.Após 30 segundos, o servidor desliga mesmo que as funções ainda estejam em execução.
Para verificar se a sessão atual não está no Roblox Studio, use RunService:IsStudio().Isso impede que funções vinculadas concluam sua execução em sessões de teste offline.
Quando você usa DataStoreService, você também deve usar BindToClose para vincular uma função que salva todos os dados não salvos para DataStores.Isso impede a perda de dados se o servidor desligar inesperadamente.
Veja também:
- Enum.CloseReason por razões para o desligamento do servidor de experiência.
- PluginGui:BindToClose() , que liga uma função a um botão de fechar PluginGui .
Parâmetros
Uma função chamada antes do servidor de experiência desligar.Se a função vinculada aceitar um parâmetro, ela passa Enum.CloseReason especificando a razão para o desligamento do servidor.
Devolução
Amostras de código
The following code sample is an example of how DataModel:BindToClose() can be used to save player data in the event of a server shutdown. In this example, player data is stored in a dictionary named playerData with UserIds as keys.
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")
local playerDataStore = DataStoreService:GetDataStore("PlayerData")
local allPlayerSessionDataCache = {}
local function savePlayerDataAsync(userId, data)
return playerDataStore:UpdateAsync(userId, function(oldData)
return data
end)
end
local function onServerShutdown(closeReason)
if RunService:IsStudio() then
-- Avoid writing studio data to production and stalling test session closing
return
end
-- Reference for yielding and resuming later
local mainThread = coroutine.running()
-- Counts up for each new thread, down when the thread finishes. When 0 is reached,
-- the individual thread knows it's the last thread to finish and should resume the main thread
local numThreadsRunning = 0
-- Calling this function later starts on a new thread because of coroutine.wrap
local startSaveThread = coroutine.wrap(function(userId, sessionData)
-- Perform the save operation
local success, result = pcall(savePlayerDataAsync, userId, sessionData)
if not success then
-- Could implement a retry
warn(string.format("Failed to save %d's data: %s", userId, result))
end
-- Thread finished, decrement counter
numThreadsRunning -= 1
if numThreadsRunning == 0 then
-- This was the last thread to finish, resume main thread
coroutine.resume(mainThread)
end
end)
-- This assumes playerData gets cleared from the data table during a final save on PlayerRemoving,
-- so this is iterating over all the data of players still in the game that hasn't been saved
for userId, sessionData in pairs(allPlayerSessionDataCache) do
numThreadsRunning += 1
-- This loop finishes running and counting numThreadsRunning before any of
-- the save threads start because coroutine.wrap has built-in deferral on start
startSaveThread(userId, sessionData)
end
if numThreadsRunning > 0 then
-- Stall shutdown until save threads finish. Resumed by the last save thread when it finishes
coroutine.yield()
end
end
game:BindToClose(onServerShutdown)
The following example prints the close reason to the output. It prints Done after three seconds, and then allows Roblox to shut down the experience server.
The close reason matches one of the values in Enum.CloseReason.
game:BindToClose(function(closeReason)
print(`Closing with reason {closeReason}`)
task.wait(3)
print("Done")
end)
GetJobsInfo
Retorna uma tabela que contém informações básicas sobre os empregos realizados pelo Agendadorde tarefas.
Na computação, um planejador de tarefas é um sistema responsável por executar tarefas chave em intervalos apropriados.
Você também pode encontrar estatísticas de agendador de tarefas ao vivo na janela do Agendador de Tarefas no Roblox Studio.
A primeira entrada na tabela retornada é um dicionário de referência que contém as estatísticas (ou cabeçalhos) disponíveis. Está no seguinte formato:
{["name"] = "name",["averageDutyCycle"] = "averageDutyCycle",["averageStepsPerSecond"] = "averageStepsPerSecond",["averageStepTime"] = "averageStepTime",["averageError"] = "averageError",["isRunning"] = "isRunning",}
As entradas subsequentes na tabela retornadas são dicionários que contêm as estatísticas acima para empregos realizados pelo Agendadorde tarefas. Por exemplo:
{["name"] = "Heartbeat",["averageDutyCycle"] = 0,["averageStepsPerSecond"] = 0,["averageStepTime"] = 0,["averageError"] = 0,["isRunning"] = false,}
Veja também:
Devolução
Uma tabela que contém informações sobre os empregos realizados pelo Agendadorde tarefas, veja acima para o formato.
Amostras de código
Here is an example of iterating over the job info.
local jobInfo = game:GetJobsInfo()
local jobTitles = jobInfo[1]
table.remove(jobInfo, 1)
local divider = string.rep("-", 120)
print(divider)
warn("JOB INFO:")
print(divider)
for _, job in pairs(jobInfo) do
for jobIndex, jobValue in pairs(job) do
local jobTitle = jobTitles[jobIndex]
warn(jobTitle, "=", jobValue)
end
print(divider)
end
GetObjects
Este método retorna um array de Instances associado ao URL de conteúdo dado.Pode ser usado para inserir conteúdo da biblioteca do Roblox.Não é possível inserir Sounds usando este método, pois eles não têm um Instance associado a eles e só têm uma URL de conteúdo.
Ao contrário de InsertService:LoadAsset() , DataModel:GetObjects() não requer que um recurso seja "confiável", o que significa que um recurso não precisa ser possuído pelo usuário logado ou criado pelo Roblox para ser inserido.No entanto, se o recurso não for de propriedade do usuário logado, ele deve estar disponível gratuitamente.
Devido ao contexto de segurança desta função, ela só pode ser usada por plugins ou pela barra de comando.Para uma alternativa que pode ser usada em Scripts e LocalScripts, veja InsertService:LoadAsset().
Parâmetros
O URL de conteúdo fornecido.
Devolução
Um conjunto de Instances associado ao URL do conteúdo.
Amostras de código
If you want to view a plugin's source code without installing it, you can use DataModel:GetObjects() to download the plugin. The code sample below includes a function that will take a plugin's website URL and insert the plugin into the currently selected Instance or the Workspace.
Due to GetObjects' security context, this function can only be used in the command line or in a plugin.
local Selection = game:GetService("Selection")
local WEB_URL = "plugin URL here"
local function downloadPlugin(webURL)
-- get the content URL
local contentID = string.match(webURL, "%d+")
local contentURL = "rbxassetid://" .. contentID
-- download the objects
local objects = game:GetObjects(contentURL)
-- decide where to parent them
local selection = Selection:Get()
local parent = #selection == 1 and selection[1] or workspace
-- parent the objects
for _, object in pairs(objects) do
object.Parent = parent
end
end
downloadPlugin(WEB_URL)
The content ID of a Decal on the Roblox website is associated with a Decal Instance rather than the actual content ID of the texture.
The code below, will use DataModel:GetObjects() to insert Decal objects into place and read their Decal.Texture property to obtain the image content IDs.
To use this code sample, enter the web URLs of the decals you'd like to convert into the array named IMAGES (as strings). A dictionary with the converted textures will be outputted.
local IMAGES = {
-- Insert Decal web URLs in an array here (as strings)
}
-- open the dictionary
local outputString = "textures = {"
-- utility function to add a new entry to the dictionary (as a string)
local function addEntryToDictionary(original, new)
outputString = outputString
.. "\n" -- new line
.. " " -- indent
.. '["'
.. original
.. '"]' -- key
.. ' = "'
.. new
.. '",' -- value
end
print("Starting conversion")
for _, webURL in pairs(IMAGES) do
-- get the content URL
local contentID = string.match(webURL, "%d+")
local contentURL = "rbxassetid://" .. contentID
local success, result = pcall(function()
local objects = game:GetObjects(contentURL)
return objects[1].Texture
end)
if success then
addEntryToDictionary(webURL, result)
else
addEntryToDictionary(webURL, "Error downloading decal")
end
task.wait()
end
print("Conversion complete")
-- close the dictionary
outputString = outputString .. "\n}"
-- print the dictionary
print(outputString)
IsLoaded
Quando toda a inicial Instances no jogo tenha terminado de se replicar ao cliente, essa função retorna verdadeiro.
A menos que sejam parentados para ReplicatedFirst , LocalScripts não execute até que o jogo tenha carregado.O seguinte trecho, executado a partir de um LocalScript em ReplicatedFirst rende até que o jogo tenha sido carregado:
if not game:IsLoaded() thengame.Loaded:Wait()end
Veja também:
- Ordem de replicação para um resumo mais detalhado do processo de carregamento.
- DataModel.Loaded , um evento que dispara quando o jogo foi carregado
- Instance:WaitForChild() , uma função que pode ser usada para esperar por um indivíduo Instance que possa se repetir sem ter que esperar que todo o jogo termine de carregar.
Devolução
Se o cliente terminou de carregar o jogo pela primeira vez.
Amostras de código
This sample demonstrates a custom loading screen with a basic TextLabel. The code should be placed in a LocalScript within ReplicatedFirst. To expand on this sample with loading screen animations, see the Custom Loading Screens article.
local Players = game:GetService("Players")
local ReplicatedFirst = game:GetService("ReplicatedFirst")
local player = Players.LocalPlayer
local playerGui = player:WaitForChild("PlayerGui")
-- Create a basic loading screen
local screenGui = Instance.new("ScreenGui")
screenGui.IgnoreGuiInset = true
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.BackgroundColor3 = Color3.fromRGB(0, 20, 40)
textLabel.Font = Enum.Font.GothamMedium
textLabel.TextColor3 = Color3.new(0.8, 0.8, 0.8)
textLabel.Text = "Loading"
textLabel.TextSize = 28
textLabel.Parent = screenGui
-- Parent entire screen GUI to player GUI
screenGui.Parent = playerGui
-- Remove the default loading screen
ReplicatedFirst:RemoveDefaultLoadingScreen()
--wait(3) -- Optionally force screen to appear for a minimum number of seconds
if not game:IsLoaded() then
game.Loaded:Wait()
end
screenGui:Destroy()
SetPlaceId
Essa função define o DataModel.PlaceId da instância do jogo para o ID de lugar dado placeId.
Configurar tanto DataModel.PlaceId e DataModel.GameId são necessários para acessar DataStoreService quando o local não é publicado, por exemplo, um arquivo local .rbxl.Veja abaixo um exemplo.Observe que obter acesso DataStoreService ao Studio requer a configuração Habilitar Acesso do Studio aos Serviços de API no painel Segurança das Configurações do Jogo.
local DataStoreService = game:GetService("DataStoreService")-- acesse o armazenamento de dados 'Dados' definindo PlaceId para placeId e GameId para universeId.game:SetPlaceId(placeId)game:SetUniverseId(universeId)local dataStore = DataStoreService:GetDataStore("Data")
Parâmetros
O ID para definir o DataModel.PlaceId para.
Devolução
SetUniverseId
Essa função define o DataModel.GameId da instância de jogo atual para o universoId dado.Isso é útil ao testar arquivos locais .rbxl que não foram publicados no Roblox.
Para acessar o DataStoreService em um local não publicado, tanto DataModel:SetUniverseId() e DataModel:SetPlaceId() devem ser configurar.
Parâmetros
O ID para definir o DataModel.GameId para.
Devolução
Eventos
GraphicsQualityChangeRequest
Incêndios quando o usuário solicita um aumento ou diminuição na qualidade gráfica usando os atalhos de teclado.
Este evento dispara sob as seguintes condições:
- Se o usuário pressionar F10 , este evento dispara com um argumento betterQuality de true.
- Se o usuário pressionar ShiftF10 , este evento dispara com um argumento betterQuality de false .
Este evento não fornece o nível atual de qualidade gráfica ou cobre todas as atualizações na qualidade gráfica.Por exemplo, as alterações feitas no menu de escape GUI principal não são registradas.
Você pode recuperar o Enum.SavedQualitySetting de um usuário usando UserGameSettings com o seguinte trecho:
UserSettings():GetService("UserGameSettings").SavedQualityLevel
Se as configurações gráficas do usuário forem definidas para automático, então o Enum.SavedQualitySetting será Automatic.Não há atualmente maneira de os desenvolvedores obter confiavelmente o nível atual de qualidade gráfica de uma máquina do usuário.
Parâmetros
Se o usuário solicitou um aumento ( verdadeiro ) ou uma diminuição ( falsa ) na qualidade dos gráficos.
Amostras de código
game.GraphicsQualityChangeRequest:Connect(function(betterQuality)
if betterQuality then
print("The user has requested an increase in graphics quality!")
else
print("The user has requested a decrease in graphics quality!")
end
end)
Loaded
Este evento dispara no cliente quando todo o inicial Instances no jogo tenha terminado de se replicar ao cliente.
A menos que sejam parentados para ReplicatedFirst , LocalScripts não execute até que o jogo tenha carregado.O seguinte trecho, executado a partir de um LocalScript em ReplicatedFirst rende até que o jogo tenha sido carregado:
if not game:IsLoaded() thengame.Loaded:Wait()end
Veja também:
- Ordem de replicação para um resumo mais detalhado do processo de carregamento.
- DataModel.Loaded , um evento que dispara quando o jogo foi carregado
- Instance:WaitForChild() , uma função que pode ser usada para esperar por um indivíduo Instance que possa se repetir sem ter que esperar que todo o jogo termine de carregar.