Change the bit number/flag naming conventions

[Rangi42]

Update the date in HISTORY.md before merging!

Fixes #26

This is a significant breaking change to the traditional hardware.inc names:

• Bit numbers REGB_NAME are changed to B_REG_NAME (a prefix is easier to read than an infix)
• Flags REGF_NAME are changed to REG_NAME (there's no ambiguity, and some flags and values already lacked an F, e.g. AUD3LEVEL_* or AUDENA_OFF/ON)
• Some abbreviations have been expanded, e.g. SCRN to SCREEN, HBL to HBLANK, X to WIDTH, etc, in order to still be short but also more recognizable
• "DPAD" is now "CTRL_PAD" because that's the official name for it

What has not changed:

• All registers still have the same good old rNAMEs. Even the aliases like rP1 for rJOYP are still supported, not deprecated.
  • The rSMBK alias for rSVBK/rWBK is deprecated, since rWBK is the new preferred alias and rSMBK was an invention from hardware.inc 3.0.
• "Official" names are all the same as before; only community-invented names have been changed. (Some are more official than before, e.g. CTRL_PAD instead of DPAD.)

Since this change affects so many constants, hardware_compat.inc is provided for backwards-compatibility. That's also where constants deprecated by previous versions have been moved to -- I didn't just remove them, since if someone just wants a drop-in fix for their old project, they might still use deprecated things.

A quick two-command sanity check:

1. rgbasm hardware.inc
2. rgbasm -P hardware.inc hardware_compat.inc

[Rangi42]

A large change like this deserves scrutiny -- make sure I didn't get any B_ prefixes wrong or make typos -- and will probably get some nitpicking, bikeshedding, etc. I expect reviewers will have suggestions for some name changes different than the ones I went with (maybe even some changes that I didn't consider, particularly from @ISSOtm). Assuming it eventually gets approval, just remember to update the HISTORY.md date after however many days review takes.

[ISSOtm]

I personally don't have any nitpicks with the names. Thank you!

[Rangi42]

Aside: Here's a little utility function for getting the formatting right:

def align_on(token, paragraph):
    token = f' {token} '
    lines = [line.split(token, 1) for line in paragraph.split('\n')]
    lines = [[p[0].rstrip(), p[1].lstrip()] if len(p) == 2 else [p[0].rstrip()] for p in lines]
    size = max(len(p[0]) for p in lines if len(p) == 2)
    lines = [p[0].ljust(size) + token + p[1] if len(p) == 2 else p[0] for p in lines]
    return '\n'.join(lines)

[dannye]

FWIW, I'm a big fan of these changes.

[dannye]

I didn't know it was called "control pad", I'm quite used to "dpad". This is the one change I would hesitate on.

[Rangi42]

Yeah, it's officially "Control Pad" (and likewise "Game Boy" not "Gameboy", "Game Link Cable" not "link cable", etc). I could shorten this to D_PAD, if it's widely preferred by users.

[vulcandth]

I actually kinda preferred Dpad as well. But just a preference.

[Rangi42]

One thing I'm tempted to do is move rSMBK into hardware_compat.inc, since we now have the rWBK alias, and rSMBK ("Select Main BanK") is a now-redundant community alias from hardware.inc 3.0 in 2020 (PR #4), not an official name.

Searching "SMBK" on the gbdev Discord gives no results, and only 4 for "rSMBK" -- all from someone who prefers rWBK anyway.

[Rangi42]

This is the first major-version update to hardware.inc since 4.0 in 2021, and is updating practically all the non-register names, so now's the time to think about whether any other names could be improved. Suggestions are welcome!

[vulcandth]

I really really like this change! I'd be fine with converting pret to use this now. I hope other people in the gbdev community weighs in.

[nitro2k01]

I've said everything I have to say about breaking changes, and I think this is a losing battle so I think I will mostly shut up about it going forward. But I will say this. Instead of breaking hardware.inc and renaming the old version hardware_compat.inc, how about keeping hardware.inc as it is (maybe minor updates, but no breaking changes) and make the improved version a new file that people can choose to use if they wish. Hell, even make that a whole new project and rethink everything from scratch in hardware_new.inc. Since it's a whole new thing, you're not obliged keep anything from the old one.

