bear_hug: games in ASCII art in Python3.6 +

For my games in ASCII art, I wrote the bear_hug library with an event queue, a collection of widgets, ECS support, and other useful little things. In this article we will see how to use it to make a minimal working game.





Under the hood of bear_hug is bearlibterminal , an SDL library for creating a pseudo-console window. That is, in pure TTY, like some ncurses, it will not work. But then the picture is the same on Linux, on Windows, and does not depend on the settings of the user terminal. This is important, especially for games, because when you change the font ASCII-art, God may well turn into what:





The same drawing in its original form and after copy-paste to different programs



Of course, the library was written for relatively large-scale projects. But, in order not to be distracted by game design and architecture, in this article we will create something simple. A one-night project, in which there is something to show the basic functions of the library. Namely - a simplified clone of those same tanks with Dandy (they are also Battle City). There will be a player’s tank, enemy tanks, destructible walls, sound and scoring. But the main menu, levels and selected bonuses will not be. Not because it would be impossible to add them, but because this project is nothing more than a Halloworld.





A gameover will be, but there will be no victory. Because life is pain.



All material used in the article is on the github ; the library itself is also on PyPI (under the MIT license).



First of all, we need assets. To draw ASCII art, I use REXpaint from Josh Ge (aka Kyzrati), the developer of the science fiction bagel Cogmind . The editor is free, although not open source; the official version is only for Windows, but everything works fine under wine. The interface is quite clear and convenient:







We save in the local binary format .xp and copy from /path/to/rexpaint/images



to the folder with the future game. In principle, loading images from .txt files is also supported, but it is obviously impossible to save the colors of individual characters in a text file. And editing ASCII art in a notebook is not convenient for me personally. In order not to hardcode the coordinates and size of each element, this data is stored in a separate JSON file:





Sounds under free licenses are downloaded from the Internet. So far, only .wav is supported. That's all with assets, you can start coding. First of all, you need to initialize the terminal and the event queue.





The terminal is the actual window of the game. You can place widgets on it, and it throws input events as necessary. As keys when creating a terminal, you can use all the terminal options bearlibterminal ; in this case, we set the font, window size (in characters), window title, and input methods of interest to us.



As for the event queue, it has a very simple interface: dispatcher.add_event (event) adds the event to the queue, and dispatcher.register_listener (listener, event_types) allows you to subscribe to it. A signer (for example, a widget or component) must have an on_event callback, which takes an event as a single argument and either returns nothing or returns another event or set of events. The event itself consists of type and value; the type here is not in the sense of str or int, but in the sense of “variety”, for example, 'key_down' or 'tick'. The queue accepts only events of types known to it (built-in or created by the user) and sends them to on_event all those who subscribe to this type. It does not check the values ​​in any way, but there are conventions within the library about what is a valid value for each type of event.



First, we queue a couple of Listeners. This is the base class for objects that can subscribe to events, but are not widgets or components. In principle, it is not necessary to use it, as long as the signatory had the on_event method.





A complete list of built-in event types is in the documentation . It is easy to notice that there are events for the creation and destruction of entities, but not for damage. Since we will have objects that do not fall apart from one shot (the player’s walls and tank), we will create it:





We agree that, as a value, this event will have a tuple from the ID of the entity that suffered the damage, and the value of the damage. LoggingListener is just a debugging tool that prints all received events wherever they say, in this case in stderr. In this case, I wanted to make sure that the damage passes correctly, and that the sound is requested always when it should.



With Listeners for now, you can add the first widget. We have this ECSLayout class playing field. This is such a Layout, which can put widgets on entities and move them in response to ecs_move events, and at the same time considers collisions. Like most widgets, it has two required arguments: a nested list of characters (possibly empty - space or None) and a nested list of colors for each character. Named colors are accepted as colors, RGB in the format `0xAARRGGBB` (or` 0xARGB`, `0xRGB`,` 0xRRGGBB`) and in the format '#fff'. The sizes of both lists must match; otherwise, an exception is thrown.





Since we now have what to place in-game objects on, we can start creating entities. All code of entities and components is moved to a separate file. The simplest of them is a destructible brick wall. She knows how to be in a certain place, display her widget, serve as an object of collision and receive damage. After enough damage, the wall disappears.





First of all, the entity object itself is created. It contains only a name (which must be unique) and a set of components. They can either be transferred all at once upon creation, or, as here, added one at a time. Then all the necessary components are created. As a widget, SwitchWidget is used, which contains several drawings of the same size and can change them by command. By the way, drawings are loaded from the atlas when creating a widget. And finally, the announcement of the creation of the entity and the order to draw it on the necessary coordinates go into the queue.



Of the non-built-in components, there is only health. I created the base class “Health component” and inherited from it the “Health component changing widget” (to show the wall intact and at several stages of destruction).





When creating a component, the 'name' key is passed to super () .__ init__. When a component is added to an entity, under the name from this key, it will be added to the __dict__ of the entity and can be accessed through entity_object.health. In addition to the convenience of the interface, this approach is good because it prohibits the issuance of entities of several homogeneous components. And the fact that it is hardcoded inside the component does not allow you to mistakenly insert, for example, the WidgetComponent into the slot of the health component. Immediately upon creation, the component subscribes to the event classes of interest to it, in this case ac_damage. Having received such an event, the on_event method will check whether it’s about its owner for an hour. If so, he will subtract the desired value from the hit points and pull the callback to change health, the base class is abstract. There is also the __repr__ method, which is used for serialization in JSON (for example, for saving). It is not necessary to add it, but all built-in components and most built-in widgets have it.



Inheriting from the underlying health component of VisualDamageHealthComponent overrides the callback on health change:





While the health is above 0, he asks the component responsible for the widget to draw the wall in the desired state. Here, the call described above is used through the attribute of the entity object. Once the hitpoints are over, the component responsible for the correct destruction of the entity and all components will be called in the same way.



For other entities, everything is similar, only the set of components is different. Tanks are added with controllers (input for the player, AI for opponents) and rotating widgets, for shells - a collision component that causes damage to those they hit. I will not analyze each of them, because it is bulky and rather trivial; look only at the projectile collider. It has a collided_into method, called when the host entity crashed into something:





To make sure that it is really possible to get a victim (which may be wrong for, for example, background elements), the projectile uses EntityTracker (). This is a singleton that tracks all created and destroyed entities; through it, you can get an entity object by name and do something with its components. In this case, it is verified that entity.collision (the victim collision handler) exists at all.



Now in the main file of the game, we simply call all the necessary functions for creating entities:





Point and hitpoint counters are not entities and are not on the battlefield. Therefore, they are not added to ECSLayout, but directly to the terminal to the right of the map. The corresponding widgets inherit from Label (text output widget) and have an on_event method to find out what interests them. Unlike Layout, the terminal does not automatically update widgets every tick, so after changing the text, the widgets tell him to do this:





The enemy generator and the object responsible for the output of “GAME OVER” are not displayed at all, so they inherit from Listener. The principle is the same: objects listen to the queue, wait for the right moment, and then create an entity or widget.





Now we have created everything we need, and we can start the game.





Widgets are added to the screen only after it starts. Entities could be added to the map earlier - creation events (in which the whole entity is stored, including the widget) are simply stored in the queue and resolved at the first tick. But the terminal can add widgets only after a window has been successfully created for it.



At this point, we have a working prototype, you can issue in Early Access for twenty bucks add features and polish the gameplay. But this is already beyond the scope of halloworld, and hence the article. I’ll just add that a build independent of system python can be built using pyinstaller .