Add a pyxel viewer

[jbdyn]

This PR adds a pelita viewer based on the retro game engine pyxel.

It shall have the same feature set as the Tk viewer and more:

• independent from OS (tested on Linux, Windows, Mac)
• walls (rounded)
• border (per side)
• food (per side)
• bots (per side, per role, rotating)
• header (score, team name, time, errors, kills, deaths, quit button)
• footer (control buttons, current turn, current round, selected tile)
• playback control with history (rewind, play/pause, forward, step, slower, faster)
• debug mode (grid, view range, move direction markers)
• configurable constructor parameters
• CLI integration
• own zmq controller
• globally switchable client-controlled tile overlays, supporting change of background-color, shapes, text

Things to discuss:

• Have a pyxres resource file with sprites or define sprites via Python API?
• Resolution okay?
• Design (sprites, colors, layout)?

[jbdyn]

Right now, it looks like this:

[jbdyn]

@Debilski could you have a look at the zmq related stuff in __init__ and _update?
I'm pretty sure my implementation could be improved here.

[Debilski]

Ah, nice. Now if only pyxel could have a high def output. :)

For zmq it kind of depends how that update loop works. Ideally, you do not want to call this unconditionally every fraction of a second as it will just eat CPU when idle. In the best case, pyxel comes with a mechanism to wake up the main loop from a different thread via a signal [*]. You’d need to have all the zmq stuff in the other thread then, and pass the messages to the main loop.

If pyxel can do asyncio, it might also be an option to asyncify the zmq calls.

If neither is possible, you probably want to increase the poll timout slightly when no more messages are incoming. Apart from that, I think for a viewer there is not so much to know about zmq. If it works, it works. It gets more interesting once you are trying to send stuff. :)

