Achievement Logic Features
There are several tools and options available to a developer. Knowing how to properly utilize them will improve the quality of your sets. These tools/options can be used in the Achievement Editor:
For more help regarding these, our Discord server is always open for assistance.
A Delta value is the previous frame's value. Note: when you use Delta it is implicit that you are referring to an address and not a value.
Examples of how it can be used:
- Detect if the level has been increased:
level > delta level. It means "current level is greater than the previous frame's level". - Detect damage:
health < delta health. It means "current health is smaller than the previous frame's health". Or you can just make the previous frame's value a requirement.health delta = 1means "the previous frame's value for health must be 1 when the achievement pops up."
You can see how it works in the Real Examples page.
In the Achievement Editor, the field on the far right side is Hit Count.
The default is Zero, which means the condition must be true for the achievement to trigger.
If you set a target hit count, like 5, it means the condition must be true for at least that many frames, and once that hit count target is met, it doesn't need to be met again at any other time.
PLEASE NOTE: if a condition has a non-zero hit count, and reaches the number required, this condition is no longer tested. It remains true, UNLESS you have a Reset If, which we will discuss below.
You can see how it works in the Real Examples page.
In the Achievement Editor, it's the field titled as Special?
If the associated condition is true, all hit counts in the achievement will be reset to 0. This includes hit counts in other groups (more about groups below).
The achievement will not trigger if one or more ResetIf conditions is true, even if there are no conditions with hit count targets.
You can see how it works in the Real Examples page.
A ResetIf condition with a hit count target will only trigger when the hit count target is met. If another ResetIf condition it met, all conditions, including the ResetIf with the hit count will have their hit counts reset to 0.
It is very common to use a condition with a hit count of 1 as a start marker for an achievement, and use a ResetIf to cancel the achievement before the end condition is met. A common example is a damageless achievement: "From start of (level/battle), reset if damage taken, trigger at end of (level/battle)". When the start condition is true, a hit count is captured. If it's still set when the end condition is true, the achievement triggers. If the ResetIf condition triggers, the hit count on the start condition is set back to zero, which makes the condition false when evaluating the state when the end condition is true, and the achievement will not trigger.
While true, the PauseIf pauses activity for all conditions in the same group. It does not pause conditions in other groups (more about groups below).
Note: keep in mind that all conditions in the sentence above includes ResetIf conditions! In other words ResetIf won't work while a PauseIf is active.
The PauseIf is usually used to prevent hit counts from going up during a specific situation (like pausing the game). It's used when you want to keep previously earned hit count, but don't want to increment it or reset it while something else is going on.
A PauseIf condition with a hit count target will only trigger when the hit count target is met. Once the hit count target is met, the group remains paused until a ResetIf condition in another group is true. A PauseIf without a hit count will unpause when the condition is no longer true.
Note: most likely this technique is not needed for simple games. So, it's not mandatory for jr-devs.
When a condition has the Add Source flag, the value on that memory address is added to the value of the address on the condition right below, and the comparison is made on the condition below the one with the Add Source flag. It may sound a bit confusing, but the example below will clarify how this works:
In this example the value in 0x8010 will be added to the value in 0x8020 and the comparison is if this sum is greater than zero.
If the value in 0x8010 is 1 and the value in 0x8020 is 2, the comparison will be 1 + 2 > 0, or 3 > 0.
Note: All the comparison fields on the condition with the Add Source flag are ignored.
Trying to summarize the explanation in an image:
Note: you can use the Add Source flag to sum more addresses, like in the example below:
Note: most likely this technique is not needed for simple games. So, it's not mandatory for jr-devs.
Works similarly to Add Source, but the Sub Source flag makes the value in the memory address have a negative value.
Note 1: Sub Source is NOT a subtraction flag. It just makes the value be negative.
Note 2: The final line (without Add Source or Sub Source) is still added for the final comparison.
Using that Add Source usecase example, if we replaced it with the Sub Source and with the same values (value(0x8010) = 1 and value(0x8020) = 2), the comparison would be -1 + 2 > 0, or 1 > 0.
Note: most likely this technique is not needed for simple games. So, it's not mandatory for jr-devs.
Adds the hit count for the current condition to the next achievement condition. The total hit count will be used when determining if the target hit count for the next non-Add Hits condition is met. If the next non-Add Hits condition does not have a hit target, the Add Hits condition has no effect on the achievement.
All fields are supported on an Add Hits condition. If the condition is met, the hit count for the condition is incremented (and will stop incrementing if a target hit count is specified).
The Add Hits condition does not have to be true for the achievement to trigger. The next non-Add Hits condition does, which is affected by the Add Hits condition.
ResetIf and PauseIf can be applied to a condition following any number of Add Hits, Add Source, or Sub Source conditions.
Going back to the Add Source example above, if ResetIf were applied to condition 2, the achievement would reset because 1 + 2 > 0.
Note: most likely this technique is not needed for simple games. So, it's not mandatory for jr-devs.
Achievements can have groups added to them that can act as alternative requirements to unlock an achievement. These are called Alt Groups.
One extremely important thing to note: For an achievement to unlock it must have it's Core group AND at least one Alt group be true. If there are no Alt groups present, then only the Core group's conditions need to be true.
Tip: Because the Core group always need to be active, typically you would put conditions there that are common among all the alternative requirements. However, one trick you can use to basically ignore needing a Core group is to give it a condition that is always true such as:
Mem 0x0001 = Mem 0x0001
Since the Core group is now always true, and you can now focus on differentiating the Alt groups.
Remember, when using ResetIf and PauseIf, PauseIf only pauses the group that it's in, but ResetIf resets hit counts in all groups.
| Feature | RA_Integration | RetroArch |
|---|---|---|
| ResetIf HitCount | 0.073 | 1.7.4 |
| PauseIf HitCount | 0.073 | 1.7.4 |
| Leaderboard Cancel AND | 0.073 | 1.7.0 |
| Leaderboard Cancel OR | 0.073 | 1.7.4 |
| Delay achievement processing on load | 0.073 | 1.7.4? |
| Full 32-bit value support | 0.073 | 1.7.0 |