Use `jr` in Unbricked and Galactic Armada when appropriate

[quinnyo]

The issue is that jr is used (mostly out of habit, by me) to jump to labelled functions.
This places constraints on the (ROM) layout of the code, but the lesson doesn't attempt to instruct the reader to take care with that, or present the functions in an order that will be sure to result in a valid layout -- and I don't think it should.

The simple solution is to replace jr with jp, wherever the destination is one of the labelled functions. There is a couple of anonymous destinations (i.e. jr .., :+) which won't cause any problems remaining as jr.

[ISSOtm]

I'm not sure that jr has been introduced at all at that point in the tutorial? The rationale for using jp always was to avoid front-loading that complexity at this point in the tutorial (though, yes, it does build up bad muscle memory, unfortunately...)

[Rangi42]

I think it's worth just biting the bullet and introducing jr fairly early on, soon after "Hello World". The core concept is simple: it saves you one byte and one CPU cycle over jp, but can only jump a "short" distance.

The precise meaning of "short" is arguably complex, but not compared to all those other front-loaded concepts -- "POSIX environment", "base 2 and 16", "registers vs RAM", "flags", etc.

And the later jr is introduced, the more code the student is left with to go back and postmaturely optimize.

[avivace]

I agree with @Rangi42 , let's just introduce it early

[ISSOtm]

And the later jr is introduced, the more code the student is left with to go back and postmaturely optimize.

I was thinking that it would be introduced in Part III, since Part II is intended to be “we're doing some things The Wrong Way for simplicity's sake”.

[Rangi42]

jr is not so complicated that the entire "Part II - Our first game" needs to omit it.

IMO the Right Way should be taught earlier in general, so that when/if the tutorial writing gets stalled, people aren't left learning the Wrong Way with little or no material towards the incomplete/unpolished end correcting them.

[avivace]

Agree with @Rangi42 here, I'd use it as soon as possible honestly. It's not a big cognitive load and there's no formative value in learning it wrong just to have to re-learn it later

@quinnyo would you like to work on it?

[quinnyo]

I'm not opposed outright to teaching jr at some point early-on, but I see very little value added from doing so. The """Right""" and """Wrong""" language being used makes me wary of saying the wrong thing, and I've been trying to write a suitable response for hours now and I just have to stop. I'll come back to it at some point with a more complete response, but for now I'll just dump a pile of notes:

• I provided what I think is a very good reason to avoid using jr in the tutorial code in the top comment.
  • jr makes the lessons harder to write and makes it more likely that participants will have a bad time
• Similarly, using jr in real-world projects is not free. It calcifies your code. It's a tradeoff.
• Teaching good optimisation practices is a lot of more complicated than teaching what jr does. Showing a beginner the faster"""Right""" way to do a jump seems quite likely to teach them bad practice optimisation strategies. Learning effective optimisation techniques is something that, sadly, requires experience.
• Nobody has described the benefits of teaching jr early on
  • I mean other than the """Right""" and """Wrong""" stuff
  • there's some suggestion that learning without jr will do some damage, but I can't imagine what that would be.
• I have no doubt that it's feasible to teach people about it, but a beginner at the start of the tutorial isn't really in a position to do anything with jr, so why complicate things?
• It saves one Mcycle, sure, but a better way to describe the difference is that it takes three quarters of the time that jp does.

You could say that teaching a beginner to count cycles is premature 😎😎😎😎😎😎😎😎

[Rangi42]

jr makes the lessons harder to write and makes it more likely that participants will have a bad time.

Same goes for hex and binary numbers, POSIX tools, having to do arithmetic via an "accumulator", unfamiliar bitwise operations...

Teaching good optimisation practices is a lot of more complicated than teaching what jr does.

Correct, which is why I'm not suggesting to front-load a bunch of micro-optimizations. jr, on the other hand, is not some subtle or complex optimization: it's literally the idiomatic way to do short jumps, that beginners would see in any other project they care to look at for reference.

Nobody has described the benefits of teaching jr early on.

The benefit is that this is the GB asm tutorial, meant for teaching how to write GB asm. Starting off by writing entire games in a non-idiomatic, over-simplified way that teaches bad habits, with the intent to eventually get around to writing much later steps that say "psych, we've taught you poorly, go back and update your code", is not

You could say that teaching a beginner to count cycles is premature 😎😎😎😎😎😎😎😎