[*] This is possible for example in the test Qt6 viewer ( https://github.com/ASPP/pelita/pull/756/files#diff-5d901d396173bb6a2fb825d926ad8db0d366708fe769c45d45f7066b12adf137R44 ) although in this specific implementation it is still somewhat simplified.

[jbdyn]

I highly appreciate your explanation! I will check CPU usage then.

Now if only pyxel could have a high def output.

I guess you mean that the resolution is too low, that is, sprites and walls are too blocky?
We have two options here:

1. We enable the "high res" screen mode. This smooths out edges while keeping them sharp. pyxel comes with 3 modes: normal, high res and CRT. But that is somewhat cheating and does not look right for pelita. It might not be cheating in combination with the second option (32 pixels or above) and look appropriate.
2. We increase the resolution of the sprites. They are not limited to 16x16 pixels. That means more work on sprites (outside the shipped editor, maxing out at 16x16) and finding a bitmap font with resolution of 16x32 or 32x32 (at least a height of 32 pixels) or higher.

[Debilski]

I highly appreciate your explanation! I will check CPU usage then.

Now if only pyxel could have a high def output.

I guess you mean that the resolution is too low, that is, sprites and walls are too blocky?

I meant it half as a joke, because I understand that this is what pyxel does best.

But OTOH, if it doesn’t have a high resolution, the question is what makes it better/different from Tk. It kind of looks like that already on Linux (unfortunately in my opinion). (+ I really would like to have a high-res SVG canvas viewer that can be built from a few lines of Python and I feel that pyxel almost could be it)

[otizonaizit]

But OTOH, if it doesn’t have a high resolution, the question is what makes it better/different from Tk. It kind of looks like that already on Linux (unfortunately in my opinion). (+ I really would like to have a high-res SVG canvas viewer that can be built from a few lines of Python and I feel that pyxel almost could be it)

To me this is a big improvement from Tk:

• guaranteed consistent appearance on Linux, Windows, Mac and web viewer
• consistent platform independent scaling
• custom font with consistent scaling
• code which is easier to understand and maintain, being based on a game engine framework instead of a generic GUI platform

There are of course downsides too, here the ones concerning me the most:

• Tk comes with the standard library, so the code relies on a strict backward compatible policy: we haven't changed most of the Tk code since many years. This is a good thing, because we don't want to suddenly be forced to update the GUI code at every new release of pyxel
• pyxel is mostly a one man show, so if that man is gone, pyxel is gone
• it remains to be seen if the "debug" mode can be implemented in a useful way in pyxel: I am still not sure how much "high-res" we do indeed need to show grid and labels and overlays, etc...

From the aesthetic point of view, I like pyxel's retro look. It fits with the mock pacman idea of pelita. And it makes the GUI something recognizable immediately instead of something that seems to work but often fails in the little details. Pyxel looks like it got buttons, game controls, sprites and fonts right from the beginning, instead of the manual retro-fitting with have to do with Tk.

If the "debug" mode looks good I would be almost convinced to risk a move to pyxel. We don't have to throw away the Tk viewer, and if we keep it around indefinitely and keep on testing it once in a while, we may be able to switch back to it if pyxel dies a terrible death.

[otizonaizit]

@jbdyn : could you add to the list of features to be implemented something along the lines of

• globally switchable client-controlled tile overlays, supporting change of background-color, shapes, text

[jbdyn]

But OTOH, if it doesn’t have a high resolution, the question is what makes it better/different from Tk.

Pros of pyxel

• Fixed aspect ratio. Tk stretches the UI and thereby the maze with the dimensions of the window, which looks weird on my tiling window manager quickly.
• Fixed look, independent from OS. No Fix dark mode colours #882.
• Built-in screenshot and screencast. Nice for sharing snapshots and recording tournaments.
• Possibility to add sound cross-platform. Not so easy in Tk as far as I can tell. Pelita could have its own tracks and sound effects. Might be nice for tournaments.

Personal Pros of pyxel

• A separate Python package. I ran into an issue with uv where it probably used one of its managed Pythons (3.12.9), colliding with the - only system-wide available - Tk shipped with my system's Python (3.13.3). Tk threw an error and no game could be started until I also used 3.13.3 in my environment.
• Not as complex as Tk. I very much like that the README.md of pyxel holds the major part of its documentation.
• Limited UI. Harder to layout since every addition is expensive in terms of screen real estate, but looks cleaner in the end.

Cons of pyxel

• Only supports .bdf bitmap fonts. Not easy to find and conversions from .ttf or .otf are neither trivial nor garantueed to work as far as I tried.
• No helpers for UI design. I need to write my own for proper alignment of text, buttons and other widgets.

I really would like to have a high-res SVG canvas viewer that can be built from a few lines of Python

My impression is that SVG with Python is somewhat difficult and limited, unfortunately.
There are a number of projects, but most of them were not updated for years and are limited to either writing SVGs, reading SVGs, maybe a combination of both. drawsvg 2 seems to be the one with the most features, but here you need to add key frames in advance to play it, which does not help for Pelita.

So a web viewer within a browser with JavaScript/TypeScript would be the natural habitat for displaying and animating/changing SVG on the fly.
Has this been tried before?

[jbdyn]

@otizonaizit Whoops, didn't know you also answered. 😅

[jbdyn]

• globally switchable client-controlled tile overlays, supporting change of background-color, shapes, text

@otizonaizit Are you thinking of chamber tile visualization?

[otizonaizit]

• globally switchable client-controlled tile overlays, supporting change of background-color, shapes, text

@otizonaizit Are you thinking of chamber tile visualization?

well, that was one use of that. But I am thinking to a feature that gets asked over and over again: a way for the client to mark tiles, for example to display a heatmap. This should be supported during development and of course be ignored when playing a standard game.

[otizonaizit]

So a web viewer within a browser with JavaScript/TypeScript would be the natural habitat for displaying and animating/changing SVG on the fly. Has this been tried before?

as far as I know @Debilski is having this already in his own web-based tournament repo somewhere. On the other hand I am very much against having a web-based client as the default GUI. Very much against. Pelita should be educational grade code, we want students to get excited about it and we want them to be able to contribute code. Ergo, it must be written in Python and runnable from the CLI. The web-client would need constant care and a paid developer to be maintained properly. And we would start having browser compatibility issues from day 1.

[Debilski]

To me this is a big improvement from Tk:

• guaranteed consistent appearance on Linux, Windows, Mac and web viewer
• consistent platform independent scaling
• custom font with consistent scaling

Sure but in a pixel font. We could have consistent appearance on Tk too (minus some anti-aliasing on Linux/Windows) if we put all the buttons into the canvas as well. I don’t see the different button designs as an absolute minus though.

• code which is easier to understand and maintain, being based on a game engine framework instead of a generic GUI platform

Not sure which ‘game engine framework’ features are needed or used other than having a canvas. Structurally, it looks pretty similar to the Tk code right now.

(Likely that this will also become messier once more features are implemented.)

There are of course downsides too, here the ones concerning me the most:

• Tk comes with the standard library, so the code relies on a strict backward compatible policy: we haven't changed most of the Tk code since many years. This is a good thing, because we don't want to suddenly be forced to update the GUI code at every new release of pyxel
• pyxel is mostly a one man show, so if that man is gone, pyxel is gone
• it remains to be seen if the "debug" mode can be implemented in a useful way in pyxel: I am still not sure how much "high-res" we do indeed need to show grid and labels and overlays, etc...

Even bot.say might be a problem …

From the aesthetic point of view, I like pyxel's retro look. It fits with the mock pacman idea of pelita. And it makes the GUI something recognizable immediately

My strongest opinion here: I think it looks cute and fun as a gimmick but it looks like a generic retro Pacman clone of which there are probably hundreds and not at all recognisable as Pelita. Not really a fan of it as the default UI.

instead of something that seems to work but often fails in the little details.

I might even agree but I am not sure what you mean exactly.

Pyxel looks like it got buttons, game controls, sprites and fonts right from the beginning, instead of the manual retro-fitting with have to do with Tk.

If the "debug" mode looks good I would be almost convinced to risk a move to pyxel. We don't have to throw away the Tk viewer, and if we keep it around indefinitely and keep on testing it once in a while, we may be able to switch back to it if pyxel dies a terrible death.

Fixed aspect ratio. Tk stretches the UI and thereby the maze with the dimensions of the window, which looks weird on my tiling window manager quickly.

You should have opened an issue here, I think no-one really tested it with tiling WMs that willingly ignore our --geometry setting ;)