[Rangi42]

@nitro2k01 Thank you for leaving negative feedback here too. It's worth addressing: why change hardware.inc instead of making something else?

The short answer is, GBDev recommends hardware.inc to new users -- in Pan Docs, in gb-asm-tutorial, in its own repository list -- so the name "hardware.inc" needs to be on the latest and most maintained version.

For established users like yourself who are already used to names like OAMF_PRI or P1F_2 or SCRN_VX_B, they don't need GBDev to hold their hands and guide them to "the" hardware.inc file. It's easy enough to include hardware_compat.inc alongside it, or more likely, just use the previous major version 4.12.¹ But new users shouldn't have to go out of their way to discover a more "friendly" way of naming things, especially when the new names aren't a huge departure from tradition.

hardware.inc hasn't been afraid of breaking changes before. 3.0 did a few renames (e.g. _HW to _IO) and removed a whole set of o-prefixed low-byte constants (as opposed to just deprecating them). It also introduced the rSMBK alias just because it "makes more sense (to me) than rSVBK". Ultimately the REGB_FLD-style names are just a community convention, like rgbasm's old x SET x + 1, and when there are good reasons to change, like with DEF x += 1 or here B_REG_FIELD, we don't need to say "things have always been this way, it's too late to change". Those who don't like the change, don't have to update their project's hardware.inc copy.

Note that when changes go further than this, @ISSOtm and I have made a separate repo, https://github.com/Rangi42/hardware2.inc. That changes even the official register names, e.g. rSC to rSerialCtl. On the one hand that follows the usual RAM labeling convention nowadays, but it's not something Pan Docs or other resources would be recommending as "the" way to do things -- LCDC, P1, NR52, etc will always be around, even though we've added aliases over the years like JOYP and AUDENA -- so it shouldn't be what a semi-official file like hardware.inc defines.

Footnotes

1. That's why I've been making the past series of 4.x updates, adding new bit number+flag constants and making sure things are well-commented, instead of doing it all as one big 5.0 update. I wouldn't want older users to have to choose between "complete consistent set of definitions" and "the good old infix flag names I've used for years". ↩

[Rangi42]

Note that issue #26 was never definitively rejected by any maintainers, but just left to sit open for over 3 years. That shouldn't happen. Either the project maintainers can say "the names are what they are, no more major versions, deal with it", or we can be open to proposing, hashing out, and then finally accepting new changes. But leaving the idea open and neglected implies that there's just no strong will to do anything in particular -- keeping things as they are, not because they're really preferred, but just out of inertia. Nobody wanting to volunteer and figure out what the bold new changes should be.

(Frankly nobody was maintaining hardware.inc -- even the users who were comfortable with the traditional constants never bothered completing the set of bit+flag names to match Pan Docs. And I know that @aaaaaa123456789, at least, just copy+pastes his needed subset of names, and doesn't even bother with bit/flag constants, just raw numbers. So I suspect that what was happening was, the old experienced users didn't need hardware.inc to be a complete resource anyway, and the new users were just not being well-served.)

