Pacote de Missões

Este pacote de recursos está em beta.

O pacote de recursos Missões oferece funcionalidade pronta para criar missões que os jogadores podem completar para alcançar recompensas e progredir em seu jogo. Todas as missões devem ter um ID, categoria e uma lista de tarefas que os jogadores devem completar para finalizar a missão. No entanto, a lista de tarefas pode estar vazia, permitindo que as recompensas da missão sejam reivindicadas imediatamente.

Usando as opções de personalização do pacote, você pode personalizar todas as missões para atender aos seus requisitos de jogabilidade exclusivos, como:

Criar missões que introduzam novos jogadores ao seu jogo e melhorem a retenção D1.
Focar na retenção D7 e D30 adicionando metas de médio a longo prazo e um senso de progresso.
Aumentar o engajamento ao destacar os vários sistemas em seu jogo e recompensar os jogadores por interagir com eles.

Para informações sobre como fornecer aos jogadores novos objetivos e incentivos para que eles estejam motivados a jogar mais e aumentar seu engajamento, veja Introdução ao Design de Quests.

Obter pacote

A Loja do Criador é uma aba da Caixa de Ferramentas que você pode usar para encontrar todos os ativos feitos pela Roblox e pela comunidade Roblox para uso em seus projetos, incluindo modelos, imagens, malhas, áudios, plugins, vídeos e fontes. Você pode usar a Loja do Criador para adicionar um ou mais ativos diretamente em um jogo aberto, incluindo pacotes de recursos!

Cada pacote de recursos requer o pacote de recursos Core para funcionar corretamente. Uma vez que os ativos dos pacotes de recursos Core e Missões estejam em seu inventário, você pode reutilizá-los em qualquer projeto na plataforma.

Para obter os pacotes do seu inventário para o seu jogo:

Adicione o Core e Missões ao seu inventário dentro do Studio clicando no link Adicionar ao Inventário no seguinte conjunto de componentes.

Pacote de Recursos Core
O pacote de recursos Core oferece lógica de armazenamento de dados compartilhados para todos os pacotes de recursos.
Pacote de Recursos de Missões
O Pacote de Recursos de Missões oferece funcionalidade para criar missões que os jogadores podem completar para alcançar recompensas e progredir em seu jogo.
No menu Janela do Studio ou na barra de ferramentas da aba Início, abra a Caixa de Ferramentas.
Na janela da Caixa de Ferramentas, clique na aba Inventário. A classificação Meus Modelos é exibida.
Clique no bloco Pacote de Recursos Core, depois no bloco Pacote de Recursos de Missões. Ambas as pastas de pacotes são exibidas na janela Explorer.
Arraste as pastas de pacotes para ReplicatedStorage.

Definir missões

Cada missão completável inclui um conjunto de tarefas que devem ser finalizadas para completar a missão, opções de configuração e metadados de exibição opcionais, todos os quais podem ser definidos dentro de ReplicatedStorage.Missions.Configs.Missions, com tipos exportados do script Types na mesma pasta.

Campos obrigatórios

Os seguintes campos são obrigatórios para cada missão.

Nome	Tipo	Descrição
missionId	string	A chave principal da tabela de Missões. Todas as missões são identificadas por sua própria string única.
categoryId	string	As missões devem pertencer a uma categoria e são agrupadas por categoria na interface do usuário.
tasks	table	Uma lista de tarefas que o jogador deve finalizar para completar a missão.

Condições de desbloqueio

Por padrão, as missões são desbloqueadas para os jogadores automaticamente e podem ser completadas exatamente uma vez. No entanto, você pode usar as seguintes opções de configuração opcionais para alterar esse comportamento.

Nome	Tipo	Descrição
prerequisites	table	Uma lista de outros missionIds que devem ser completados antes que a missão possa ser desbloqueada.
manualOnly	bool	Desabilita o desbloqueio automático da missão. Em vez disso, uma função deve ser chamada para desbloquear a missão. Quaisquer outras condições de desbloqueio também devem ser atendidas.
availableAfterUtc	bool	A missão não pode ser desbloqueada antes do horário especificado em UTC.
availableBeforeUtc	bool	A missão não pode ser desbloqueada após o horário especificado em UTC. Se for desbloqueada, mas não completada antes desse horário, a missão será falhada.
repeatable	bool	A missão se torna desbloqueada novamente após ser completada.
repeatLimit	number	Se a missão for repetível, não pode ser repetida mais do que esse número de vezes.
repeatCooldownSeconds	number	Se a missão for repetível, há um atraso antes que ela se torne desbloqueada.
expireSeconds	number	Se a missão estiver desbloqueada e não for completada dentro do número especificado de segundos, ela falhará.
expireCountOffline	bool	Se a missão tiver expireSeconds e expireCountOffline estiver definido como verdadeiro, o tempo em que o jogador não está realmente no jogo contará para a expiração da missão.