But it is solvable in Tk. A small problem is that you have to add the header and footer part to the aspect ratio. (And you have to take into consideration absurdly ‘deformed’ mazes – they shouldn’t make the window manager unmanageable, so it is still a bit messy to fine-tune.)

Fixed look, independent from OS. No #882.

Built-in screenshot and screencast. Nice for sharing snapshots and recording tournaments.

That’s nice of course. (Not sure if needed anymore; we can now export the tournament – or at least all matches – to a website https://aspp.uber.space/tournament.html and don’t even have to carry the overhead of having to include videos anymore.)

Possibility to add sound cross-platform. Not so easy in Tk as far as I can tell. Pelita could have its own tracks and sound effects. Might be nice for tournaments.

Not having sound is a plus here maybe :)

Only supports .bdf bitmap fonts. Not easy to find and conversions from .ttf or .otf are neither trivial nor garantueed to work as far as I tried.

If we only have a 7x7 bitmap font (means we can fit four letters in a 16x16 cell) then there aren’t so many different designs possible anyway I guess.

No helpers for UI design. I need to write my own for proper alignment of text, buttons and other widgets.

Hmm, ok, but then we need to write the same wrappers for things as we would in Tk. Just for different things.

So a web viewer within a browser with JavaScript/TypeScript would be the natural habitat for displaying and animating/changing SVG on the fly. Has this been tried before?
as far as I know @Debilski is having this already in his own web-based tournament repo somewhere. On the other hand I am very much against having a web-based client as the default GUI. Very much against. Pelita should be educational grade code, we want students to get excited about it and we want them to be able to contribute code. Ergo, it must be written in Python and runnable from the CLI. The web-client would need constant care and a paid developer to be maintained properly. And we would start having browser compatibility issues from day 1.

I’d imagine we’d have less browser compat issues than we currently have issues with wayland/x11 and wrongly linked Python UI libraries. [*]

The main points against a browser-based UI as a default are:

• Browser-based code needs a web server that would need to be transparently started in the background.
• Ideally, you want to have an individual window per Pelita run. This window should not look like a browser.
• You can do all the development in Python (in principle), that is not really the issue (whether it makes sense to do so is a different question). But I also would say anyone would be capable of making small changes in Typescript code. That isn't the point though: The tricky problem is building it. (Getting a correct dev environment is of course also a tricky problem in Python, but luckily we can take it for granted.)

So yes, this is likely not happening.

[*] I also looked into https://flet.dev as an alternative to Tk but unfortunately I immediately ran into this on Linux flet-dev/flet#2823 It remains to be seen if pyxel is more stable here.