Pacote de Missões

Este pacote de recursos está em beta.

O Pacote de Missões oferece funcionalidade pronta para uso para criar missões que os jogadores podem completar para obter recompensas e progredir em sua experiência. Todas as missões devem ter um ID, categoria e uma lista de tarefas que os jogadores devem concluir 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 na sua experiência 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 progressão.
Aumentar o engajamento destacando os vários sistemas do seu jogo e recompensando os jogadores por interagirem com eles.

Para informações sobre como fornecer aos jogadores objetivos e incentivos novos para que eles se sintam 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, áudio, plugins, vídeos e fontes. Você pode usar a Loja do Criador para adicionar um ou mais ativos diretamente a uma experiência aberta, incluindo pacotes de recursos!

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

Para levar os pacotes do seu inventário para sua experiência:

Adicione os pacotes Core e Missions 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 obter recompensas e progredir em sua experiência.
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 tile Pacote de Recursos Core, em seguida, no tile 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 que pode ser completada 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 concluir para finalizar a missão.

Condições de desbloqueio

Por padrão, as missões são desbloqueadas automaticamente para os jogadores 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 concluídos antes que a missão possa ser desbloqueada.
manualOnly	bool	Desativa 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 ainda 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 a missão for desbloqueada, mas não concluída antes desse horário, a missão será falhada.
repeatable	bool	A missão se desbloqueia novamente após ser completada.
repeatLimit	number	Se a missão for repetível, ela não pode ser repetida mais do que esse número de vezes.
repeatCooldownSeconds	number	Se a missão for repetível, existe um atraso antes que ela se desbloqueie.
expireSeconds	number	Se a missão estiver desbloqueada e não for completada dentro do número especificado de segundos, então 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 na experiência 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 os metadados.

Nome	Tipo	Descrição
displayName	string	Um nome para exibir para a missão na interface do usuário em vez do missionId.
description	string	Um bloco de texto maior 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 ficará 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 por uma missão. Isso é necessá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 tem zero tarefas, ela é reivindicável imediatamente após ser desbloqueada; se uma missão tem 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 dada.

As tarefas vêm em dois tipos:

Tarefas Temporizadas - Permitem que você inicie e pare a tarefa em diferentes pontos no tempo. Uma certa quantidade de tempo deve passar enquanto o cronômetro da tarefa está funcionando, então a tarefa é concluída.
Tarefas de Contagem - Permitem que você adicione ou defina o progresso da tarefa. Quando o progresso atinge um valor definido, a tarefa é concluída.

Ambos os tipos de tarefa compartilham os seguintes campos:

Nome	Tipo	Descrição
taskType	string	Especifica se o tipo de tarefa é contagem ou temporizada.
counter	object	(Opcional) O contador que esta tarefa rastreia. Contadores são armazenamento persistente específicos do jogador para um número ou um temporizador. Múltiplas tarefas podem rastrear um único contador; por exemplo, se mais de uma tarefa rastreia quantas moedas um jogador coletou, todas elas podem compartilhar o mesmo contador de “moedas”. Essas tarefas podem rastrear de forma independente 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 esse 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 mostrado na interface do usuário. numericType (Opcional string) - como o número de progresso na tarefa deve ser exibido. Fracionário, 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 ativa 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 atinge esse valor, a tarefa é concluída.

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

Campos de tarefas temporizadas

As tarefas temporizadas têm um valor alvo de tempo gasto e podem ser iniciadas e paradas. Quando a quantidade alvo de tempo é atingida, a tarefa é concluída.

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, ao invés de somente após ser iniciada.
includesOfflineTime	bool	Se a tarefa deve incluir o tempo gasto enquanto o jogador não está ativamente na experiência.

Configurar categorias

As categorias não precisam ser definidas explicitamente para serem usadas, pois a categoria para uma missão tem valores padrão que serão usados. 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 de tempo especificada passa, e podem ser desbloqueadas, completadas, e suas recompensas reclamadas novamente. Isso é separado de missões repetíveis, que podem ser repetidas 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 irá interagir com o pacote de recursos Missions.

Você precisa principalmente conectar quatro coisas uma vez que arraste o pacote de recursos Missions para sua experiência:

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

Adicione lógica à sua experiência para atualizar o progresso das tarefas ou os contadores aos quais o progresso está vinculado.

README
-- Aumenta o progresso em uma missão Pulando com uma tarefa Jumps
Missions.addProgressToTask(player, "Jumping", "Jumps", 1)

-- Inicia o cronômetro em uma missão TempoDeBatalha com uma tarefa TempoEmBatalha
Missions.startTimedTask(player, "BattlingTime", "TimeInBattle")

-- Para o cronômetro em uma missão TempoDeBatalha com uma tarefa TempoEmBatalha
Missions.stopTimedTask(player, "BattlingTime", "TimeInBattle")

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

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

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

Defina manipuladores de conclusão de missão e, opcionalmente, manipuladores de desbloqueio ou falha. Use o manipulador de conclusão para conceder as recompensas da missão em sua experiência.

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

Missions.setCompletionHandler(missionId, completeHandler)

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

Configurar constantes

As constantes para o pacote de recursos Core estão em dois lugares:

Constantes compartilhadas estão em ReplicatedStorage.FeaturePackagesCore.Configs.SharedConstants.
Constantes específicas do pacote, neste caso o pacote de recursos Missions, estão em ReplicatedStorage.Missions.Configs.Constants.

Além disso, você pode encontrar strings para tradução organizadas em um único lugar: 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 sua 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 ao redor hierarquicamente, o código não conseguirá encontrá-los, e você precisará fazer ajustes na MissionsUI.

Além disso, se sua experiência já tiver uma interface de usuário existente que você gostaria de integrar com o pacote de recursos Missions, o ModuleScript 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