Update developer doc examples and update outdated toolkit screenshots

[pilzkopf777]

Proposing update to the developer documentation. Quick overview of what's involved:

• Updated Code Note examples to better suit the newly decided standards.
• Toolkit screenshots were quite outdated - swapped out accordingly.
• Guide for Getting Started updated as well as the currently example is out of date.
• Updated guide based on achievement for Leaderboards.
• Also added notes on how and when to implement Instant Submission LBs which was missing previously.
• Some pages like ResetIf feature an example on usage.

[redwizard42]

Examples in other documents tend to use tables rather than code blocks. Consider changing to tables (or changing the examples in other documents to be code blocks)

[pilzkopf777]

The Recall examples using the table helps in working out which column should have what flag.
I fear the code blocks will not get the idea across there so for those the table or just a screenshot may be a better fit

[pilzkopf777]

This is what it'd look like as a table.

[pilzkopf777]

Using some custom css (padding-top and bottom: 8px; padding-left and right: 13px;) it'd look like this but honestly I'm not sure what the correct location or approach would be to implementing that.
I'd rather just leave the table as is before I mess something up somewhere else or go against some internal style guide for the docs.

[Pr1ms]

I think QA are going to recommend only using hex and float as values.
It does not necessarily mean we have to be prescriptive in the docs but I for one would not mind enforcing it.

[redwizard42]

I think QA are going to recommend only using hex and float as values. It does not necessarily mean we have to be prescriptive in the docs but I for one would not mind enforcing it.

This one is BCD so I think decimal is more correct here; QA may want to consider that specific case.

[suspect15]

We will discuss, but generally I'm always inclined to mirror RAInt unless there is a compelling reason to deviate (which I don't see here) - it displays BCD as hex so therefore I don't really see a reason to not do it as well. We tend to use technicalities as justifications that don't necessarily make things better, but do make them different. My priorities for formats are ease of use and standardization - in this case, I don't think decimal makes it significantly easier to use, but it does make it non-standard.

[redwizard42]

With BCD, a hex reading of the value is identical to a decimal reading. Hence Binary Coded Decimal. At the very least it could be written a 0x00-0x09, 0x10-0x99, etc I guess, but it's funcationally the same.

[suspect15]

My primary concern, which I failed to clearly describe, is that in RAInt if someone selects "view as decimal" the values displayed won't match the note. If I saw 10-99 in a note, I'd assume the decimal values would be 10-99, however since BCD is still hex at the RAInt value level, there's a mismatch.

Using the note as an example, if the value of the score address was 0x99 (153 decimal value), it's easy to mistakenly think the rank is "Prosperous", especially if in "view as decimal" whereas if the note just said 0x00-0x99, 0x100-0x999 then there'd be no potential for this confusion.

Ultimately, I don't see any benefit to not using a hex prefix, but I can see some situations in which it could be misleading.

[redwizard42]

I mean, it also depends on if you're using the BCD type too whether a Value comparison will match.

[Jamiras]

Ultimately, I don't see any benefit to not using a hex prefix, but I can see some situations in which it could be misleading.

Does this pursuade you at all?

When the notes are in hex, the tooltip can't find a match (0x0f=15, 15 is not in the 0x10-0x20 range)

When the notes are in decimal, the tooltip can find 15 in the 10-20 range:

There does seem to be a bug where the tooltip is still decoding the value as hex when Show Decimal is checked, so the screenshots were taken with hex values, which is slightly confusing, but I hope the illustration still works.

In the end, BCD is just a different way to view the data. You wouldn't note a Float address by dumping the hex values - you'd list the decoded values (1.0-1.6=slow).

[suspect15]

I didn't realize the tooltip was able to translate as you show - that is good, but the Mem/Val column still shows hex. I guess my main concern is just trying to keep things as simple as possible and eliminate as much unnecessary variance across the library as possible. As someone who resolves a lot of inactive dev tickets, it feels like the number of code note styles across the library isn't much lower than the number of people who've developed sets.

From a QA/maintenance perspective, when looking to resolve issues with other people's sets, this reality adds a time burden needed to decipher whatever particular style the dev preferred whenever maintenance is needed. In most cases it's not significant, but I think the narrower the tolerance for deviation amongst notes, generally the better.

Floats do show in the achievement editor as X.Y, so having the code notes in that format makes sense.

This isn't a big issue in particular, but it feels like doing something differently for no tangible benefit. I'm an advocate for more standardization.

[suspect15]

This is a really helpful update. Thank you for doing this!

[pilzkopf777]

How are we all feeling about moving the example from the Real Examples section of the docs to the respective guides on flags?

Using Hit Counts as a Timer , Using Delta Values and Hit Counts to Detect an Increment , Circumvent the Problem of a Counter Incrementing Twice in the Same Frame and Creating a Timer with ResetIf Hits based on the Speed of the Game all would be a fair fit in the Hit Count docs.
Using AddSource and Deltas for Collectibles and Similar Achievements would fit AddSource.

[redwizard42]

How are we all feeling about moving the example from the Real Examples section of the docs to the respective guides on flags?

I have debated this with myself a lot. I think having more examples in the flags docs themselves is a good thing to do (I made sure I had a few examples of use for Remember/Recall), but I think there's benefit in having the real examples as their own thing as a sort of "I have this task/goal, how do I code that?"

Both of these have merit and should be represented:

Examples in Flags docs: "What can I do with this flag?"
Examples of Tasks: "What flags and features do I need to do this kind of thing?"

[pilzkopf777]

How are we all feeling about moving the example from the Real Examples section of the docs to the respective guides on flags?

I have debated this with myself a lot. I think having more examples in the flags docs themselves is a good thing to do (I made sure I had a few examples of use for Remember/Recall), but I think there's benefit in having the real examples as their own thing as a sort of "I have this task/goal, how do I code that?"

Both of these have merit and should be represented:

Examples in Flags docs: "What can I do with this flag?" Examples of Tasks: "What flags and features do I need to do this kind of thing?"

Based on some other Jrs and how they navigated the docs I rarely saw them consult the "real examples" section as such. Never did they think "oh, is this case covered" but instead asked in the Discord chat and then navigated to the specifics about a flag in the docs.