New 2023 Python-tcod tutorial

[HexDecimal]

You can view the in-progress tutorial here: https://python-tcod.readthedocs.io/en/latest/tutorial/index.html

I've made a collection of resources in prepration for making a new Python-tcod tutorial. In hindsight I should've done this much sooner.

Criticism of the previous tutorials: TStand90/roguelike-tutorials-website#38

The /r/roguelikedev tutorial series for reference: https://old.reddit.com/r/roguelikedev/wiki/python_tutorial_series

The 2020 Python tutorial for reference: http://rogueliketutorials.com/tutorials/tcod/v2/

The repo to hold the tutorial source code is here: https://github.com/HexDecimal/python-tcod-tutorial-2023

I plan on using tcod of course as well as the tcod extensions tcod-ecs and tcod-camera. Other modules such as scipy and attrs might also be used. Because a tutorial like this always ages I'll be using Python 3.11 instead of any older version.

The tutorial will likely be a simplified version of the engine I've been experimented with.

Any suggestions for the tutorial can go either to this post, as an issue on the tutorial repo, or as a discussion on the tutorial repo.

Currently following this guide for tutorial writing: https://diataxis.fr/tutorials/

[rjmagley]

The link to the in-progress tutorial above seems to be broken - https://python-tcod.readthedocs.io/en/latest/tutorial/index.html seems to take you there, though.

[HexDecimal]

Thanks. I guess at some point I decided to drop the year and switch to something I could update progressively. I've also setup a redirect for https://python-tcod.readthedocs.io/en/tutorial-2023.

[GreyGoldFish]

Here's my feedback after following the current version of the tutorial up to Part 1:

When the tutorial project is finished, I think that it'd be nice to be able to get a preview of it on Part 0.

An example game state

• You could add an explanation or a link about game states in general, as the meaning might be unclear.
• I believe I understand why you chose to import attrs, but perhaps you could add your own reasoning.
• The line tcod.tileset.procedural_block_elements(tileset=tileset) isn't mentioned in the explanation.
• I really like that you added links about Structural Pattern Matching.

I don't have anything specific to say about other sections, but in general I felt like it took me a while to understand what was being done until I saw the code. Perhaps you could break the code down as you explain it, like so:

Configuring an event loop

The next step is to keep the window open until the user closes it.

Since nothing is displayed yet a Console should be created with "Hello World" printed to it. The size of the console can be used as a reference to create the context by adding the console to tcod.context.new.

...
tileset = tcod.tileset.load_tilesheet(
  "data/Alloy_curses_12x12.png", columns=16, rows=16, charmap=tcod.tileset.CHARMAP_CP437
)
console = tcod.console.Console(80, 50)
console.print(0, 0, "Hello World")  # Test text by printing "Hello World" to the console
...

Begin the main game loop with a while True: statement.

To actually display the console to the window the Context.present method must be called with the console as a parameter. Do this first in the game loop before handing events.

...
with tcod.context.new(console=console, tileset=tileset) as context:
        while True:  # Main loop
            context.present(console)  # Render the console to the window and show it
...

Events are checked by iterating over all pending events with tcod.event.wait. Use the code for event in tcod.event.wait(): to begin handing events.

In the event loop start with the line print(event) so that all events can be viewed from the program output. Then test if an event is for closing the window with if isinstance(event, tcod.event.Quit):. If this is True then you should exit the function with raise SystemExit().

...
with tcod.context.new(console=console, tileset=tileset) as context:
        while True:  # Main loop
            context.present(console)  # Render the console to the window and show it
            for event in tcod.event.wait():  # Event loop, blocks until pending events exist
                print(event)
                if isinstance(event, tcod.event.Quit):
                    raise SystemExit()
...

If you run this then you get a window saying "Hello World". The window can be resized and the console will be stretched to fit the new resolution. When you do anything such as press a key or interact with the window the event for that action will be printed to the program output.

I'm excited to see the finished tutorial. Thank you for all of your work.

[HexDecimal]

You could add an explanation or a link about game states in general, as the meaning might be unclear.

Good idea, I'll try to include a link to https://gameprogrammingpatterns.com/state.html where it's relevant.

I believe I understand why you chose to import attrs, but perhaps you could add your reasoning.

Not using attrs means that a lot of simple classes would've require a ton of boilerplate to write. attrs has better default behavior for classes in general and allows the easy creation of immutable classes which will become important later on when I add tcod-ecs. Plus as a project using Mypy several dynamically typed options would also have a lot of extra boilerplate.

A full explanation may be outside of the scope of this tutorial, but I might be able to link to something in the attrs docs.

The line tcod.tileset.procedural_block_elements(tileset=tileset) isn't mentioned in the explanation.

I missed this when I went and highlighted my examples. Thanks for pointing it out.

I don't have anything specific to say about other sections, but in general I felt like it took me a while to understand what was being done until I saw the code. Perhaps you could break the code down as you explain it, like so:

I ended up grouping sections so that the reader can see results after every example by running their code, but it makes sense to split it up into smaller examples like you've shown.

[GreyGoldFish]

I ended up grouping sections so that the reader can see results over every example by running their code, but it makes sense to split it up into smaller examples like you've shown.

That's fair enough. Then I'd suggest that you change the code to include everything that you need to just CTRL + A, copy and paste, then run. You could perhaps add sections in-between refactors with "The code so far:", for example.

A minor nitpick: I don't think that the ... in the first line are necessary in the first few code blocks, as there are no other modules to import.

[HexDecimal]

That's fair enough. Then I'd suggest that you change the code to include everything that you need to just CTRL + A, copy and paste, then run. You could perhaps add sections in-between refactors with "The code so far:", for example.

I was worried that this could become too verbose, but now I think it would be better than the current method, at least until the examples become larger.

A minor nitpick: I don't think that the ... in the first line are necessary in the first few code blocks, as there are no other modules to import.

Good idea. In my mind I kept imagining a script starting with #!/usr/bin/env python3 which isn't being used for this tutorial and thus doesn't need to be shown or explained.