Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
SCI: Add patch opcodes enum for better readability #1716
The motivation is to allow for nicer script patches with opcode names instead of "magic" numbers.
Using the new enum,
This change is backward compatible, so patches could still maintain their magic opcode numbers. This would allow for incremental refactoring of existing patches, while writing new ones with the opcode names.
I prefixed the opcode names with their numeric value for 2 reasons:
I’m a bit undecided on this one. It does help with readability, but the existing script patches will have to be adapted. Creating a script that would mass convert the existing patches would be preferable, instead of leaving this task to be done at some point in the future.
Could you please help by working on such a script?
I'm on the fence too.
What's weird is that logically, this is a natural improvement that should make things more readable, but SCI script patches are a weird medium. It would be a bit of work to convert them all and I don't think the benefits are significant, while there are downsides.
Pros to enum'in:
Pros to just hex'in:
As a patch author, I think this would add another step for me to ensure readability. I'd OCD over keeping the opcode column space-aligned so that the operand column was left aligned, and this would push the right column off even farther, which is bad because that's the one with a shot at readability. Would the existing mnemonics leave the right column once they'd been enum'd? I sweat a lot of details to make my patches holistically readable and I suspect changing the structure I took into account at the time will decrease that.
A while ago someone reformatted a ton of patch comments, some of which were needed, most of which were not, and I responded with a curter comment than warranted because I took offense, but I should have instead taken that opportunity to lay out my thoughts.
I recently had to read someone else's mid-sized patch to port it to a different game version. I didn't know anything about the bug or script prior. WOW it was hard, and it was a well documented patch. It confirmed what I suspected, that the patch code itself (two arrays of bytes) is inherently unreadable, even with a strong narrative and line-level annotations, unless you personally dive in with the original disassembly and learn the script. That's okay! Done right, these are write-once affairs with (hopefully!) entertaining narratives. Unlike normal code the goal is for them to never be maintained.
Come to think of it my one formatting wish is the opposite, for the left column's macro names to be shorter, like PATCH_GETORIGINALUINT16ADJUST(), and that's just because I want more room for the right.
If these enums help patches get written, I'm all for it. I'm uncomfortable with converting the existing ones to it, because it means monkeying with the existing comments, which only the original author had the context to express clearly, and I defer to them. I'm okay with the enums being optional, but that doesn't sound right either because then there's more than one way.
Despite being a parade of c++ word arrays, I'd wager that script_patches.cpp is the most entertaining part of the ScummVM codebase, and our best chance of bringing down the github UI should it ever start to show Terminator-like inclinations.
The resulting code is nice, but the comments now duplicate the patch:
Thing is, we need to keep one consistent way of writing script patches. Since we do have comments in all script patches, adding an enum is superfluous in existing patches. I can think of this being useful in new script patches, where the enum will substitute the corresponding comment. But then, we do not have a unified way of writing script patches.
Thus, we should either merge this and convert all the current script patches to use the enums, or not merge this, and keep writing the patches the way we do now.
I thought the code could be sprinkled with more consts and the comments could be restricted to higher level explanations, a bit like this: