Adding my new Pygame book as a Tutorial

[adamsralf]

I’d like to have my Pygame book linked as a tutorial on the Pygame-ce website.

Here is the link to the PDF:
https://github.com/adamsralf/pygame_book/blob/main/00%20pygamece.pdf

And here is the link to the corresponding project:
https://github.com/adamsralf/pygame_book

[robotsnh]

Just to clarify, would you like to list it on the pygame-ce website (pyga.me) or the mainline pygame website (pygame.org)? The pyga.me repo is here, whereas the main pygame repo is here. In my opinion, the pygame.org one is not maintained as well, the last commit being 2 years ago, but it's ultimately up to you.

[robotsnh]

If you do intend to post this issue on another repo, please close the one here.

[adamsralf]

The script ist focused on pygame-ce. So I want it to be referenced on pyga.me.

[robotsnh]

Great, please hop over to that repo and close this issue :)

[Starbuck5]

No, this is the correct repo for tutorial content.

Just to clarify, would you like to list it on the pygame-ce website (pyga.me) or the mainline pygame website (pygame.org)? The pyga.me repo is here, whereas the main pygame repo is here. In my opinion, the pygame.org one is not maintained as well, the last commit being 2 years ago, but it's ultimately up to you.

These are some bizarre hyperlinks.

[adamsralf]

I'm confused. Who's right? I've got no problem to switch but I want to avoid to have the same discussion over there.

[Starbuck5]

If I need to pull rank, I'm a member of this organization on Github and I'm the 2nd most prolific contributor to pygame-ce by commit count. I'm right.

[adamsralf]

Ok, fine. So I'm just waiting or is there anything for me to do?

[oddbookworm]

@robotsnh please refrain from acting like you're someone with any kind of pull over someone else's project. We appreciate that you're trying to involve yourself, but you should leave telling people what they should do to those of us that actually maintain the repo and know the correct path. In fact, you're not fully correct here. The docs portion of pyga.me is fully generated from the docs in this repository. So if OP wants it to appear in docs, this issue is in the correct place

[oddbookworm]

@adamsralf for now, please wait. This is something we'll need to discuss internally, and it'll take some time to go through it ourselves. There's so much bad code out there that we don't want to have a "recommended" book that has ultimately bad practices. I'm not as high up as @Starbuck5 , but I am pretty high up in the authority gradient, so I feel I can say something like this on the matter.

[Starbuck5]

Hey, I think this is neat! I spent a bit of time reviewing it.

I think it would work best linked in https://pyga.me/docs/index.html#tutorials or as a "third party resources" (or a better name) section at that level. We could also link Clear Code / DaFluffyPotato's latest tutorials using pygame-ce.

Starbuck book review

It's cool to see newer things like Window and FRect making it into a book like this. It's clear you've put a lot of effort into it, it seems to go over many foundational topics.

You're using a lot of Window positioning, I'm nervous that could fail on Wayland in Linux, which would raise a pygame.error and crash the program. This is on us to fix, we need to make sure the errors raised by some of these functions are filtered out if they're not actually fatal. But maybe for the book it would be better to not position as much, the default window position should do for most uses.

In the events section, it uses USEREVENT to to grab ids for custom events. It's preferred to use https://pyga.me/docs/ref/event.html#pygame.event.custom_type so that if using libraries that use pygame events everyone can share the space without fear of overlapping event types.

Instead of saying pygame.rect.Rect or pygame.surface.Surface, it should use pygame.Rect or pygame.Surface. From a documentation standpoint, pygame.rect and pygame.surface are implementation details (not that we would break compatibility for people using these names). But using them directly on pygame is preferred.

Various examples use Sysfont, SysFont(None) to get the default font, but the chapter on fonts uses match_font instead. Also, the font chapter says that the default font is a system font, it is actually shipped inside pygame-ce, so it is safe to use consistently when distributing games.

Lastly, there are a few spare usages of pygame.display.set_mode, which is totally fine to use but is not previously introduced in the book.

Minor stuff / typos:
Simple Direct Media Layer, Trade-off sections in glossary are in German
Pygame-ce was created in 2023, not 2020 (glossary entry on pygame-ce).
Definition of degree is wrong, it says there are 2pi degrees in a circle (glossary)
"Pygamee" (146)
"a hole" (14)
"Objekt" should be object (55)
"60ff" (86), "66ff" (105)
"Periodisches Event" (173)
"Blocking too many events and accidentally preventing essential input from being processed." (175) - "and" -> "can" ?

[adamsralf]

Thank you Very Much :-)
I truly appreciate comments like this and will take them into account when working on future version(s). Unfortunately, I do not have a dedicated review partner - apart from my students, whose “I still don’t get it” has become my personal benchmark.

[robotsnh]

@oddbookworm My bad, I'll try to focus on reporting more of my own bugs for now.

[robotsnh]

If I need to pull rank, I'm a member of this organization on Github and I'm the 2nd most prolific contributor to pygame-ce by commit count. I'm right.

@Starbuck5 my bad