(Also, out of the two maintainers for gbdev's asm-related projects, I'm the more conservative one; be glad that rLCDC isn't being renamed to rPPUCtl. :P )

[Rangi42]

One more thing -- the motivation for actually making this v5 PR was that I tried to use the v4 names in pokecrystal (pret/pokecrystal#1186), replacing pret's accreted subset of names, and realized "...this is a step backwards". Who wants to replace SCREEN_WIDTH with SCRN_X_B? Or OAM_PRIORITY with OAMB_PRI? We would be degrading the user experience in the name of consistency.

pret's hardware_constants.asm had grown some names for registers and bits that Pan Docs described but hardware.inc itself didn't, so I ported those to it in 4.x. And then decided, let's not keep neglecting #26, if we're not closing it then let's address it.

[NovaSquirrel]

I like being able to explicitly write 9800 or 9C00, instead of just implying 9800 via the absence of 9C00

[nitro2k01]

The short answer is, GBDev recommends hardware.inc to new users -- in Pan Docs, in gb-asm-tutorial, in its own repository list -- so the name "hardware.inc" needs to be on the latest and most maintained version.

The tutorials could just as well point to the new thing, assuming it was branched off to a whole new repo.

hardware.inc hasn't been afraid of breaking changes before. 3.0 did a few renames (e.g. _HW to _IO) and removed a whole set of o-prefixed low-byte constants (as opposed to just deprecating them).

Ok, but those were likely almost never used in practice. I'm more likely to complain about changes that break 100% of projects without exception. (Unless you count a project that somehow doesn't use a single constant anywhere.)

Ultimately the REGB_FLD-style names are just a community convention, like rgbasm's old x SET x + 1, and when there are good reasons to change, like with DEF x += 1 or here B_REG_FIELD, we don't need to say "things have always been this way, it's too late to change". Those who don't like the change, don't have to update their project's hardware.inc copy.

Yes, it is a community convention, or more like convention of hardware.inc itself. I do agree that the new suggested convention is slightly nicer, but for me, not nice enough to justify breakage.

Also note with the example of x SET x + 1, = was always an alias for SET so you always had the option to write x = x + 1 which I think from memory is what I preferred. You didn't have c-style combination operators back then (+=) and variable name had to be left justified. I still wish defining variables without DEF was never deprecated and removed though. (Although that's neither here not there.)

And yes, this is why (even just on principle) I prefer keeping a copy of hardware.inc for my projects instead of linking it as a submodule. Even though that would be pointing to a specific version of the file.

Time for a round of rate your constant:

Who wants to replace SCREEN_WIDTH with SCRN_X_B?

Ok, I admit, SCRN_X_B is a horrible name. F SCRN_X_B, all my homies hate SCRN_X_B. Using X/Y instead of W/H is weird. B postfix, apparently for bytes, is also weird and too close to the convention of B for bit indices. You might not like my suggestion of something like SCRN_W_T. Pokecrystal's SCREEN_WIDTH might seem nice at first glance, but it doesn't specify the unit of the value. (Tiles or pixels.) You could look this up at the definition, but it's perhaps not clear which one it's referring to if you see it used randomly in code. If you're unabbreviating it, at least go the whole way and explicitly call it SCREEN_WIDTH_TILES.

Or OAM_PRIORITY with OAMB_PRI?

So here's an issue with pokecrystal's constants. They don't systematically distinguish between bit indices and resolved bit masks in a good way.

; interrupt flags
DEF VBLANK     EQU 0
DEF LCD_STAT   EQU 1
DEF TIMER      EQU 2
DEF SERIAL     EQU 3
DEF JOYPAD     EQU 4
DEF IE_DEFAULT EQU (1 << SERIAL) | (1 << TIMER) | (1 << LCD_STAT) | (1 << VBLANK)

There aren't even any bit mask constants, aside from IE_DEFAULT. Probably because the game only ever uses set/res and never needs them.

And for the OAM flags:

; OAM attribute flags
DEF OAM_TILE_BANK EQU 3
DEF OAM_OBP_NUM   EQU 4 ; non CGB Mode Only
DEF OAM_X_FLIP    EQU 5
DEF OAM_Y_FLIP    EQU 6
DEF OAM_PRIORITY  EQU 7 ; 0: OBJ above BG, 1: OBJ behind BG (colors 1-3)

; BG Map attribute flags
DEF PALETTE_MASK EQU %111
DEF VRAM_BANK_1  EQU 1 << OAM_TILE_BANK ; $08
DEF OBP_NUM      EQU 1 << OAM_OBP_NUM   ; $10
DEF X_FLIP       EQU 1 << OAM_X_FLIP    ; $20
DEF Y_FLIP       EQU 1 << OAM_Y_FLIP    ; $40
DEF PRIORITY     EQU 1 << OAM_PRIORITY  ; $80

