Como criar um temporizador de contagem regressiva personalizado

Você pode usar o dispositivo Temporizador, que executa um temporizador de contagem regressiva, mas criando seu próprio temporizador de contagem regressiva em Verse é uma maneira de personalizar o comportamento dele para se adequar exatamente ao que você precisa.

Este tutorial mostrará como criar seu próprio temporizador com Verse e usar um texto explicativo quando o tempo for adicionado à contagem regressiva. Começando de forma simples, você encontrará maneiras de melhorá-lo em cada um dos projetos.

Funcionalidades da linguagem Verse usadas

• if: a expressão if testa condições e acessa valores que podem falhar.

• block: este exemplo usa a expressão block para inicializar a interface de usuário quando o temporizador de contagem regressiva é criado.

• loop: a expressão loop atualiza a interface de usuário e termina quando a contagem regressiva chega a zero.

• spawn: uma expressão spawn inicia uma expressão assíncrona em qualquer contexto.

• message: o tipo "message" significa que o texto pode ser localizado, e a string que você usa para inicializar uma variável "message" é o texto e o idioma padrão da mensagem.

• classe: este exemplo cria uma classe Verse que gerencia e exibe a contagem regressiva.

• constructor: um "constructor" é uma função especial que cria uma instância da classe à qual ele está associado.

• Especificadores de acesso: Você pode usar os especificadores de acesso para definir o nível de acesso do código.

APIs Verse usadas

• Sleep: Com a API Sleep(), você pode escolher o período entre as atualizações da interface de usuário.

• Events: Você pode criar seus próprios eventos em Verse e adicionar funcionalidades personalizadas quando eles ocorrerem.

• Interface de usuário em Verse: Crie uma interface de usuário personalizada no jogo para exibir informações sobre o jogador e o jogo.

Instruções

Siga estas etapas para aprender a criar o próprio temporizador personalizado. O código completo está incluído no final deste guia como referência.

Como configurar o nível

Este exemplo usa os seguintes adereços e dispositivos:

• 1 dispositivo Botão: quando o jogador interage com o dispositivo, mais tempo é adicionado à contagem regressiva.

• 1 dispositivo Fim de Jogo: quando a contagem regressiva termina, esse dispositivo faz com que o jogo termine.

Siga estas etapas para configurar o nível:

1. Adicione um dispositivo Botão e um dispositivo Fim de Jogo ao nível.

2. Crie um novo dispositivo Verse chamado countdown_timer_example usando o Explorador Verse. Consulte os passos em Crie seu próprio dispositivo usando o Verse.

3. Adicione uma referência editável ao dispositivo Botão em countdown_timer_example chamada AddMoreTimeButton. Consulte as etapas necessárias passos em Personalizar propriedades de dispositivos.

   Verse

        countdown_timer_example := class(creative_device):
   		
            @editable
            AddMoreTimeButton : button_device = button_device{}
   

   Copy full snippet(4 lines long)

4. Adicione uma referência editável ao dispositivo Fim de Jogo em countdown_timer_example chamada EndGame.

   Verse

        countdown_timer_example := class(creative_device):
   		
            @editable
            AddMoreTimeButton : button_device = button_device{}
   		        
            @editable
            EndGame : end_game_device = end_game_device{}
   

   Copy full snippet(7 lines long)

5. Salve seu arquivo Verse e, no menu principal do UEFN, escolha Verse, Compilar código Verse para atualizar seu dispositivo no nível a fim de ver suas alterações no painel Detalhes do dispositivo.

Iniciando a contagem regressiva

Neste exemplo, você criará uma classe Verse que desenha a própria interface de usuário e gerencia a própria contagem regressiva.

Siga estas etapas para criar o temporizador de contagem regressiva personalizado:

1. Crie um arquivo Verse vazio chamado countdown_timer.verse.

2. Adicione os seguintes módulos Verse na parte superior do arquivo:

   Verse

        using { /UnrealEngine.com/Temporary/UI }
        using { /UnrealEngine.com/Temporary/SpatialMath }
        using { /Fortnite.com/UI }
        using { /Verse.org/Colors }
        using { /Verse.org/Simulation }
   

   Copy full snippet(5 lines long)