Metadados

As missões têm metadados que especificam como serão exibidas na interface do usuário de Missões. Você pode usar os seguintes campos opcionais para personalizar seus metadados.

Nome	Tipo	Descrição
displayName	string	Um nome a ser exibido para a missão na interface do usuário em vez do missionId.
description	string	Um bloco de texto mais longo que fornece informações ou contexto adicionais sobre a missão.
visibleAfterComplete	bool	Se definido como verdadeiro, a missão aparecerá na lista de missões mesmo após ser completada, mas marcada como completada.
visibleAfterFailed	bool	Se definido como verdadeiro, a missão aparecerá na lista de missões mesmo após ser falhada, mas marcada como falhada.
visibleBeforeUnlocked	bool	Se definido como verdadeiro, a missão será visível, mas bloqueada na lista de missões antes de estar disponível para conclusão.
invisibleWhileActive	bool	Se definido como verdadeiro, a missão será invisível mesmo enquanto estiver ativamente em progresso.
rewards	table	Uma lista de informações de exibição de recompensas. assetID (number) - O ID da imagem que é exibido na interface de missões sob as recompensas de uma quest. Isso é obrigatório se uma recompensa estiver presente. displayName (string) - O nome que é exibido na interface de missões sob o ícone.

Definir tarefas

Cada missão pode ter zero ou mais tarefas. Se uma missão tiver zero tarefas, ela pode ser reivindicada imediatamente após ser desbloqueada; se uma missão tiver uma ou mais tarefas, uma vez que as tarefas estejam completas, o jogador pode coletar quaisquer recompensas associadas à missão. Cada tarefa tem um taskId, que é a chave associada à tarefa para uma missão específica.

As tarefas vêm em dois tipos:

Tarefas Temporizadas - Permite que você inicie e pare a tarefa em diferentes momentos. Um certo período de tempo deve passar enquanto o cronômetro da tarefa está em execução, então a tarefa está completa.
Tarefas de Contagem - Permite que você adicione ou defina o progresso da tarefa. Quando o progresso atinge um valor definido, a tarefa está completa.

Ambos os tipos de tarefa compartilham os seguintes campos:

Nome	Tipo	Descrição
taskType	string	Especifica se o tipo de tarefa é de contagem ou temporizada.
counter	object	(Opcional) O contador que esta tarefa rastreia. Contadores são armazenamento persistente específico do jogador para um número ou um cronômetro. Múltiplas tarefas podem rastrear um único contador; por exemplo, se mais de uma tarefa rastrear quantas moedas um jogador coletou, então todas podem compartilhar o mesmo contador de “moedas”. Essas tarefas podem rastrear independentemente novas moedas coletadas, começando do zero, ou continuar contando a partir do valor do contador (todas as moedas já coletadas). counterId (string) - O ID do contador a ser rastreado. Use este ID para obter ou definir o valor do contador. continueFromCounter (Opcional bool) - Se definido como verdadeiro, o progresso da tarefa corresponderá diretamente ao valor do contador em vez da quantidade que aumentou.
metadata	object	(Opcional) Informações sobre como a tarefa é exibida na interface do usuário. displayName (string) - Nome da tarefa, usado quando exibido na interface do usuário. numericType (Opcional string) - como o número de progresso na tarefa deve ser exibido. Frações, ex. 5/10 ou 5k/50k Porcentagem, ex. 50% ou 10% LongFraction, ex. 5/10 ou 5000/50000 Booleano, ex. Incompleto
callToAction	object	(Opcional) Um botão que aciona uma função de retorno de chamada. callback (function) - Função acionada pelo botão callToAction. buttonText (string) - O texto que é exibido na interface do botão.

Campos de tarefas de contagem

As tarefas de contagem têm um valor obrigatório. Quando o progresso da tarefa atende a essa quantidade, a tarefa está completa.

Nome	Tipo	Descrição
goalCount	number	(Opcional) O progresso necessário para completar a tarefa.

Campos de tarefas temporizadas

As tarefas temporizadas têm uma quantidade alvo de tempo gasto e são iniciadas e paradas. Quando a quantidade alvo de tempo é atingida, a tarefa está completa.