If it has the OAM_ prefix, it's a bit index, no prefix it's a bit mask. What. I know this is not what you're suggesting for hardware.inc but the observation is that it's easy to have clean looking constants when that's your convention.

My general opinion on unabbreviating the OAM and LCDC constants is: don't if you can help it. You will often have a long list of them |'d together, so every little bit of width saved helps.

[Rangi42]

(I see you have suggestions on the individual constant names, great! Will address that separately.)

I'm more likely to complain about changes that break 100% of projects without exception. (Unless you count a project that somehow doesn't use a single constant anywhere.)

Everyone whose project copy+pastes hardware.inc, or includes it as a Git submodule, will be using a static unbreakable copy. Anyone who tries updating it from v4 to v5 will realize the breaking change, hopefully because they were using the rev_Check_hardware_inc macro we've always provided, but more likely because they see "I changed something and now my build broke". Then they can add hardware_compat.inc and continue, or decide the new names look better and search+replace them. (Or the former and then gradually the latter.)

I guess we could create a gbdev/hardware2.inc repo, use hardware2.inc in resources like Pan Docs and gb-asm tutorial, announce that hardware.inc is an historical artifact which won't be getting any more major version updates, and archive this repo. But what's the advantage of that? It reifies "hardware.inc" from "the name for the thing we use for hardware constants, which continuously evolves" to "this particular file Jeff Frohwein made, which is of historical interest but now GBDev suggests using something else". The RGBDS assembler has changed more drastically than this, step by step, but at no point did we say "this isn't the ship of Theseus RGBDS any more, time to rename it".

I do agree that the new suggested convention is slightly nicer, but for me, not nice enough to justify breakage.

I agree it would be unfriendly and unhelpful to break repos without any solution. hardware_compat.inc is a drop-in solution for that. If someone's putting in the effort to edit + build + commit project updates anyway, and updates their hardware.inc copy or submodule, then this one extra line isn't a big deal.

[AntonioND]

I agree with @nitro2k01 regarding the name change. First, you're creating a new and incompatible header, so you might as well give it a new name.

But also, hardware.inc has always been an awful name. If you're going to rewrite it from scratch, you might as well give it a better name. gameboy.inc or something like that would make a lot more sense.

[Rangi42]

You might not like my suggestion of something like SCRN_W_T. Pokecrystal's SCREEN_WIDTH might seem nice at first glance, but it doesn't specify the unit of the value. (Tiles or pixels.) You could look this up at the definition, but it's perhaps not clear which one it's referring to if you see it used randomly in code. If you're unabbreviating it, at least go the whole way and explicitly call it SCREEN_WIDTH_TILES.