3. Crie uma classe chamada countdown_timer e adicione as seguintes variáveis:

   • Uma variável float chamada RemainingTime e inicializada como 0.0.

     Verse

                               var RemainingTime : float = 0.0
     

     Copy full snippet(1 line long)

   • Uma variável de widget de tela chamada Canvas.

     Verse

       var Canvas : canvas = canvas{}
     

     Copy full snippet(1 line long)

   • Um widget de texto chamado RemainingTimeWidget com uma cor de texto branca padrão.

     Verse

       RemainingTimeWidget : text_block = text_block{DefaultTextColor := NamedColors.White}
     

     Copy full snippet(1 line long)

   • Uma função que retorna uma mensagem chamada RemainingTimeText que leva um parâmetro de número inteiro para exibir o valor representado por RemainingTime.

     Verse

       RemainingTimeText<localizes>(CurrentRemainingTime : int) : message = "{CurrentRemainingTime}"
     

     Copy full snippet(1 line long)

   • Uma interface de usuário de jogador opcional chamada MaybePlayerUI e inicializada como false.

     Verse

       MaybePlayerUI : ?player_ui = false
     		
     

     Copy full snippet(2 lines long)

4. Sua classe deve ficar assim:

   Verse

        countdown_timer := class:
            MaybePlayerUI : ?player_ui = false
            var RemainingTime : float = 0.0
               var Canvas : canvas = canvas{}
               RemainingTimeWidget : text_block = text_block{DefaultTextColor := NamedColors.White}
               RemainingTimeText<localizes>(CurrentRemainingTime : int) : message = "{CurrentRemainingTime}"
   

   Copy full snippet(6 lines long)

5. Adicione uma expressão block para criar a interface de usuário em que o tempo aparece na parte superior central da tela. Uma expressão block em uma definição de classe é executada apenas quando a classe é instanciada, portanto, podemos criar a interface de usuário uma vez nessa expressão block.

   Verse

        countdown_timer := class:
            block:
                set Canvas = canvas:
                    Slots := array:
                        canvas_slot:
                            Anchors := anchors:
                                Minimum := vector2{X := 0.5, Y := 0.05}
                                Maximum := vector2{X := 0.5, Y := 0.05}
                            Alignment := vector2{X := 0.5, Y := 0.0}
                            Offsets := margin{Top := 0.0, Left := 0.0, Bottom := 0.0, Right := 0.0}
   
   Expand code Copy full snippet(18 lines long)

6. Adicione a função StartCountdown() para exibir a interface de usuário.

   Verse

        StartCountdown() : void =
            Print("Starting countdown")
   		
            if (PlayerUI := MaybePlayerUI?):
                PlayerUI.AddWidget(Canvas)
   

   Copy full snippet(5 lines long)

7. Em countdown_timer_example.verse, crie uma instância countdown_timer com uma referência à interface de usuário do jogador e ao tempo de início da contagem regressiva. Chame StartCountdown() em OnBegin() para que a contagem regressiva seja exibida assim que o jogo começar.

   Verse

        using { /Verse.org/Simulation }
        using { /Fortnite.com/Devices }
   
        countdown_timer_example := class(creative_device):
   
            @editable
            AddMoreTimeButton : button_device = button_device{}
   
            @editable
            EndGame : end_game_device = end_game_device{}
   
   Expand code Copy full snippet(23 lines long)

8. Se você testar agora, a interface de usuário não exibirá o tempo restante quando a contagem regressiva começar, então, em countdown_timer.verse, crie uma função chamada UpdateUI() que atualiza o valor atual da contagem regressiva na interface de usuário. Chame UpdateUI() em StartCountdown().

   Verse

        StartCountdown() : void =
            Print("Starting countdown")
   		
            if (PlayerUI := MaybePlayerUI?):
                PlayerUI.AddWidget(Canvas)
   		            
                # Update the UI when we start the timer to see the initial RemainingTime on screen
                UpdateUI()
   		
        UpdateUI() : void =
   
   Expand code Copy full snippet(12 lines long)

