RetroAchievements · wescopeland · Dec 2, 2024 · Nov 25, 2024 · Nov 25, 2024 · Nov 25, 2024
diff --git a/...les/circumvent-the-problem-of-a-counter-incrementing-twice-in-the-same-frame.md b/...les/circumvent-the-problem-of-a-counter-incrementing-twice-in-the-same-frame.md
@@ -14,7 +14,7 @@ Such achievements were supposed to be quite simple, like this:
 | ID  | Special? | Memory    | Cmp | Type  | Mem/Val   | Hits |
 | --- | -------- | --------- | --- | ----- | --------- | ---- |
 | 1   |          | 0xCANDIES | !=  | Delta | 0xCANDIES | (N)  |
-| 2   | ResetIf  | 0xSTAGE   | !=  | Value | 0xBONUS   |
+| 2   | ResetIf  | 0xSTAGE   | !=  | Value | 0xBONUS   |      |
 
 This translates into "check if the candy canes counter changed `N` times in the bonus stage".
 
@@ -26,7 +26,7 @@ In order to circumvent this issue we have to use that technique of [using `SubSo
 
 Let's take a look at the achievement logic and then we'll see the explanation:
 
-**Addresses**
+## Addresses
 
 - `0x80dc`: Candy Canes counter.
 - `0x809c`: Stage ID.
@@ -35,7 +35,7 @@ So now the structure of the achievement is going to be like this:
 
 ![](https://i.imgur.com/sDtPpX9.png)
 
-**Conditions**
+## Conditions
 
 1. Together with condition 2, is a trick used to check if `0xCANDIES - Delta 0xCANDIES = 2`. In other words, the candy counter was incremented by two.
 
@@ -47,7 +47,7 @@ So now the structure of the achievement is going to be like this:
 
 All these conditions could be translated as "while in the bonus stage, trigger the achievement if the candy counter changes 99 times, and if the candy counter is incremented by 2 in the same frame, count an extra change in the candy counter."
 
-So, now it is 100% solved, right? Well, actually, almost. There is still a very minor exception. Remember it was said before that `!=` was being used instead of `>` because `when the player has 99 candies and collect one more, the counter goes to zero`?
+So, now it is 100% solved, right? Well, actually, almost. There is still a very minor exception. Remember it was said before that `!=` was being used instead of `>` because **when the player has 99 candies and collect one more, the counter goes to zero**?
 
 This means that, if we get two canes in the same frame (which is already rare), there's a very small possibility that this change will be from `98 -> 00` or from `99 -> 01`. In these only two cases our code won't work, because `00 - 98` is not 2, it is `-98`. Same thing for `01 - 99`, it is not 2, it is also `-98`.
 

diff --git a/...-examples/creating-a-timer-with-reset-if-hits-based-on-the-speed-of-the-game.md b/...-examples/creating-a-timer-with-reset-if-hits-based-on-the-speed-of-the-game.md
@@ -11,7 +11,7 @@ Every game has an address which is constantly increasing, it functions like a en
 
 > Please note that PAL Games (50hz) have a lower framerate than NTSC Games (60hz) and aren't compatible with this method. It is recommended to create every Timer based on the NTSC version of the game, unless PAL version is the only version existing and there is no NTSC Patch available.
 
-**Addresses**
+## Addresses
 
 - `0x19`: Demo Mode: `01`=Active, `00`=Inactive
 - `0x1a`: Game Engine (speed based on framerate)
@@ -25,7 +25,7 @@ Link to Cheevo: [Contra Speedrun](https://retroachievements.org/achievement/6544
 
 YouTube: [ResetIfHits Demo: Contra Stage 1 60 seconds Speedrun ](https://youtu.be/6PpdG04tM4s)
 
-**Conditions**
+## Conditions
 
 1. Activates the Cheevo's 'Hit' when entering a Stage (`03`only appears once in each Stage).
 

diff --git a/...amples/using-add-source-and-deltas-for-collectibles-and-similar-achievements.md b/...amples/using-add-source-and-deltas-for-collectibles-and-similar-achievements.md
@@ -9,7 +9,7 @@ In this example is a simple way one can utilize the `AddSource` flag in their ac
 
 We'll look at an achievement from [Suikoden (PlayStation)](https://retroachievements.org/game/11255) entitled [Treasure Hunter - Dragon Knights' Domain](http://retroachievements.org/Achievement/80100):
 
-**Addresses Used**
+## Addresses Used
 
 - `0x1b8244`: bit0-bit4 are treasures in Soniere, bit5 is a treasure at the Northern Checkpoint, and bit6-bit7 are treasures at the Dragon Den.
 - `0x1b8245`: bit0 is a treasure at the Dragon Den, bit1-bit5 are treasures at Seek Valley, and bit6-7 are treasures in Kalekka.
@@ -19,7 +19,7 @@ We'll look at an achievement from [Suikoden (PlayStation)](https://retroachievem
 
 This particular achievement only requires treasures from Dragon Knights' Fortress, Dragon Den, and Seek Valley; therefore, we only need bit6-7 from `0x1b8244`, bit0-bit5 from `0x1b8245`, and bit3-bit4 from `0x1b824b`.
 
-**Logic Breakdown**
+## Logic Breakdown
 
 - There are two groups of ten conditions with the main differences being the Delta type and the total. This is to ensure that the player goes from nine of these treasures obtained to having all ten of these treasures obtained. _Note: Remember to use hexadecimal for `AddSource` totals!_
 - Since we're using bitflags here, the totals for individual conditions will only ever be 0x00 or 0x01. Obviously, we want them all to be 0x01 for the trigger, but we don't want someone to get the achievement simply by loading a save with all ten treasures already found.

diff --git a/...les/circumvent-the-problem-of-a-counter-incrementing-twice-in-the-same-frame.md b/...les/circumvent-the-problem-of-a-counter-incrementing-twice-in-the-same-frame.md
@@ -7,7 +7,7 @@ Esos logros se suponen que tendrian que ser algo simple, como esto:
 | ID  | Special? | Memory   | Cmp | Type  | Mem/Val  | Hits |
 | --- | -------- | -------- | --- | ----- | -------- | ---- |
 | 1   |          | 0xDULCES | !=  | Delta | 0xDULCES | (N)  |
-| 2   | ResetIf  | 0xSTAGE  | !=  | Value | 0xBONUS  |
+| 2   | ResetIf  | 0xSTAGE  | !=  | Value | 0xBONUS  |      |
 
 Esto se traduciría "checa si el contador de dulces cambio `N` veces en el stage bonus".
 
@@ -20,7 +20,7 @@ En manera que podamos evitar este problema tenemos que utilizar la técnica de [
 
 Echemos un vistazo a la lógica del logro y así poder ver la explicación:
 
-**Variables (Addresses)**
+## Variables (Addresses)
 
 - `0x80dc`: Contador de Dulces.
 - `0x809c`: ID de Stage.
@@ -29,7 +29,7 @@ Así que ahora la estructura de logro seria de esta manera:
 
 ![](https://i.imgur.com/ufPTDF3.png)
 
-**Condiciones**
+## Condiciones
 
 1. Junto con la condición 2, es un truco para ver si `0xDULCES - Delta 0xDULCES = 2`. En otras palabras, el contador de dulces fue incrementado por dos.
 

diff --git a/...-examples/creating-a-timer-with-reset-if-hits-based-on-the-speed-of-the-game.md b/...-examples/creating-a-timer-with-reset-if-hits-based-on-the-speed-of-the-game.md
@@ -4,7 +4,7 @@ Cada juego tiene una variable que esta constantemente aumentando, esta funciona
 
 > Ten en cuenta que juegos PAL (50hz) tiene un framerate mas bajo a los juegos NTSC (60hz) y no son compatibles con este método. Es recomendable crear cada temporizador utilizando la versión NTSC del juego, a menos que la versión PAL sea la uncia versión existente y no exista un parche NTSC disponible.
 
-**Variables (Addresses)**
+## Variables (Addresses)
 
 - `0x19`: Modo Demo: `01`=Activo, `00`=Inactivo
 - `0x1a`: Motor del Juego (velocidad basada en el framerate)
@@ -18,7 +18,7 @@ Link al Logro: [Contra Speedrun](https://retroachievements.org/achievement/65443
 
 YouTube: [ResetIfHits Demo: Contra Stage 1 60 segundos Speedrun ](https://youtu.be/6PpdG04tM4s)
 
-**Condiciones**
+## Condiciones
 
 1. Se activa el Hit del Logro cuando se entra al Stage (`03`solo aparece una vez por cada Stage).
 

diff --git a/docs/pt/developer-docs/real-examples.md b/docs/pt/developer-docs/real-examples.md
@@ -1,3 +1,8 @@
+---
+title: Exemplos Reais
+description: Explore real examples of achievement logic, including using hit counts as timers, delta values, managing counters, and more. Learn techniques for effective achievement development through practical case studies.
+---
+
 # Exemplos Reais
 
 **Link para o texto em inglês:** [Real Examples](/developer-docs/real-examples)
@@ -6,3 +11,6 @@ Um dos melhores recursos de aprendizagem está em analisar alguns exemplos reais
 
 - [Usando Hit Counts e ResetIf](/pt/developer-docs/real-examples/using-hit-counts-as-a-timer)
 - [Usando Delta Values e ResetIf](/pt/developer-docs/real-examples/using-delta-values-and-hit-counts-to-detect-an-increment)
+- [Contornando o Problema de um Contador Incrementando Duas Vezes no Mesmo Frame](/pt/developer-docs/real-examples/circumvent-the-problem-of-a-counter-incrementing-twice-in-the-same-frame)
+- [Criando um Temporizador com `ResetIf` Hits Baseado na Velocidade do Jogo](/pt/developer-docs/real-examples/creating-a-timer-with-reset-if-hits-based-on-the-speed-of-the-game)
+- [Usando `AddSource` e Deltas para Colecionáveis e Conquistas Similares](/pt/developer-docs/real-examples/using-add-source-and-deltas-for-collectibles-and-similar-achievements)
diff --git a/...les/circumvent-the-problem-of-a-counter-incrementing-twice-in-the-same-frame.md b/...les/circumvent-the-problem-of-a-counter-incrementing-twice-in-the-same-frame.md
@@ -0,0 +1,60 @@
+---
+title: Contornando o Problema de um Contador Incrementando Duas Vezes no Mesmo Frame
+description: Aprenda como lidar com o problema de um contador incrementando duas vezes no mesmo frame usando SubSource e flags AddHits, garantindo uma lógica precisa de conquistas em jogos com coleta simultânea de itens.
+---
+
+# Contornando o Problema de um Contador Incrementando Duas Vezes no Mesmo Frame
+
+Neste exemplo, você verá como contornar o problema de um contador incrementando duas vezes no mesmo frame combinando [SubSource](/developer-docs/flags/subsource) e [AddHits](/developer-docs/flags/addhits-subhits).
+
+Na biblioteca do Game Boy Advance, existe um jogo de plataforma natalino chamado [Santa Claus Jr. Advance](http://retroachievements.org/Game/7152). Existem algumas conquistas para coletar todas as bengalas de doce em cada um dos estágios bônus.
+
+Essas conquistas deveriam ser bem simples, desta maneira:
+
+| ID  | Special? | Memory    | Cmp | Type  | Mem/Val   | Hits |
+| --- | -------- | --------- | --- | ----- | --------- | ---- |
+| 1   |          | 0xCANDIES | !=  | Delta | 0xCANDIES | (N)  |
+| 2   | ResetIf  | 0xSTAGE   | !=  | Value | 0xBONUS   |      |
+
+Isso se traduz em "verificar se o contador de bengalas de doce mudou `N` vezes no estágio bônus".
+
+**Nota**: estamos usando `0xCANDIES != Delta 0xCANDIES` (usando `!=` e não `>`) porque quando o jogador tem 99 doces e coleta mais um, o contador vai para zero.
+
+No entanto, existe um aspecto neste jogo (e em muitos outros) onde se o jogador coletar 2 bengalas de doce simultaneamente, o contador é aumentado em 2 no mesmo frame. Quando isso acontece, o contador de hits é aumentado em um enquanto o contador de doces é aumentado em dois. Isso, obviamente, arruína a lógica usada acima.
+
+Para contornar esse problema, precisamos usar aquela técnica de [usar `SubSource` para contar incrementos específicos](/developer-docs/flags/subsource#using-subsource-to-count-specific-increments) combinada com a [flag `AddHits`](/developer-docs/flags/addhits-subhits).
+
+Vamos dar uma olhada na lógica da conquista e depois veremos a explicação:
+
+## Endereços
+
+- `0x80dc`: Contador de Bengalas de Doce.
+- `0x809c`: ID do Estágio.
+
+Agora a estrutura da conquista será assim:
+
+![](https://i.imgur.com/sDtPpX9.png)
+
+## Condições
+
+1. Junto com a condição 2, é um truque usado para verificar se `0xCANDIES - Delta 0xCANDIES = 2`. Em outras palavras, o contador de doces foi incrementado em dois.
+
+2. Usado junto com a condição 1 (como explicado acima) e 3. Como explicado em [sua respectiva página](/developer-docs/flags/addhits-subhits), quando a condição `AddHits` é verdadeira, o contador de hits na próxima condição é incrementado. Portanto, em nosso exemplo aqui, quando a condição 2 é verdadeira, o contador de hits na condição 3 é incrementado.
+
+3. Conta quando o contador de doces muda.
+
+4. Reseta o contador se não estiver no estágio Bônus.
+
+Todas essas condições podem ser traduzidas como "enquanto estiver no estágio bônus, ativar a conquista se o contador de doces mudar 99 vezes, e se o contador de doces for incrementado em 2 no mesmo frame, contar uma mudança extra no contador de doces."
+
+Então, agora está 100% resolvido, certo? Bem, na verdade, quase. Ainda existe uma exceção muito pequena. Lembra que foi dito antes que `!=` estava sendo usado em vez de `>` porque **quando o jogador tem 99 doces e coleta mais um, o contador vai para zero**?
+
+Isso significa que, se pegarmos duas bengalas no mesmo frame (o que já é raro), existe uma possibilidade muito pequena de que essa mudança seja de `98 -> 00` ou de `99 -> 01`. Nesses dois únicos casos, nosso código não funcionará, porque `00 - 98` não é 2, é `-98`. O mesmo vale para `01 - 99`, não é 2, também é `-98`.
+
+Apesar de ser uma possibilidade muito improvável, devemos tratar esse caso também. Então vamos adicionar mais dois requisitos ao código, e ele ficará assim:
+
+![](https://i.imgur.com/6wePK8N.png)
+
+É o mesmo que antes, com as únicas mudanças sendo as linhas 3 e 4, que representam um `SubSource + AddHits` extra para verificar se `0xCANDIES - Delta 0xCANDIES = -98`, apenas para cuidar dessa exceção muito pequena que acabamos de mencionar.
+
+E agora está resolvido!
diff --git a/...-examples/creating-a-timer-with-reset-if-hits-based-on-the-speed-of-the-game.md b/...-examples/creating-a-timer-with-reset-if-hits-based-on-the-speed-of-the-game.md
@@ -0,0 +1,42 @@
+---
+title: Criando um Temporizador com `ResetIf` Hits Baseado na Velocidade do Jogo
+description: Aprenda a criar temporizadores precisos no jogo usando a flag ResetIf para considerar a taxa de quadros do jogo, permitindo mecanismos de temporização precisos para conquistas em vários cenários de jogo.
+---
+
+# Criando um Temporizador com `ResetIf` Hits Baseado na Velocidade do Jogo
+
+Neste exemplo, você aprenderá como criar um Temporizador no jogo baseado na taxa de quadros (framerate) do jogo.
+
+Todo jogo tem um endereço que está constantemente aumentando, ele funciona como um motor em um carro que está constantemente em movimento, independentemente do que você faz, e começa assim que você inicia o jogo. O jogo em si é seu carro, e alguns carros são mais rápidos que outros.
+
+> Por favor, note que jogos PAL (50hz) têm uma taxa de quadros menor que jogos NTSC (60hz) e não são compatíveis com este método. É recomendado criar todos os Temporizadores baseados na versão NTSC do jogo, a menos que a versão PAL seja a única existente e não haja Patch NTSC disponível.
+
+## Endereços
+
+- `0x19`: Modo Demo: `01`=Ativo, `00`=Inativo
+- `0x1a`: Motor do Jogo (velocidade baseada na taxa de quadros)
+- `0x25`: Jogo Pausado: `01`=Sim, `00`=Não
+- `0x2c`: Progressão do Jogo: `03`=Antes do Estágio começar, `04`=Estágio iniciado, `08`=Estágio finalizado
+- `0x30`: ID do Estágio (neste exemplo, Estágio 1)
+
+![Contra Timer](https://user-images.githubusercontent.com/8508804/57049681-81f45380-6c4f-11e9-9a35-f62c8124498a.jpg)
+
+Link para a Conquista: [Contra Speedrun](https://retroachievements.org/achievement/65443)
+
+YouTube: [ResetIfHits Demo: Contra Estágio 1 60 segundos Speedrun](https://youtu.be/6PpdG04tM4s)
+
+## Conditions
+
+1. Ativa o 'Hit' da Conquista ao entrar em um Estágio (`03` só aparece uma vez em cada Estágio).
+
+2. Ativa a Conquista quando um Estágio foi finalizado.
+
+3. Estágio Atual (neste exemplo, Estágio 1).
+
+4. Pausa a Conquista se o Jogo estiver 'Pausado' (Para o Temporizador na Conquista).
+
+5. Reseta a Conquista se `60` segundos `3600` Hits forem atingidos. `1` segundo = `60Hits` (NTSC 60fps), `50Hits` (PAL 50fps).
+
+6. Reseta a Conquista se o `Modo Demo` estiver ativo.
+
+7. Reseta o Temporizador da Conquista ao entrar em um novo Estágio.
diff --git a/...amples/using-add-source-and-deltas-for-collectibles-and-similar-achievements.md b/...amples/using-add-source-and-deltas-for-collectibles-and-similar-achievements.md
@@ -0,0 +1,39 @@
+---
+title: Usando `AddSource` e Deltas para Colecionáveis e Conquistas Similares
+description: Aprenda a usar efetivamente a flag AddSource e Deltas para criar conquistas para colecionáveis, garantindo rastreamento preciso e prevenindo disparos prematuros nos jogos.
+---
+
+# Usando `AddSource` e Deltas para Colecionáveis e Conquistas Similares
+
+Neste exemplo, veremos uma maneira simples de utilizar a flag `AddSource` na lógica de suas conquistas.
+
+Vamos analisar uma conquista de [Suikoden (PlayStation)](https://retroachievements.org/game/11255) intitulada [Treasure Hunter - Dragon Knights' Domain](http://retroachievements.org/Achievement/80100):
+
+## Endereços Utilizados
+
+- `0x1b8244`: bit0-bit4 são tesouros em Soniere, bit5 é um tesouro no Checkpoint Norte, e bit6-bit7 são tesouros no Covil do Dragão.
+- `0x1b8245`: bit0 é um tesouro no Covil do Dragão, bit1-bit5 são tesouros no Vale Seek, e bit6-7 são tesouros em Kalekka.
+- `0x1b824b`: bit0-bit1 são tesouros na Vila da Runa Escondida, bit2 não é usado, bit3-4 são tesouros na Fortaleza dos Cavaleiros do Dragão, bit5-6 são tesouros em Teien, e bit7 é um tesouro na Casa de Luiken.
+
+![addsource-example1](https://u.cubeupload.com/televandalist/docssuikotreasure.png)
+
+Esta conquista específica requer apenas tesouros da Fortaleza dos Cavaleiros do Dragão, Covil do Dragão e Vale Seek; portanto, só precisamos dos bit6-7 de `0x1b8244`, bit0-bit5 de `0x1b8245`, e bit3-bit4 de `0x1b824b`.
+
+## Detalhamento da Lógica
+
+- Existem dois grupos de dez condições com as principais diferenças sendo o tipo Delta e o total. Isso é para garantir que o jogador passe de nove desses tesouros obtidos para ter todos os dez tesouros obtidos. _Nota: Lembre-se de usar hexadecimal para totais `AddSource`!_
+- Como estamos usando bitflags aqui, os totais para condições individuais sempre serão apenas 0x00 ou 0x01. Obviamente, queremos que todos sejam 0x01 para o disparo, mas não queremos que alguém ganhe a conquista simplesmente carregando um save com todos os dez tesouros já encontrados.
+- O disparo ocorre no primeiro frame em que o jogador passa de nove para dez tesouros obtidos. Isso ajuda a evitar que a conquista seja ativada quando não deveria.
+- A flag `Measured` está na última condição para que o jogador possa verificar o quanto falta para seu objetivo. Se eles tiverem oito de dez tesouros, a conquista mostrará que está 80% completa na sobreposição (RAEmus) ou menu de conquistas (RetroArch).
+
+Este método é principalmente útil para quando os totais entre o tipo Delta e o tipo Mem têm apenas uma diferença de 0x01, mas pode ser usado em vários tipos de conquistas: colecionáveis que só podem ser obtidos um por vez, conclusão de mapas (como em jogos dungeon-crawler com mapas visíveis que são revelados conforme você entra em novas áreas), habilidades que podem ser aprendidas, bestiários, completar um certo número de missões secundárias e muitos outros.
+
+Se você encontrar uma situação onde mais de uma bitflag em uma cadeia `AddSource` alterna ao mesmo tempo, você ainda pode utilizar este modelo. No entanto, você vai querer clonar as condições Delta e fazer com que ambos os totais criem um intervalo. Ainda usando a conquista acima como exemplo, o total existente poderia ser alterado para `<= 0x09` e o total para o segundo grupo poderia ser `>= 0x05`. Isso faria com que a conquista fosse ativada se o total passasse de 5-9 tesouros para 10 tesouros.
+
+---
+
+A Fazer:
+
+- Fornecer um exemplo separado para o intervalo Delta.
+- Abordar o uso de BitCount em uma conquista similar.
+- Abordar o uso de `/` quando você precisa de pelo menos uma de múltiplas coisas.