Maybe we could put a table of contents at the top. Is there an easy way to do this?

ToDo list:

• write a hands-on tutorial (use game ID 10971, from NES database).
• guidelines for translations
• create a page explaining the Memory Inspector, similar to what Scott did in the past with this forum post. Don't forget to add the features added recently by @GameDragon2k .

The official website and the https://retroachievements.github.io/ front page has a dark background. Then it would be nice to have a similar look & feel in the docs.

AFAIK the MkDocs Material theme doesn't provide a way to change the background so easily. It must be done by tweaking CSS.

@luchaos looks like you're familiar with CSS stuff. If you have some free time could you help on this front?

In this post there's a guy who seems that made it.

EDIT: I think he shared his extra.css file here: https://github.com/fmaida/mkdocs-material-dark-theme
I'll try it as soon as I get home. :)

https://docs.retroachievements.org/Achievement-Logic-Features/#hit-counts

Detail each major use case for hit counts rather than just saying, "look at the real examples".

This page can probably be deleted. It's out of date and redundant.
https://github.com/RetroAchievements/docs/wiki/Alt-Groups-and-Flags

The same info is present on the https://github.com/RetroAchievements/docs/wiki/Achievement-Logic-Features page.

The only reason I've not just deleted it is a concern with broken links.

@kdecks @GameDragon2k

In the Beginner Tips page there is a tip that confused me. Well, IMHO if it confuses me it can confuse others... 😅

Then I think it can be better written by a more experienced dev. The item is this one:

• 16-bit requirements do not have to be used on an even number of RAM, they can be used in-between properly, even if 16-bit view doesn't show it right. Ex: 0 1 2 3 4 5, in 16-bit it's usually viewed as 10 32 54, but if you start the address at the 1 here in your requirement, "21" will be read by the achievement, even if 16-bit view in the memory viewer isn't showing it. It also works if it's the last address in the line(starting at F, going to 0).

Also, many of tips there is very basic that deserves to be in the "Getting Started..." page. Things like ResetIf, PauseIf, Delta, etc.

I compromise myself to overhaul the "Getting Started" page adding stuff I'm learning currently. It still lacks many info.

This can include technical terms that relate to game memory, specific terms that that relate to our tools, and colloquial terms that are common use for RA, such as set, cheevo, etc.

Here's a starting list:

flag (memory)
flag (achievement field)
bit
byte
8-bit
16-bit
32-bit
cheevo
set
forum
game page
achievement page
Discord
Developer
memory viewer
comparison
address
upper4
lower4
local achievement
unofficial
promote to core
commit selected
leaderboard
global leaderboard
hardcore
softcore
claim
set
memory bookmarker
memory
dynamic memory
static memory
pointers
stage id
value
hexadecimal
binary
PauseIf
ResetIf
achievement ID
game ID
badge
game icon
author
demotion
ticket
points
retro ratio
set cap
endian
rich presence
Retroarch
rcheevos
dll
github

@kdecks IMO the #welcome channel on our discord is bloated, making many new users simply ignore it.

