GB ASM Tutorial Cheatsheet

[LaroldsJubilantJunkyard]

The goal of the cheatsheet is a bunch of concise snippets and explanations on how to do common tasks. i expect a bunch of wording/order/best practice comments/suggestions/changes. This time around, let me have'm.

As a plan of action, let's try avoid adding extra stuff in this initial PR. Why? I had to remove some topics because i realized the list could go on forever, and it would take wayyyy more time than i have. Which would start crunching with other tasks and ultimately delay actual release.

[ISSOtm]

I only read through the first part, but this review is significant enough as-is.

[ISSOtm]

I get that this is meant to be a cheat sheet, but there are at least three ways to do this (LY, STAT, and VBlank handler), each with their own pros and cons; so enjoining people to use only one of these three feels wrong.

Then again, perhaps I am applying the wrong scope in trying to convey here all of the subtle differences between all of those various ways... I don't know. I feel like it should be documented somewhere at least.

Can @Rangi42 help? I believe you have written most of this, so you may have some insight. (And perhaps that document could be merged with this one, to increase its visibility?)

[LaroldsJubilantJunkyard]

Let's find the most common way, and then maybe leave links and notes about where to find info for the other ways and documentation about the technical differences?

[ISSOtm]

I agree with the sentiment. But for this one specifically, even that won't work..!

The two common ways are LY and VBlank handler, and the latter is inherently dependent on said handler. The former is used mostly when the handler hasn't been set up yet (i.e. when turning off the LCD during boot-up), and the latter everywhere else.

[LaroldsJubilantJunkyard]

I agree with the sentiment. But for this one specifically, even that won't work..!

The two common ways are LY and VBlank handler, and the latter is inherently dependent on said handler. The former is used mostly when the handler hasn't been set up yet (i.e. when turning off the LCD during boot-up), and the latter everywhere else.

Yeahhh... i don't understand that :D

[avivace]

Can we introduce the three ways and just explain/describe one for the time being?

[LaroldsJubilantJunkyard]

What's a good gameplan here? I don't know "the three ways"

I don't think the vblank handler fits in the same entry. This is how to do nothing except wait for vblank.

That's the purpose of the snippet?

[quinnyo]

Sorry, I was perhaps a bit too brief in my previous comment. I'm responding to the debate/confusion surrounding which technique should be highlighted here.

Briefly:

• the LY way (as it is in the text currently) is the best candidate for "how to wait for VBlank".
• the VBlank handler is an important topic that should be covered, but is a separate thing that should be treated as such (e.g. a separate entry / under a different heading)
• It's easier to understand LY than using STAT -- loosely: scanlines are "real" but PPU is a black box.

Not briefly:

• I think it's reasonable to say that the way (recommended way, in general, etc.) to wait for VBlank is to enter a busy loop and read LY until scanline 144. This is "doing nothing except waiting".
  • This is essentially what the text is already saying. The snippet is fine.
  • Ideally the text will not give too strong an impression that that's the only way to do anything re. VBlank.
• My point about the VBlank interrupt handler is that it doesn't need to be considered as a competing technique to LY144 as the usual point of using it is significantly different to waiting for VBlank. They serve different purposes.
  • The VBlank interrupt is for efficient game loop synchronisation in concert with halt (in general, etc.)
  • I would recommend not using a busy loop to synchronise a game loop.
• verbose: The implication of doing nothing except waiting is that the program has nothing else to do, or nothing better to do at that time (or no other reliable means to "V-sync"). Using halt to wait for the VBlank interrupt and save power would be an example of something better to do, if all the program is doing is delaying until the next frame (synchronising the game loop).

[LaroldsJubilantJunkyard]

I guess I sort of get what youre saying... Maybe that should be an addition later down the line? Unless someone else wants to submit the code snippet...

[ISSOtm]

I think it shouldn't be a code snippet, then; but that this one's description should at least hint at the use of halt instead of this, whenever available. Perhaps with a link to the relevant section of the tutorial that explains that (if there isn't one yet, that's fine, and we'll open an issue to remind us later).

[LaroldsJubilantJunkyard]

I think it shouldn't be a code snippet, then; but that this one's description should at least hint at the use of halt instead of this, whenever available. Perhaps with a link to the relevant section of the tutorial that explains that (if there isn't one yet, that's fine, and we'll open an issue to remind us later).

Sure, I can do that. I'm not familiar with halt, can you give me some documentation links or a snippet to add?

[avivace]

Can we introduce the three ways and just explain/describe one for the time being?

[quinnyo]

I've marked a bunch of (mostly small) specific things (in the first half or so, at least).

[quinnyo]

This is a lot of detail information.
This entry has no snippet.

[LaroldsJubilantJunkyard]

This is a lot of detail information. This entry has no snippet.

is it critical to have a snippet? it's just explaining the purpose of the section

[quinnyo]

I'm not saying that it has to have a snippet necessarily, it just seemed to be less of a concise cheatsheet tip than the other sections.

I guess I don't have any specific, actionable advice and the text isn't wrong, so you can probably ignore this.

[ISSOtm]

These are some old comments from when I had started reviewing this. I wasn't able to muster enough energy to review the entire PR, sorry.

[ISSOtm]

Actually, those constants are only meant to be OR'd; so either as part of a | expression, or the operand to a or instruction. All of the LCDCF_*OFF constants are only useful for the former. Thus I'm not sure if we should mention them in this section.

[ISSOtm]

Note also that this has different behaviour on DMG and CGB, and it doesn't allow access to VRAM even when off; so I don't think this section is much use at all?

[LaroldsJubilantJunkyard]

Note also that this has different behaviour on DMG and CGB, and it doesn't allow access to VRAM even when off; so I don't think this section is much use at all?

Should i remove this section?

[ISSOtm]

Yeah, I think that's better. I'd assume people interested will read Pan Docs, and figure out how to modify the other, similar snippets. It shouldn't hurt to focus on the most useful ones rather than try to be exhaustive, for a cheat sheet.

[LaroldsJubilantJunkyard]

Note also that this has different behaviour on DMG and CGB, and it doesn't allow access to VRAM even when off; so I don't think this section is much use at all?

It's an easy remove , but What's the behavior difference? I guess part of me feels like turning on/ off the window at least is common.

[avivace]

So, after discussing with @ISSOtm we decided to merge this in the current situation with the following reservations:

• This "cheatsheet" probably doesn't fit the scope (and the resources) of this project. We should think about moving it to Pan Docs or to gbdev.io/guides in the next future.
• The open unresolved threads will be moved to Issues so we can keep working on them
• From now on, PR should be shorter and brief, so in this case it would've been better to add one snippet at the time to make the maintainers (and other potential contributors) easier.