I was hoping that the existence of SCREEN_WIDTH_PX would be enough to imply that SCREEN_WIDTH is for tiles, like how previously the existence of SCRN_X_B implied that of SCRN_X. (I expect the width in tiles is more common, hence why we already didn't bother with a suffix for it.)

So here's an issue with pokecrystal's constants. They don't systematically distinguish between bit indices and resolved bit masks in a good way.

I totally agree! Although for its own game-engine constants pokecrystal tends to define NAME_F bit numbers and NAME masks, its hardware constants are less consistent. Constants like VBLANK and X_FLIP, with no "namespace" prefix/suffix, were just invented way back when because they seemed short and self-descriptive. That's why I want to get rid of pokecrystal's hardware_constants.asm and replace it with hardware.inc (at least, after hardware.inc improves its own names).

There aren't even any bit mask constants, aside from IE_DEFAULT.

Yeah lol, and IE_DEFAULT is a game-specific thing, nothing to do with the hardware. Hence why pret/pokecrystal#1186 moves it to ram_constants.asm.

My general opinion on unabbreviating the OAM and LCDC constants is: don't if you can help it. You will often have a long list of them |'d together, so every little bit of width saved helps.

True, and that would be one downside to pokecrystal switching to hardware.inc: I'm used to X_FLIP | Y_FLIP | PRIORITY, and having an OAM_ prefix on them all is extra typing. It's not too bad though, not an issue worth keeping pret separate from the larger community over.

I could be persuaded to abbreviate PRIORITY as PRI. My main reason against, is that "pri" looks obscure on its own, whereas "priority" reminds users "oh yeah, I heard something about OAM/BG priority, now I can look it up". @ISSOtm @vulcandth @dannye Thoughts?

(Likewise LCDC_WINDOW_OFF/ON could just be LCDC_WIN_OFF/ON; they'd have a less obvious connection to LCDC_WINDOW, but probably not a big deal?)

Given that this update no longer has an F infix for mask constants, the LCDC lengths before and after are quite close, and could be identical if we abbreviate both WIN and PRI:

; old: 133 chars
ld a, LCDCF_OFF | LCDCF_WIN9800 | LCDCF_WINOFF | LCDCF_BLK21 | LCDCF_BG9800 | LCDCF_OBJ16 | LCDCF_OBJOFF | LCDCF_BGOFF | LCDCF_PRIOFF
; new: 141 chars
ld a, LCDC_OFF | LCDC_WIN_9800 | LCDC_WINDOW_OFF | LCDC_BLOCK21 | LCDC_BG_9800 | LCDC_OBJ_16 | LCDC_OBJ_OFF | LCDC_BG_OFF | LCDC_PRIORITY_OFF
; abbreviated WIN and PRI: 133 chars
ld a, LCDC_OFF | LCDC_WIN_9800 | LCDC_WIN_OFF | LCDC_BLOCK21 | LCDC_BG_9800 | LCDC_OBJ_16 | LCDC_OBJ_OFF | LCDC_BG_OFF | LCDC_PRI_OFF

[Rangi42]

But also, hardware.inc has always been an awful name. If you're going to rewrite it from scratch, you might as well give it a better name. gameboy.inc or something like that would make a lot more sense.

Didn't we have this same sort of question in gbdev/rgbds#1609? Lots of people know and refer to "hardware.inc" and "rednex gb dev system", so <the repos that are our "official" hardware include file or assembler for the community> should keep those old names, even as they change to become incompatible. (Why have semver if we don't do any major updates?)

[AntonioND]

Didn't we have this same sort of question in gbdev/rgbds#1609? Lots of people know and refer to "hardware.inc" and "rednex gb dev system", so <the repos that are our "official" hardware include file or assembler for the community> should keep those old names, even as they change to become incompatible. (Why have semver if we don't do any major updates?)

The discussions are quite different. In the discussion of your link, the meaning of the R would only affect a couple of mentions in the documentation. This discussion is about a general push to change the register names used for decades to new names. A push that affects... well, everything. Everything has used the old names for ages: documentation, hardware.inc, emulators, etc.

Most libraries don't do big breaking changes because the maintainers don't want to annoy their users. Maintaining something doesn't mean you have to change things that work. It can also mean not doing anything but fixing bugs. It can also mean making improvements in a backwards-compatible way.

A major version increment, according to semver, can mean any breaking API change from this:

• An error code returned by a function was misleading, but users of our library may expect it to be that way, so we may break code that uses the function.

To this:

• We have rewritten the whole library.

I've stopped using libraries over breaking changes that were too big. This is also why I also think that a completely new repository would make more sense. You can point to it from the documentation and leave hardware.inc the way it is (and even mark it as a public archive, yeah).

Are you free to make breaking changes to hardware.inc? Sure, I'm not going to stop you. But this change is a matter of personal preference. In fact, I'm only leaving a comment because you added me as a reviewer, I don't have any opinion about names of a new header apart from the change itself being a bad idea. I just use my own copy of the header with the old names.

The context in the NDS homebrew scene when the big rename happened was very different (and justified). When libnds was created there was no standard yet. The libnds header change happened after a year or two of creating the initial header, and it was done to match the newly created GBATEK. It was a way to match the standard, not to create a new one.

---

In any case, this isn't a productive discussion, so I'll stop it there as well.

[pinobatch]