9. Agora, a contagem regressiva inicial aparece na interface de usuário, mas o valor não é atualizado a cada segundo. Para fazer isso:

   • Adicione a variável float TimerTickPeriod para representar a frequência em segundos de atualização da interface de usuário. Este exemplo usa um segundo.

     Verse

                               TimerTickPeriod : float = 1.0 # The timer "precision": how often, in seconds, it ticks.
     

     Copy full snippet(1 line long)

   • Crie uma função chamada RunCountdown(), que tenha o especificador suspends chamada StartCountdown(). Faça RunCountdown() aguardar o TimerTickPeriod antes de atualizar a interface de usuário e repita isso em loop. Defina o loop para terminar e faça com que a contagem regressiva desapareça da interface de usuário quando chegar a 0.0.

     Verse

       StartCountdown() : void =
           Print("Starting countdown")
     
           if (PlayerUI := MaybePlayerUI?):
               PlayerUI.AddWidget(Canvas)
     
               # Update the UI when we start the timer to see the initial RemainingTime on screen
               UpdateUI()
     
               spawn:
     
     Expand code Copy full snippet(24 lines long)

10. Ao testar, você deve ver a contagem regressiva começar em 30 e ser atualizada a cada segundo até que o temporizador chegue a 0 e a contagem regressiva desapareça da interface de usuário.

Como adicionar mais tempo

Com esse temporizador de contagem regressiva, adicione uma forma personalizada de incluir mais tempo e indicar o tempo adicionado. Este exemplo mostra como adicionar mais tempo à contagem regressiva e exibimos o tempo adicionado quando o jogador interage com o dispositivo Botão.

Siga estas etapas para adicionar tempo ao temporizador de contagem regressiva quando o jogador interagir com o dispositivo Botão:

1. Em countdown_timer.verse, crie uma nova função chamada AddRemainingTime() que atualiza a variável RemainingTime com o valor passado para a função no parâmetro float chamado Time e, em seguida, atualize a interface de usuário para mostrar o novo tempo restante.

   Verse

        AddRemainingTime(Time : float) : void =
            set RemainingTime += Time
   		
            # Immediately update the UI for better player feedback when time is added.
            UpdateUI()
   

   Copy full snippet(5 lines long)

2. Em countdown_timer_example.verse, faça a inscrição em InteractedWithEvent do dispositivo Botão e chame AddRainingTime() quando o jogador interagir com o dispositivo Botão.

   Verse

        using { /Verse.org/Simulation }
        using { /Fortnite.com/Devices }
   
        countdown_timer_example := class(creative_device):
   
            @editable
            AddMoreTimeButton : button_device = button_device{}
   
            @editable
            EndGame : end_game_device = end_game_device{}
   
   Expand code Copy full snippet(29 lines long)

3. Adicione um widget à classe countdown_timer para informar quanto tempo é adicionado à contagem regressiva quando o jogador interage com o botão.

   Verse

        AddedTimeWidget : text_block = text_block{DefaultTextColor := NamedColors.White} 
        AddedTimeText<localizes>(AddedTime : int) : message = " +{AddedTime}!"
   

   Copy full snippet(2 lines long)

4. Use os mesmos valores de posicionamento do widget `RemainingTime` para o novo `AddedTimeWidget`, mas altere os valores abaixo para que o tempo do texto explicativo seja exibido no canto superior direito do temporizador de contagem regressiva:

   • Para AddedTimeWidget, defina a margem esquerda em Offsets como 50.0.

   • Para RemainingTimeWidget, defina a margem superior no deslocamento como 25.0.

     Verse

                               countdown_timer := class:
                                   <# This block runs for each instance of the countdown_timer class.
                                   We can setup the canvas once here. #>
                                   block:
                                       set Canvas = canvas:
                                           Slots := array:
                                               canvas_slot:
                                                   Anchors := anchors:
                                                       Minimum := vector2{X := 0.5, Y := 0.05}
                                                       Maximum := vector2{X := 0.5, Y := 0.05}
     
     Expand code Copy full snippet(22 lines long)

