Updated v2 tutorial for using tcod 21.2.0, numpy 2.x and modern python

[Darky-Lucera]

Summary

This PR updates the v2 tutorial to work with tcod 21.2.0 and NumPy 2.x, bringing them in line with the current library API. 27 files changed across content/tutorials/tcod/2019/ (parts 0–13, except part-3) and content/tutorials/tcod/v2/ (parts 0–13).

The changes are intentionally minimal and surgical: only API-level replacements, no rewriting of game logic or tutorial structure.

---

Changes

The v2 series was closer to the modern API but still had some outdated calls and deprecated patterns:

• tcod.context.new_terminal(...) → tcod.context.new(columns=..., rows=...) (deprecated name)
• tcod.Console(...) → tcod.console.Console(...) (canonical path)
• .print(string=...) → .print(text=...) (parameter renamed in tcod 11.x)
• root_console → console (consistent rename throughout)
• int(x / 2) → x // 2 (idiomatic integer division)
• np.bool → np.bool_ — important fix: np.bool was removed in NumPy 1.24; this would crash with NumPy 2.x
• if event.type == "QUIT": → match event: case tcod.event.Quit(): (modern event handling)
• Path(__file__).with_name(...) for asset paths — more robust than bare strings
• from __future__ import annotations added consistently
• Type hints modernized (Optional[X] → X | None)
• Dependency versions updated: tcod>=21.2,<22, numpy>=2.4,<3
• Python minimum updated to 3.11; reviewed with Python 3.14.4, tcod 21.2.0, numpy 2.4.2 (April 2026)
• Version notes in part-3 and other parts updated to reflect current library versions

---

Why these tutorials are still worth maintaining

I'd like to make a case for keeping both series alive and up to date.

These are still among the best beginner roguelike tutorials available. The structure — 14 parts, building a complete dungeon crawler from scratch, covering everything from a moving @ to saving/loading, inventory, spells, equipment and procedural generation — is genuinely hard to find elsewhere at this level of quality and completeness. The RogueBasin lineage gives them credibility, and the Python + tcod combination is still the most accessible entry point for someone who wants to write a roguelike without wrestling with C++ or a full game engine.

The 2019 series and v2 serve different audiences, and both have real value:

The 2019 series is the better tutorial for a complete beginner. Part 1 is 40 lines and you have a moving @ on screen. The patterns it teaches — handle_keys returning dicts, GameStates enum, step-by-step render functions — are "visible" complexity: the code looks like what it does. The fact that those patterns don't scale well is actually pedagogically useful: you experience the pain of an ever-growing if/elif in engine.py and discover why you'd want to refactor. That motivated discovery is worth more than copying a clean Action + EventHandler pattern without knowing what problem it solves.

The v2 series is the better tutorial if you already have some OOP experience and want to end up with a codebase you can actually extend. The Action-based input, interchangeable EventHandlers as a state machine, NumPy for the map and FOV, and pickle+lzma serialization of the whole Engine are all genuinely good architectural decisions that hold up as the codebase grows. The type hints and from __future__ import annotations also teach habits that matter in real Python projects.

In short: the 2019 series teaches you how to build a roguelike; the v2 teaches you how to build one well. Both are useful. Keeping them up to date means both remain usable entry points rather than historical artifacts that confuse beginners with deprecated API calls and AttributeError: module 'numpy' has no attribute 'bool'.

[HexDecimal]

The website maintainer is absent so not much will come from making a pull request to this repo.

Updating the existing tutorials is something I'm interested in, but there's not much I can do here. I'd accept the updated tutorials being added to the official python-tcod docs if they were converted to reStructuredText and Sphinx directives.

[Darky-Lucera]

Oops!
Not sure how to do it. I have never worked with reStructuredText and Sphinx directives, but I can give it a try.
Any advice?

[HexDecimal]

reStructuredText is not the nicest format to work with, but it's the standard format of Sphinx and most Python documentation. It's easy to find a syntax reference for reStructuredText and the Sphinx manual is the best place to look for both the syntax and the directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

While Sphinx can support Markdown it doesn't work very well for complex code examples.

I've written an incomplete tutorial in the past, and looking at the raw text can give a good idea of what syntax to use: https://github.com/libtcod/python-tcod/tree/main/docs/tutorial

I'm unsure how to handle the hybrid-diff widgets. As far as I know those are unique to this site. Using plain diff syntax highlighting might be the best option.

Feel me to ask me anything more specific.

[Darky-Lucera]

It seems that there is an extension called sphinx-tabs but it seems a complicated change just to maintain the Diff / Original couple. It's probably not worth the effort.

So the plan would be to use plain .. code-block:: diff for all the 'change sections', and drop the dual-view widgets entirely.
Do you agree?