I've seen "prio" used in various spaces as an abbreviation for "priority". The earliest I remember is NerdTracker II, a 25+-year-old music composition tool targeting the NES sound chip.

[ISSOtm]

I don't see the point of creating a public archive, because if something is going to never change again, why allocate so much space to it? A user who decides that they stop using hardware.inc because of this 5.0 breakage would not have switched to hardware2.inc anyway.

We're doing our best to bring improvements to the most users possible, in the least painful way. That is, better names to potentially everyone who's being linked to this repo, with a compat layer if necessary.

---

I agree with "PRIO" being a better shortening of "PRIORITY" than "PRI", which sounds more like "PRINT" to me.

As for the LCDC constants, it's rather unfortunate that they need to be prefixed at all, because that's where a third of their length is coming from. But if you'll allow me a suggestion that'll likely raise some pitchforks, and leverages a rarely-seen RGBASM feature:

    ld a, LCDC_OFF | LCDC_WIN_9800 | LCDC_WINDOW_OFF | \
          LCDC_BLOCK21 | LCDC_BG_9800 | LCDC_BG_OFF | \
          LCDC_OBJ_16 | LCDC_OBJ_OFF | LCDC_PRIORITY_OFF

People do this in C, why not in assembly?

---

As for the shared OAM/attr constants, I think they should be duplicated; mostly because then we can give them each proper prefixes (OAMATTR and BGATTR?), and also because BG attributes bit 4 is unused.

[AntonioND]

I don't see the point of creating a public archive, because if something is going to never change again, why allocate so much space to it? A user who decides that they stop using hardware.inc because of this 5.0 breakage would not have switched to hardware2.inc anyway.

Well, public archive or not, I think the right approach would be either to have two repositories, or to have hardware2.inc or any other name. By default, old projects should be able to update without everything being broken.

We're doing our best to bring improvements to the most users possible, in the least painful way. That is, better names to potentially everyone who's being linked to this repo, with a compat layer if necessary.

As I've said before, this isn't really an improvement, but a complete rewrite that has very little to do with the old version that people are using. Whether that's an improvement or not is up to the users to decide, but any user that downloads hardware.inc and updates the header in their project will see that lots of things are broken.

This doesn't look to me like a good approach to updating things. Nobody expects an update that suddenly breaks everything, this doesn't look "the least painful way" at all. The least painful way is to leave the old header as it is and create a new one with any improvements you want. And you can have a compatibility header or whatever you want to make the migration easier, of course.

[Rangi42]

We're doing our best to bring improvements to the most users possible, in the least painful way. That is, better names to potentially everyone who's being linked to this repo, with a compat layer if necessary.

Exactly, thank you. <3

By default, old projects should be able to update without everything being broken.

Major version increments explicitly say "things will break", and if people don't want to change any of them, a single back-compat include will fix them all at once.

Besides, as you noted in #51, "people don't try to update everything to match the last "right way" of doing things." Old projects were never going to update this file anyway, and new ones will get the benefits without needing to learn that a new repo exists.

this isn't really an improvement, but a complete rewrite that has very little to do with the old version that people are using

Little is being actually "rewritten"; most names are only affected because of changing the B/F infix convention. How else would we improve that convention, except with a sweeping major-version change like this one? If people thought "no, I like infix B/F, it should stay that way forever", then #26 should have been closed years ago. If nobody likes it and the only reason to keep it is "change is hard", well, time to bite that bullet.

And yes, since constants would change anyway, this seemed like an ideal opportunity to improve some of the actual names, like SCRN to SCREEN and PRI to PRIORITY (or at least PRIO, not a bad idea). No reason to release 6.0 soon after this.

The least painful way is to leave the old header as it is and create a new one with any improvements you want. And you can have a compatibility header or whatever you want to make the migration easier, of course.