5. Crie uma nova função chamada AddedTimeCallout() que atualiza o valor em AddedTimeWidget e exibe o texto explicativo por dois segundos antes de ocultar o widget novamente. Chame AddedTimeCallout() em AddRemainingTime().

   Verse

        AddRemainingTime(Time : float) : void =
            set RemainingTime += Time
   		
            # Immediately update the UI for better player feedback when time is added.
            UpdateUI()
   		
            # Fire a simple callout to show the time being added.
            spawn:
                AddedTimeCallout(Time)
   		
   
   Expand code Copy full snippet(19 lines long)

6. Ao testar, você deve ver a contagem regressiva começar em 30 e ser atualizada a cada segundo até que o temporizador chegue a 0 e a contagem regressiva desapareça da interface de usuário. Quando o jogador interage com o botão, vinte segundos são adicionados à contagem regressiva, e uma mensagem explicativa é exibida por dois segundos mostrando o tempo adicional acrescentado.

Sinalizando o fim do temporizador de contagem regressiva

Anteriormente neste tutorial, você usou o InteractedWithEvent de um dispositivo Botão para saber quando o jogador pressionou o botão e adicionou mais tempo ao temporizador de contagem regressiva. Porém, você também pode criar os próprios eventos personalizados que outras pessoas podem usar para saber quando algo acontece no código.

Este exemplo mostra como usar o comportamento de eventos personalizados abaixo:

• Signal(): essa função permite que qualquer pessoa que esteja aguardando o evento saiba que o evento aconteceu.

• Await(): essa função assíncrona bloqueia a execução do contexto delimitador até que o evento seja sinalizado.

Neste exemplo, você adicionará um evento ao temporizador de contagem regressiva para sinalizar quando a contagem regressiva termina para que possa ativar o dispositivo Fim de Jogo.

Siga estas etapas para adicionar um evento ao final da contagem regressiva.

1. Adicione um campo de evento chamado CountDownEndedEvent à classe :

   Verse

        CountdownEndedEvent : event() = event(){}
   

   Copy full snippet(1 line long)

   O event() é um tipo paramétrico, ou seja, retorna uma classe ou interface em vez de um valor ou instância de objeto. É por isso que o tipo é event() e por que você precisa inicializar sua constante CountDownEndedEvent com event(){} para imitar como uma classe é instanciada.

2. Atualize RunCountdown() para sinalizar CountdownEndedEvent de forma que outro código saiba que a contagem regressiva terminou antes de sair do loop.

   Verse

        RunCountdown()<suspends> : void =
            # We loop with the TimerTickPeriod.
            # The UI is also updated each time.
            loop:
                Sleep(TimerTickPeriod)
                set RemainingTime -= TimerTickPeriod
                UpdateUI()
   
                # Timer End
                if (RemainingTime <= 0.0):
   
   Expand code Copy full snippet(14 lines long)

3. Em countdown_timer_example.verse, aguarde CountdownEndedEvent associado a CountdownTimer e ative o dispositivo Fim de Jogo, porque sabemos que a contagem regressiva terminou quando o evento aconteceu.

   Verse

        OnBegin<override()<suspends> : void =
            AddMoreTimeButton.InteractedWithEvent.Subscribe(OnButtonInteractedWith)
            if:
                FirstPlayer := Self.GetPlayspace().GetPlayers()[0]
                PlayerUI := GetPlayerUI[player[FirstPlayer]]
            then:
                set CountdownTimer = countdown_timer{MaybePlayerUI := option{PlayerUI}, RemainingTime := InitialCountdownTime}
   		        
                CountdownTimer.StartCountdown()
                CountdownTimer.CountdownEndedEvent.Await()
   
   Expand code Copy full snippet(14 lines long)

4. Ao testar, você deve ver a contagem regressiva começar em 30 e ser atualizada a cada segundo até que o temporizador chegue a 0. Assim que a contagem regressiva terminar, ela desaparecerá da interface de usuário e o jogo terminará. Quando o jogador interage com o botão, vinte segundos são adicionados à contagem regressiva, e uma mensagem explicativa é exibida por dois segundos mostrando o tempo acrescentado.