That message listing the staff members is a cool info, but seems to be of little relevance to those just entering the server. Then I suggest moving that to a page here. Another benefit: it has a more dynamic way to edit it as needed (no need to be done only by the Discord message's author).

And links to download them.

And any other legal freeware titles too.

Shouldn't be on the downloads page if we would be limiting it to developers. Better to post it in Developer news when we're ready.

Previously for Atari there were objections for release before the package was ready.

~ will submit the largest value of multiple lookups.

example: 0x0f3336*~0xM0f3314$0x0f32d6*~0xM0f32b4$0x0f3306*~0xM0f32e4$0x0f3366*~0xM0f3344 for http://retroachievements.org/leaderboardinfo.php?i=2282

I thought that maybe I/we could use this as a to-do list of things that need documentation, maybe. That anyone could work on.

inspiration: https://stackoverflow.com/help/how-to-ask

The RA user ImpliedKappa posted a detailed guide on the forum that could be adapted to a doc page: http://retroachievements.org/viewtopic.php?t=6688

Most wiki's have a back side which is for discussion on certain changes. Any ideas how we could have something like that here?

Something clean and unobtrusive, but allows to discussion concepts for specific pages.

I have one idea, just now:
The idea is for any time someone wants to have discussion on a specific page, they create an issue, Title it: Discussion for page [page name]. Label it as discussion, post their discussion points and then close the issue (to hide it), other points of discussion can be added there as they come up, and the issue can stay closed.

But anyway, this is meant to be an open ended question. Any thoughts?

Although very useful, the github wiki engine doesn't provide a way to host images.

Then we can use this issue here for the github image hosting hack and put here the images we need in the wiki.

Just add a comment on this issue thread attaching the image file you need. It will generate a markdown link to the image, like this one:

![memory_inspector](https://user-images.githubusercontent.com/8508804/32601361-83b8d962-c529-11e7-9e90-85fe2edc6f45.png)

Now you can copy this markdown link and use on the wiki page you are editing.

Quoting what I read where I learned this trick:

I admit this is a HACK only useful until GitHub finally provides a more intuitive upload feature. But until that happens… enjoy!

Real Example for "Conditional ResetIf" cheevo. Probably from the Little Mermaid bonus set (by Thoreau).

@Jamiras
According to the Game Identification page, in the Mega Drive case the entire file is hashed.

But the logic in RetroArch gives me the impression that it pads the content with zeros when the file size is smaller than 6 megabytes.

Could you find on RAGens code how the hash is calculated?

Maybe @leiradel or @ScottFromDerby can shed some light here too.

Real Example for cheat protection. Probably from Zero Wing set.

I see a few of Achievement Templates that I feel can either use more examples or can be updated to include some new features that have been added since they were made.

• Collected 100% of Something -
• Add new template for when items are stored in different addresses or bits and you are checking for all of them to be obtained (Ex. get all SubTanks in Mega Man)

Example to check if the last item of X items is collected and the items are stored in bits.

Requirements
*Assuming that 0xItemX bits are 1 when obtained and 0 when not and that multiple items can nob be obtained in the same frame.

• 1-3: Each of the items are currently obtained
• 4-7: Any one of the items were not collected on the previous frame (Adding all Delta values adds up to number of items - 1)

Using this method the achievement will trigger when all ItemX's are currently obtained and the previous frame any one of them was not collected.

Real Example

Condition 1 - Difficulty is Normal or higher
Conditions 2-6 - All 5 shoes are currently collected
Conditions 7-11 - Previous frame any of 4 shoes were collected

*Conditions 2-6 Alternative - Alternatively you can write these conditions with AddSource the way it is used in conditions 7-11 but using value = 5 instead of 4.
However you won't be able to debug which specific conditions are currently true/false and if you check a large number of conditions this can be problematic (Ex. out of all the 100+ treasure chests in a game which one is not getting triggered properly)

• Conditional Resets -

• Remove ALT2 from example (not needed)

• Add an example using AndNext for a conditional reset.

Alternative ALT1 (Using AndNext)

• The reset will only happen if all 5 of the conditions are true
  
  
  

Also I was suggested to use the issue tracker for suggestions but also told that any edits to pages are reviewed beforehand so I'm not sure was the best way to go about making suggestions would be since I plan to do more.
Can I just make these sort of edits myself or is it better to post suggestions here to discuss further before making changes?

It would be useful to have the explanation below (currently present in the ResetIf with hitcount section) as a template or even better: get an example from a real achievement in the Core.

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.

I've noticed that the Achievement Logic Features started to become very bloated and kinda hard to find info quickly.

Then I started to split the topics into separate pages. Then you can quickly go to the AddSource page, for example.

The problem is: there are many other pages linking to each one of those techniques. It'll be necessary to check other docs and fix the links.

Achievement Hunting Rules page

• Add battery save abuse rule

Write somewhere in the docs clearly that shows the difference and the similarities.

maybe adapting this forum post for a doc page:
http://retroachievements.org/viewtopic.php?t=81

update

It would be cool if we had a video showing techniques to find the RAM address for demo mode. In some games it's really easy to find, but in other's it can be tricky. The video should show examples on various games, the simple and the complex ones.

Possible solutions:

• linkchecker: https://pypi.org/project/LinkChecker/
• wget sourcery

For now I'm using https://www.deadlinkchecker.com/, but, as an online tool, it can only check after the pages are deployed. The goal is to check for broken links before deploying.

I think we can all agree that we need more of these. Source: #13 #14 #15 #23 #28 #36

So let's just start a project to list what we need and the examples we can use for the docs. Having multiple examples per category would showcase and stress the point that there are often multiple ways to get the same results. Not to mention what works in one game may not work in another.

I'd also like to see in-depth case studies documented at some point. :)

Currently the explanation on the SubSource Flag page refers to the example in the AddSource page. For clarity sake, it would be useful to have a specific SubSource example instead.

Planned edits

Add homebrews for:

• Genesis
• SNES
• GB
• GBA
• NES
• Atari 2600
• VB

(as always, anyone can help out here)

This one should be easy. (I intend to do it)

I'm tempted to change from mkdocs to docsify.

Also, use gitalk for comments.

RAVBA currently has a note on it saying "Cartridge RAM may appear as all FFs" - while it's clear to achievement developers that this means that a good chunk of achievements will not work in RAVBA, it is not clear to regular players that that is the case.

(this should also be updated on download.php on the site, if I should make a separate issue/discussion over there, let me know)

A feature to be implemented in generate-docs.sh script:

When generating the RAdocs add at the end of each page a Changelog section, with the last 10 commit messages.

Here's the command needed:

git log -n 10 --pretty=format:"- [%ci] **%an**: %s%n" Document-Name.md

The example below was generated from the commit history of the Developer's Code of Conduct:

Changelog

• [2019-01-04 20:04:33 -0700] Kvon: added a clarification about set ownership responsibility.

• [2018-12-06 11:08:28 -0700] Kvon: This was intended to be removed in my last edit, (see comments) but was not

• [2018-11-25 06:37:54 -0700] Kvon: removed "or allow two players where it could give an advantage". To allow for achievements with normal co-op to be acceptable. Added a line about concept wiggle room.

• [2018-11-13 18:07:17 -0700] Kvon: updated tl;dr "state your intention" to match the rule in later in the doc.

• [2018-10-22 14:51:47 -0600] Kvon: added rule we forgot to add about two player achievements.

• [2018-09-17 17:56:39 -0300] meleu: case sensitiveness

• [2018-09-10 15:17:28 -0600] Kvon: typo

• [2018-09-09 21:11:37 -0600] Kvon: clarified unwelcome concepts, added info about 1 rom per console per game. Made links to working with the right rom

• [2018-09-08 12:19:55 -0300] meleu: an item about "set ownership" on the TL;DR version.

• [2018-09-08 07:20:18 -0300] meleu: moved "Unwelcome Concepts" to be the first item in "Basic Achievement Design Guidelines"

Real Example for not awarding a cheevo when playing with 2p on Fighting Games. Probably from a Street Fighter set, or even the Double Dragon (NES) set.

short history

The short history makes me feel a little uncomfortable. There's years of history gap, and plenty happened during that time. As written it feel like first the site was started, and then things started happening after 2017.

I don't have a proposed solution yet.

staff

• I intend to match the the staff data to how it is in the welcome channel, and then remove that section after it's done.

EDIT: Sorry, this was meant to go in the RAIntegration section! For some reason it ended up here!
While working on one game I came across a feature I was missing.
The game in question had a bunch of different room ID's for the same dungeons or towns for example, and instead of writing:

Lookup:Location
350=[Oedo Town]
351=[Oedo Town]
352=[Oedo Town]
353=[Oedo Town]
354=[Oedo Town]
355=[Oedo Town]
356=[Oedo Town]
357=[Oedo Town]
358=[Oedo Town]
359=[Yamashiro / Zazen Town]
360=[Yamashiro / Zazen Town]
361=[Yamashiro / Zazen Town]
362=[Yamashiro / Zazen Town]
363=[Yamashiro / Zazen Town]
364=[Yamashiro / Zazen Town]
365=[Yamashiro / Zazen Town]
366=[Yamashiro / Zazen Town]

I think it would be nice to define a range of values, like this:

Lookup:Location
350:359=[Oedo Town]
360:366=[Yamashiro / Zazen Town]

It would save a lot of space in cases like this, and it could also be used together with scores for example:

Lookup:Score
0:1000=Noob
1001:2000=Amazing

This could be done with conditional outputs of course, but if that wouldn't be a viable option for some reason... yeah.

Similar to the Game Identification page, it would be useful to document how memory is mapped for each RA-supported system, especially for implementing support in future clients (libretro cores, etc.).

I only know about these:
GB/C: http://gameboy.mongenel.com/dmg/asmmemmap.html (according to @Jamiras)
PC88: http://www.maroon.dti.ne.jp/youkan/pc88/memmap.html -> RA maps main RAM (left column, inc. text window) immediately followed by TVRAM (text VRAM, AKA high-speed RAM). ROM, GVRAM, and extension RAM are not mapped.

I just signed up on RA a few days ago (ApplemunchRA) and when I tried to play Super Smash Bros. or Super Mario World, it fails to load achievements and says "Failed to download game data: Credentials Invalid (0)" and I didn't know what to do. It seems like other people have gotten this issue, but nobody seemed to answer.