This is not the sick burn that you think it is. (Sorry, I was being too annoyed and rude there.) Skim over the sections in Part 1 again, and think about how complex it all seems to someone who's still learning about binary, has to transition from Windows to POSIX, has to deal with an "accumulator" and "flags" instead of if a + b == c and d / e == f... And then note that https://gbdev.io/gb-asm-tutorial/part1/jumps.html even lists jr already in its table of jumps. If we're capable of teaching all that other material well, we're capable of adding a paragraph to I.10 explaining jr in a beginner-friendly way. (And vice-versa.)

Note that https://gbdev.io/rgbds-live/ has an edited copy of the Hello World source, demonstrating where jr could be used well. Even if we still don't want to front-load local labels and calls, using jr for the WaitVBlank loop would be a 100% appropriate thing to teach. (It's certainly less complicated and involves fewer concepts than using ds $150 - @, 0 to "make room for the header" instead of SECTION "Start", ROM0[$150].)

[ISSOtm]

I remain vehemently opposed to this idea, because:

• It is not because we are front-loading some complexity that we should front-load all of it. Rather, we should strive to keep it to the minimum necessary to teach what we're really interested in. If you can find a way to remove some of that complexity, then please do—if you have the bandwidth to write and maintain a Windows-centric version of all of the relevant parts of the tutorial, you are more than welcome to do so, because you would be decreasing friction in getting started.

• Further, simplifications are required anyway. The simplification I propose is “let's only use a sure-fire way to jump”; the simplification you propose is “let's only use jr in contexts where we know it's safe, but not in all contexts where they could be reasonably used (e.g. jring across the header)”. Until the reader has learned enough to be able to grok the full explanation (it's only able to jump a certain amount of bytes forward) and ideally also best practices, we will have to “psych” them to some extent.

  The main difference is that we are not lying, we are pacing the rate at which things are being introduced. We cannot teach the reader to write idiomatic assembly at once, so we need to build things on top of others; I believe this parallels the principle of “make it work, then make it fast” but for teaching: “make it work, then make it idiomatic”.

  I believe this also turns out to help explain why one would want to use this or that feature: I have found that people learn better when they first experience the frustration that its lack generates, and then when they learn how to fill that gap, they get a better idea for when to use either alternative. (I distinctly remember struggling to decide between putting variables in WRAM0 or HRAM, using call vs. rst, and whether to use global or local labels, when I first started self-teaching assembly.)

• And, lastly, I also share quinn's view that introducing jr this early is as premature as “premature optimisation”: I selected jp because I wanted to explain the concept of control flow, and needed a way to show it in action. We need not talk about the subtleties and nuances of that at the same time as introducing it, no more than we need to talk about the order in which tile data gets fetched when we introduce the concept of tiles.

  Yes, the reader is going to make some assumptions, and there's nothing we can do about that. “Oh, what do you mean the frame isn't rendered all at once? Huh.” I've personally tried pre-empting all of those in the OG asm-tutorial, and it was generally considered to be intractable for newcomers.

• Lastly, due to our inherent biases as experts (obligatory XKCD), I will much more gladly err on the side of assuming things are much harder to understand than they seem to be to us, and thus I reject the idea that introducing jr is “not a big cognitive load”. I don't know, if only because that will vary a lot from person to person, but I am deeply convinced that we should always err on the side of introducing as little as possible, in part by my own memories of reading expert-written documentation as a complete newbie (e.g. at work) that was making a lot of assumptions and referenced concepts and acronyms I had no idea about.

  I mean, consider how many developer tooling tutorials out there already assume familiarity with the command line, and then talk about “TUI”, “completions”, “can be used as a systemd service” (what is a systemd and why would I want it??)—likewise, at least for the vision I had when I started writing this tutorial (and which I want to pursue when I eventually\™ will have cleared enough off my stack to get back to it), we should strive to be accessible to as wide an audience as possible.

  This is partly motivated by the fact that GB dev is becoming more popular among younger people, who we can thus assume to have a basic programming education (without programming, they'd be using GB Studio) and thus a grasp of variables and control flow primitives, but not necessarily of how memory allocation, pointers, etc. work (we're not targeting graybeards, and who below the age of 20 learns C these days?)

[Rangi42]