Como preparar uma classe para ser usada por outro código

Você já criou a própria classe personalizada de temporizador de contagem regressiva e usou um dispositivo criado com Verse para instanciar e controlar esse temporizador.

Quando você cria as próprias classes personalizadas (e qualquer outro código), é importante especificar quem pode acessar a criação. Por exemplo, somente o temporizador de contagem regressiva deve ser capaz de criar e alterar a própria interface de usuário. Em Verse, você pode usar os especificadores de acesso para definir o nível de acesso do seu código.

Adicione o especificador public a qualquer identificador que queira que outras pessoas acessem, pois public significa que o identificador é universalmente acessível. Neste exemplo, todos os itens a seguir são usados no dispositivo countdown_timer_example e, portanto, devem ter acesso público:

• CountdownEndedEvent<public> : event() = event(){}

• StartCountdown<public>() : void =

• AddRemainingTime<public>(Time : float) : void =

Adicione o especificador private a qualquer identificador que não queira que outras pessoas acessem, pois private significa que o identificador só pode ser acessado no escopo atual, imediatamente delimitante (que neste caso é a classe countdown_timer).

Neste exemplo, estas linhas devem ter acesso privado:

• RemainingTimeWidget<private> : text_block = text_block{DefaultTextColor := NamedColors.White}

• AddedTimeWidget<private> : text_block = text_block{DefaultTextColor := NamedColors.White}

• AddedTimeText<localizes><private>(AddedTime : int) : message = " +{AddedTime}!"

• RemainingTimeText<localizes><private>(CurrentRemainingTime : int) : message = "{CurrentRemainingTime}"

• var Canvas<private> : canvas = canvas{}

• TimerTickPeriod<private> : float = 1.0

• RunCountdown<private>()<suspends> : void =

• AddedTimeCallout<private>(Time : float)<suspends> : void =

• UpdateUI<private>() : void =

Você pode usar um constructor para definir valores iniciais para uma nova instância de classe sem expor as variáveis de uma classe. Um construtor é uma função especial que cria uma instância da classe à qual ele está associado.

Crie um constructor para a classe countdown_timer que atualize as variáveis RemainingTime e MaybePlayerUI.

MakeCountdownTimer<constructor><public>(MaxTime : float, InPlayer : agent) := countdown_timer:
    RemainingTime := MaxTime
    MaybePlayerUI := option{GetPlayerUI[player[InPlayer]]}

As variáveis RemainingTime e MaybePlayerUI definidas no constructor não devem ter acesso público, mas não poderão ter acesso privado se estiverem definidas em um constructor. Você pode usar o especificador internal para essas variáveis, o que significa que o identificador só pode ser acessado no módulo atual e imediatamente delimitante.

• MaybePlayerUI<internal> : ?player_ui = false

• var RemainingTime<internal> : float = 0.0

Código completo

O código a seguir é o código completo para criar um temporizador de contagem regressiva personalizado.

Dois arquivos Verse foram criados neste exemplo.

countdown_timer.verse

using { /UnrealEngine.com/Temporary/Diagnostics }
using { /UnrealEngine.com/Temporary/UI }
using { /UnrealEngine.com/Temporary/SpatialMath }
using { /Verse.org/Simulation }
using { /Fortnite.com/UI }

MakeCountdownTimer<constructor><public>(MaxTime : float, InPlayer : agent) := countdown_timer:
    RemainingTime := MaxTime
    MaybePlayerUI := option{GetPlayerUI[player[InPlayer]]}

countdown_timer_example.verse

using { /Verse.org/Simulation }
using { /Fortnite.com/Devices }
using { /UnrealEngine.com/Temporary/UI }

countdown_timer_example := class(creative_device):

    @editable
    AddMoreTimeButton : button_device = button_device{}

    @editable

Por si só

Ao concluir este guia, você aprendeu a criar um temporizador de contagem regressiva personalizado.

Usando o que aprendeu, tente fazer o seguinte:

• Altere a taxa de contagem do temporizador e adicione um evento para cada marcação.

• Adicione as funcionalidades de pausa, retomada e reinicialização ao temporizador.