We do have a compatibility header. The only controversy is over whether the improvements get to be called "hardware.inc 5.0" (which would not even need an update to Pan Docs, it doesn't mention the non-official bit/mask constants anywhere) or "hardware2.inc 1.0" (which has no community mindshare and would do worse at making these improvements useful in practice).

Nobody is going to grab a new major version of hardware.inc for their old project expecting zero breakage, or at least, nobody should by the semver promise it's always made and the rev_Check_hardware_inc 4 macro they could always have been using. So they won't experience any update pain.

This discussion is about a general push to change the register names used for decades to new names. A push that affects... well, everything. Everything has used the old names for ages: documentation, hardware.inc, emulators, etc.

Again, this does not change register names. Emulators and Pan Docs will not be affected. hardware.inc already defined some aliases for official registers (e.g. rOBPI for rOCPS) and all the new ones (e.g. rSYS for rKEY0) were already added in 4.x. (See gbdev/pandocs#605.)

[Rangi42]

I've seen "prio" used in various spaces as an abbreviation for "priority". The earliest I remember is NerdTracker II, a 25+-year-old music composition tool targeting the NES sound chip.

Thank you @pinobatch! The "prio" abbreviation appears pretty common+Googlable in other contexts, so we've switched to that. :) I also shortened LCDC_WINDOW_OFF/ON to LCDC_WIN_OFF/ON. Which means an LCDC line is only one character longer, even if one doesn't want to use \ line continuations:

; old: 133 chars
ld a, LCDCF_OFF | LCDCF_WIN9800 | LCDCF_WINOFF | LCDCF_BLK21 | LCDCF_BG9800 | LCDCF_OBJ16 | LCDCF_OBJOFF | LCDCF_BGOFF | LCDCF_PRIOFF
; new: 134 chars
ld a, LCDC_OFF | LCDC_WIN_9800 | LCDC_WIN_OFF | LCDC_BLOCK21 | LCDC_BG_9800 | LCDC_OBJ_16 | LCDC_OBJ_OFF | LCDC_BG_OFF | LCDC_PRIO_OFF

(As for why I bothered adding underscores, it's because words are hard to distinguish in same-case names without any separator. For example...)

[dannye]

I think forking these changes off into a separate repo would be a mistake in the long-term.

If these changes were forked off into a new repo, it seems to me that there are only two possibilities; either the original repo would be archived (in which case, what was the point of forking?) or the two repos would eventually diverge, which would certainly add to the mess.

Letting the two repos diverge would only even possibly be a good idea if there were enough people that actually believed that the current 4.0 names are better, but I haven't seen anyone even pretend to argue that.

So, if we don't put these changes in a new repo, then the only question left to answer is: Do we stick with the current (genuinely awful, IMHO) bit/flag naming convention forever? Or do we replace it with a much, much better naming convention?

If we merge this, then all new projects will just start with 5.0 and get all the gains. Existing projects can just stick with 4.0 (it isn't broken; it works just fine) or they could update to 5.0 easily by using hardware_compat.inc or they could update to 5.0 and update their source code to use the new, better names. Updating their source code wouldn't even be that much trouble because the proposed changes in this PR aren't that radical; they're quite straightforward and systematic (and this PR isn't changing everything). But again, this is a choice; they aren't forced to make all the updates.

[dannye]

No more critiques from me after this.

[vulcandth]

I agree with all of Dannye's comments diverging the repos. This is a massive improvement as-is... Most users will continue using the hardware.inc they are using, or can redownload older versions if the prefer. The hardware_compat file will also help with older repos. New repos will benefit greatly from the better names which everyone seems to agree are actually better. The only concern was "breakage"...

[ISSOtm]

I don't know if this is the right thing to do, but I feel like there's a strong push for this change. Maybe I'll come to regret this, but we won't know if we don't try—and if strong pushback against this appears from the wider community, then we also have the option of reverting the changes, one way or another.

Therefore, merging this. Alea jacta est.

[Rangi42]

Thank you! I'll start using this in pret soon. :)

(Note that the only changed constants here which match what pret already had, are TILE_WIDTH, SCREEN_WIDTH/HEIGHT, and SCREEN_WIDTH/HEIGHT_PX. So it'll still be a significant change, particularly replacing our X_FLIP/Y_FLIP/PRIORITY names.)