Nome	Tipo	Descrição
goalSeconds	number	O número de segundos que devem passar para completar a tarefa.
startImmediately	bool	Se a tarefa deve começar a contar o tempo assim que for desbloqueada, em vez de apenas após ser iniciada.
includesOfflineTime	bool	Se a tarefa deve incluir o tempo gasto enquanto o jogador não está ativamente no jogo.

Configurar categorias

As categorias não precisam ser definidas explicitamente para serem usadas, pois a categoria de uma missão tem valores padrão que serão utilizados. No entanto, você pode configurar esses valores em ReplicatedStorage.Missions.Configs.Categories para adicionar efeitos adicionais à categoria. As categorias são identificadas por CategoryIds únicos, os mesmos referenciados na configuração das missões.

Nome	Tipo	Descrição
repeatDelaySeconds	number	(Opcional) Se definido, todas as missões na categoria são redefinidas toda vez que a quantidade especificada de tempo passa, e podem ser desbloqueadas, completadas e suas recompensas reivindicadas novamente. Isso é separado de missões repetíveis, que são repetíveis dentro de uma repetição de categoria dada.

Integrar lógica do servidor

Dê uma olhada em ReplicatedStorage.Missions.Server.Examples.MissionsExample, que mostra como seu servidor interagirá com o pacote de recursos Missões.

Você precisa conectar principalmente quatro coisas ao arrastar o pacote de recursos Missões para o seu jogo:

Defina missões em sua configuração de missões.

Adicione lógica ao seu jogo para atualizar o progresso das tarefas ou os contadores aos quais o progresso está vinculado.

README

-- Aumenta o progresso em uma missão Saltando com uma tarefa de Saltos
Missions.addProgressToTask(player, "Saltando", "Saltos", 1)

-- Inicia o cronômetro em uma missão Tempo de Batalha com uma tarefa de Tempo em Batalha
Missions.startTimedTask(player, "Tempo de Batalha", "Tempo em Batalha")

-- Para o cronômetro em uma missão Tempo de Batalha com uma tarefa de Tempo em Batalha
Missions.stopTimedTask(player, "Tempo de Batalha", "Tempo em Batalha")

-- Aumenta o progresso em todas as tarefas vinculadas ao contador de Saltos
CounterSystem.addCounter(player, "Saltos", 1)

-- Inicia o cronômetro em todas as tarefas temporizadas vinculadas ao contador de Tempo em Batalha
CounterSystem.startTimer(player, "Tempo em Batalha")

-- Para o cronômetro em todas as tarefas temporizadas vinculadas ao contador de Tempo em Batalha
CounterSystem.stopTimer(player, "Tempo em Batalha")

Defina manipuladores de conclusão de missões e, opcionalmente, manipuladores de desbloqueio ou falha. Use o manipulador de conclusão para premiar as recompensas da missão em seu jogo.

README

local function completeHandler(player: Player, missionId: Types.MissionId)
     print(`{player} completou a missão {missionId}`)
     -- Premie o jogador com suas recompensas.
 end

Missions.setCompletionHandler(missionId, completeHandler)

Desbloqueie missões que não são desbloqueadas automaticamente. A lógica do pacote de recursos Missões garante que todos os requisitos da missão sejam atendidos antes que a missão seja completada e suas recompensas sejam coletáveis.
README
Missions.unlockMission(player, "Manual")

Configurar constantes

As constantes para o pacote de recursos Core vivem em dois locais:

Constantes compartilhadas vivem em ReplicatedStorage.FeaturePackagesCore.Configs.SharedConstants.
Constantes específicas do pacote, neste caso o pacote de recursos Missões, vivem em ReplicatedStorage.Missions.Configs.Constants.

Além disso, você pode encontrar strings para tradução separadas em um local: ReplicatedStorage.FeaturePackagesCore.Configs.TranslationStrings.

Personalizar componentes da interface do usuário

Ao modificar os objetos do pacote, como cores, fonte e transparência, você pode ajustar a apresentação visual da interface de missões. Por exemplo, em ReplicatedStorage.Missions.Configs.Constants, você pode habilitar SingleTaskMode para exibir uma barra de progresso para uma tarefa diretamente na missão para missões que têm apenas uma única tarefa.

Se você mover qualquer um dos objetos hierarquicamente, o código não conseguirá encontrá-los, e você precisará fazer ajustes na MissionsUI.

Além disso, se seu jogo já tiver uma interface do usuário existente que você gostaria de integrar com o pacote de recursos Missões, o ModuleScript do cliente MissionsClient contém todas as funções necessárias para obter as informações sobre as missões de um jogador enviadas do servidor.

Pacote de Recursos Core

Pacote de Recursos de Missões