Issues with the Roguelike Tutorial
Issues with the Roguelike Tutorial
Two years ago, I worked with HexDecimal, the current maintainer of the tcod library, to create an updated version of the Python Roguelike tutorial. We worked on this during the tutorial event that is hosted on the /r/roguelikedev subreddit every year, publishing the tutorials during the relevant weeks.
What we created is now the “default” tutorial suggested to beginners on the subreddit. While I’m proud of what we managed to accomplish in such a short period of time, I believe it could be improved in many ways.
So… why hasn’t it been improved?
That’s a topic for another day I think. There are a lot of reasons, some good, some not, but what I’d like to focus on is what I think the current problems of the tutorial are. The major points I think need addressing are:
Let’s dig into each of those topics a bit more.
Complexity
I think there’s a lot of frustration in the community over the complexity of the current version of the tutorial. I say I think because nobody has actually complained directly to me about this, but I have seen some people bring it up elsewhere, like in this highly upvoted post on the /r/roguelikedev subreddit. I think the post makes some good points, so let’s go through some of them quickly.
Everyone bashes the C++ for teaching “bad programming practices” and the Python tutorial (new one) as good. But imo, the older tutorials are more approachable for newer programmers. You want to draw a map, here’s how you’d do that. It’s not the most efficient way to do it, it’s not good for large maps or multiple maps, but it’s easy to understand. You want to do A? Here’s how you do A.
It’s true the older tutorials are simpler and easier, and I do think the newer (Python) one loses some of that. I have some thoughts about simplicity vs complexity that I’ll get into later.
The new tutorials have gone crazy. Context managers to handle the program, using Optional events to handle events, rendering the map using NumPy elements.
While the new tutorial undoubtedly sets up users better in the long run, by giving them a better framework to build off of, I do agree that it’s a bit daunting for new people. The reality is that if you’re writing a roguelike in Python, then you’re probably not all that experienced in programming games (not criticizing anyone, I’m not either!). Perhaps people seeking out a Python tutorial are more interested in something more straightforward, even if the “engine” created in the end isn’t as solid.
Quick counter-point about NumPy: That’s not going away. The harsh reality is that if you want to write a Python roguelike, you must use NumPy. Believe me, I tried writing a Python-based roguelike without it, and you’re going to hit performance issues immediately. Perhaps the tutorial needs to explain this better, and give a better understanding of how NumPy works (which is going to require me to better understand how it works; I don’t use NumPy in my day-to-day!).
Now it’s crazy, if someone asked me how to do simple event handling in tcod I’d have no idea.
tcod's API has changed quite a bit recently, and for the better, in my opinion. It’s my own failure in not explaining how it works. A lot of the tutorial was frankly rushed, so I didn’t go into a lot of detail of how or why, because I was just trying to keep up with getting the sections done.
In my opinion a user who does the Tutorial know how to make a ‘@’ appear on screen and control it using keyboard buttons in a short, single page python file.
A single file is a bad idea in my opinion. It’s actually the whole reason I set out on my “roguelike tutorial writing journey” (bit of a stretch calling it a “journey”, I know). Still, I understand the sentiment: The old tutorial was a lot simpler. I believe there can be a middle ground between the old tutorial’s “single file, globals everywhere” approach, and the way it’s written now.
If you’re interested, I’d highly recommend checking out the Reddit post that I’m responding to. I think it brings up a lot of good points, and ones that I’m sure many people agree with on some level.
Those sections
Anyone who has read the tutorial knows what I’m talking about. The beginnings of Part 6 and Part 8 both have these absolutely awful sections where, out of nowhere and seemingly for no reason at all, I ask users to refactor a bunch of code. The reason was that we were writing all of this while the tutorial event was happening, and some things were changed partway through.
I need to go back through parts 1-8 and rewrite with these changes in mind… but I haven’t.
Now, dear reader, you’re probably thinking to yourself, Tyler, why are you writing this instead of just working on those parts? Get off your lazy ass and get it done already!
You’re absolutely right to think that. The truth is that working on the tutorial is pretty time consuming and mentally exhausting, so for the last two years, I just… haven’t done that. Originally, I was going to get into my personal reasons for not working on the tutorial more, but this post is long as it is, so I’ll leave that out. Perhaps I’ll express those thoughts for a separate post, if anyone cares.
The bottom line is that those sections are there, they’re terrible, and they’re a huge drag on the tutorial as a whole.
Lack of Explanations
This is, again, down to the tutorial being rushed. Design decisions, tcod APIs, and a whole host of other things just… aren’t explained well, if at all. This is a huge problem, as many people reading the tutorial are fairly inexperienced programmers. I’m sure people with some experience can read the code and understand it fairly well, but I’ve been wondering lately how much of the target audience that really is.
As I mentioned before on the NumPy point, some of the “complexity” can’t go away. That doesn’t mean it can’t be explained better.
It’s unfair to just post a bunch of code and say “write this in your program, because I say so!” Decisions about how the project is laid out should be explained, so that if users end up disagreeing with how something is implemented, they have a chance to understand the logic behind it, and implement it their own way. After all, the ultimate goal of a tutorial should be empowering users to make their own decisions about their own game.
Lack of “Extras”
As of writing, there is one “extra” section: A more “Traditional” look. It barely even counts as an extra, to be honest. It’s just changing a few lines to make the resulting game look more like most people would expect a roguelike to look.
The original tutorial has all kinds of extras, like mouse driven menus, scrolling maps, and graphical tiles. These sections are all great, and I’d love to translate them to the current tutorial. But again, I just haven’t. Sorry again for that.
It’s worth noting that the original tutorial has an extra on creating a binary to deliver the finished game. I actually think this should be part of the tutorial proper, because what good is a game that you can’t deliver to your players? (It’s also a frequently asked question from people who finish the tutorial).
No animations
This one might be a bit subjective, but I think the tutorial should include some basic animations. You know, covering the fireball explosion area in red asterisks, drawing yellow dashes on the path of the lightning bolt, real basic stuff like that.
Some people may think it unnecessary, but I think it’d be a neat addition. Especially since the tutorial as it is delivers a somewhat decent UI (you know, for a roguelike, anyway).
Again, this one is a pretty commonly asked question from people who have finished the tutorial, so it’s probably worth exploring.
My own Inexperience
A large part of the reason the tutorial isn’t great is because I have never actually written a roguelike. Yes, it’s shameful for me to admit, but I wrote two roguelike tutorials without ever actually delivering something myself.
Being a part of the roguelike development “community” and not having ever shipped a roguelike isn’t exactly a unique experience. In fact, a lot of people who write articles (very good articles!) and create development libraries (very good libraries!) haven’t actually shipped a game either. Still, I feel this sense of impostor syndrome from telling other people how to structure their code, despite the fact that there’s nothing about me, specifically, that really gives me any right to do so.
I’ve had several projects in the last few years, of course, but most of them never got all that far, and many of them weren’t even written in Python. While Python is the language I use the most professionally, I haven’t had a huge desire to use it in side projects as of late. In fact, I’ve recently been toying with a roguelike in C# and MonoGame, but that’s enough about my personal projects for now.
I am constantly improving as a programmer (at least I hope so!), so I think if I were to contribute to something like this again, my contributions would at least be better, if still not fantastic. The last few years have been pretty good for me in terms of personal development skill, whereas when I wrote both the 2017 and 2020 tutorials, I was working at the same place professionally, where I honestly didn’t improve very much.
What to do about all this?
So there’s a few things I’d like to do moving forward, as time allows. In no specific order:
- Fixing those sections. This may require a complete rewrite of earlier sections.
- Speaking of a rewrite, the “sections” of the current tutorial are based on the old one on Roguebasin. I did this originally to match the cadence of the weekly tutorial events, but I wonder if this tutorial could be rewritten better by combining, reorganizing, or flat out axing certain parts.
- Adding more “extras” sections.
- Adding animations. Would probably need to be worked in early rather than tacking it on as an “extra” (though if that’s possible, that route is better).
- Reducing complexity, where possible. (Sadly I don’t have a specific plan for this yet.)
- Adding CI to the site. That way, contributors don’t have to wait on me to merge/deploy changes when issues come up. This one is actually in progress already!
I have a few ideas on how to do some of this, but it’s all early idea stages right now. As mentioned earlier, for personal reasons, I haven’t put too much thought or time into this project lately, though I’d like to change that in the coming months.
If you made it this far, genuinely, thanks for reading. Feel free to shoot any thoughts, suggestions, ideas, or criticisms to me either on Reddit or Github