This section introduces ds-in-ROM (very uncommon compared to db and dw) and the @` symbol; and the next section, "Memory", introduces "memory chips", "little cells that can store current" (irrelevant physical detail, which a footnote notes may not even be accurate), "physical addresses" (not something I've ever needed to think about when programming assembly), a whole memory map table (when all that's needed to talk about at this point is ROM0 and I/O), a footnote about "punching holes into a layer of silicon using acid"...

None of that is important information, certainly not early in a tutorial. It is not "pacing the rate at which things are being introduced", it is doing the student a disservice by going into unnecessary detail, instead of teaching them about concepts that will be more relevant to any real project they're working on.

It's great that GB dev is becoming more popular among younger people. Your original vision for the tutorial -- a complete artifact that shows how to naïvely create a project, then note all the flaws with it and justify teaching how to fix them -- may have been good for that. But since the tutorial has been on the back-burner for the past two years and won't realistically get fully written to your exact vision, I think the responsible thing for us to do is prioritize accurate fundamentals.

Omitting jr (and omitting local labels, as per #153) is a kind of lie-to-children like saying you can't take the square root of a negative number. If we had an equivalent of higher education already prepared, where they would learn about complex numbers relative jumps and local labels, then it might be justifiable. But right now we don't have that. And I think #151 and #154 demonstrate how easy it is to briefly explain them, especially when you step back and look at how complex all the steps leading up to them are.

[ISSOtm]

Further, rather than “Right” or “Wrong”, I think Sylvie nailed that on the head: “idiomatic” versus “non-idiomatic” is exactly what I was trying to say, but failing to name.

I also agree with quinn's point (“jr places constraints...”), but not as a tutorial maintainer, but as a hypothetical reader: using jr comes with subtle (for a newbie, at least) restrictions that generate error messages that they may have trouble making sense of at all; conversely, the loss from them never using jr is a bit of performance loss, but c'mon, people make commercial releases with GBDK or even GB Studio, I doubt that's gonna be a show-stopper.

We need to teach people to write games in non-idiomatic ways. I've tried, during one-on-one Discord teaching sessions (ca. 2018 probably), teaching exclusively idiomatic patterns on the first round. It didn't work, because that was too much complexity and subtlety at once. Instead, yes, we could introduce everything before starting to write code, but that has also failed (that's gb-asm-tutorial-old)—too much theory before grounding anything in reality. And, in practice, without the tutorial, that is exactly how people learn: by writing terrible, unidiomatic code, stumbling over issues, and learning from that. I do not think that the goal of the tutorial should be to avoid those, but instead to make them happen in a controlled environment so that the reader can learn more from them and do so faster than they would on their own from first principles. (Because we already know what “the right direction to go from there” is, instead of requiring exploration and a feedback loop.)

None of that is important information, certainly not early in a tutorial.

This is entirely possible. I assumed, myself, when writing it, that it would be good to ground the programming in the console's hardware, but you are correct that there are a bunch of concepts that it relies on. Therefore, I am in favour of reworking that the be a better introduction, or outright removing it if the consensus is reached that it can't be salvaged.

I think the responsible thing for us to do is prioritize accurate fundamentals

By nature, the tutorial omits things when it first introduces them. For example, the Hello World directly accesses VRAM without talking about PPU safety. This is fine, because as you said above, we need to build accurate fundamentals. Instead of saying “you can't take the square root of negatives”, we can say “taking the square root of negatives is more complicated than we care about right now, so let's punt it off to next year/section”. (Or, since this is a monologue and nobody will be asking questions, save the text when appropriate to keep lessons shorter and more focused, and outright omit things that don't need to be mentioned yet.)

I don't care for the tutorial to be written to my exact vision either; Galactic-Armada is already something I'd consider unidiomatic in several ways, for example, but that's fine because it's good enough. The reason why I am pushing back this hard on this issue is not because I want to stick to My Way of doing things, but because I believe that the direction you are proposing jeopardises the entire value-add proposal of the tutorial. Perhaps that is because we have different target audiences in mind? I don't know. But I know the tutorial as currently written has helped several of those relative beginners, and thus I believe that it is worth pursuing that goal. But, this is GBDev's project, not mine; so if the consensus turns out to be that we should target another group than what I have in mind, then I will simply bow out and make my own (w/BJ&H, of course! 😛) on my own.

If we had an equivalent of higher education already prepared, [...] then it might be justifiable. But right now we don't have that.

Well, yes, such a lesson hasn't been written yet, but you could just as well write it, if you feel able to contribute to the tutorial? This isn't a “you versus me” situation, I genuinely believe we can find a solution we both agree with.

Note that the reason those lessons don't exist yet is because I decided to write the tutorial bottom-up instead of top-down, based on my own experience building software: starting from the fundamentals, so that later lessons know what they can rely on, without then having to shoehorn lessons awkwardly because of lack of foresight. This is also why I dragged my feet a lot before accepting Galactic Armada—but I ended up compromising in the end, so..?

The later lessons don't exist because they don't exist yet? Lessons necessarily an order they're written in, so IMO it's fine to incrementally build the tutorial, expecting the rest to be contributed at a later point. Isn't that the spirit of open-source? Making something, possibly incomplete, and having it be built upon by other people, in time?

[Rangi42]

If we had an equivalent of higher education already prepared, [...] then it might be justifiable. But right now we don't have that.

Well, yes, such a lesson hasn't been written yet, but you could just as well write it, if you feel able to contribute to the tutorial? This isn't a “you versus me” situation, I genuinely believe we can find a solution we both agree with.

No, this is a trap and I want to avoid it.

Your original plan was to have prepared that, but then you -- very understandably -- got burned out, and contributions from others have of course not matched your own vision of what a complete tutorial would look like, and also of course other devs' contributions still haven't gotten the tutorial to a Finished state. (After all, this whole issue was initially proposing to hobble Part III by changing its jrs to jps, as if three parts into a GB tutorial, with two whole functioning games under their belt, is still too early for students to comprehend those complicated "relative jump" instructions that were listed in a table in Part I but not described further. /s)

If I said "sure, I'll write Part IV+", I'd be volunteering to boil yet another ocean. It's biting off more than I can chew. That goes for me and you and most other individuals. It's a grand scope that's unrealistic to aspire to.

At the moment I'm trying to contribute to the tutorial as it actually is, not as we'd like some distant much larger one to be. For me, that means updating Part I to teach more of the idiomatic fundamentals -- not MACROs or {interpolation}s or popslides or HBlank interrupt tricks, don't worry, but simple things that will be widely applicable in all the future parts.

The whole premise of this issue was "oops, well-meaning volunteers trying to write more advanced tutorial sections have used this idiomatic thing which we deliberately haven't taught yet... let's modify their code not to use it". I think that's the antithesis of good teaching. If jr is so natural that it's crept into Part II by accident, that's evidence it should have been taught already. (And I think everything we're saying here, pro and con, applies to local labels too.)

If the first part teaches a good foundation, that means students will spend some more time meditating on the "toy" project of Hello World, but it also means they'll have more tools for making real projects well. And just as importantly, new contributors to GBDev will have an easier time writing more tutorial parts, because they won't have so many artificial restrictions to keep in mind.

[ISSOtm]

I'm not sure how it's a trap?

Anyway; I believe that jr is only natural in hindsight, like hexadecimal, CPU-PPU sync, or macros are natural to us because we're on the other side of the fence, however they are far from so before you learn enough to be able to make that jump. Put another way: if jr is natural and idiomatic, then why is is not intuitive for beginners to write code that uses it? I know I certainly didn't, but perhaps I am an exception.

Thus, I do not believe that it is a good idea to teach it this early. (Referring back to that XKCD to try and give an example of what I want to say: no, teaching the structure of quartz is not a good thing to start with, even though it becomes second nature eventually.)

Also, the first part wasn't written with the goal of providing a foundation, it was written with the objective of “how can I get something meaningful on-screen while introducing the minimum amount of concepts?”, in order to get the reader something concrete and meaningful with as little friction as possible. Which is why, again, I feel very grateful that you have recognised some of its parts as superfluous, and wish to remove them.

~—~

I do not want to hobble Part III; the plan that I had in mind is to have Part III be as idiomatic as possible (just not “advanced”, such as using interpolation, self-modifying code, etc.), and thus we'd explain instruction encoding somewhere in there. (Possibly as a sort of retrospective/analysis of Part II, or perhaps within Part II itself? If you have suggestions, or wish to write such a lesson like #137 did, then by all means!) But, again, that hasn't been written, because there hasn't been manpower put behind that yet. (And I feel reluctant to even plan a Part IV, because that would make the tutorial longer than most attention spans would appreciate; not unless it's optional, such as some kind of “Part IV — Wizardry”.)

And, yes, I have burned out from writing, but I have not burned out from maintaining the tutorial itself. I have not yet found it in me to try and type out entire pages and accompanying code, but even when I was more severely burned out, I still directed Evie to write the code and substance of Part II. I would say that the style does not match mine (which is a necessary and acceptable loss in my eyes), but the direction remains consistent. (Part III, however, I believe needs some rework.) And, yes, that is having others do my bidding, but that was the entire point of donating money and putting bounties on issues; I'm not expecting people to do things I want for free.

And yes, the stream of issues clearly scoped with bounties attached has stopped for a few years; but I have a good excuse for that hiatus, and we could resume it if we got the ball rolling again. I don't know; do you and @avivace think it'd be worth doing?