Mingos: On September the 19th, the first ever Annual Roguelike Release Party took place. Its result: over a dozen interesting releases, including new games and updates to existing ones. A rather exotic ARRP release was Umbra, a C++ framework written by me and Jice. We’re here to have a small chat about Umbra and its connection to the roguelike world.
WHAT IS UMBRA?
Mingos: So, Jice, people have asked this question a few times in the past two weeks: What is Umbra? How would you define it?
Jice: Well… its long term goal is to be a roguelike framework built on top of libtcod. It’s currently only a chrysalis that proposes a clean code architecture (UmbraModules) and various generic utilities to handle logs, keyboard shortcuts, dynamic font detection and so on. It also makes you easily create a program in no time with a lot of built-in features like full screen switch, screenshots, game pause, advanced frame counter…
Mingos: Technicalities, technicalities – I say it’s a time saver. For me, Umbra is a framework that plainly takes programming to a higher level of abstraction. It takes care of the inner loop of any application and helps organise the application’s elements into separate parts. In other words: it makes software design simpler and makes the code easier to manage. So, in short: a high level framework/toolkit? Would that description be valid?
Jice: I wouldn’t say that. To me, high level means you handle game objects like Player, Dungeon, Item. Currently, Umbra only manages the deepest foundations of your game and we want to be sure it does it the best way before starting to build a higher level API.
Mingos: If, for instance, coding your own keyboard parsing routines is “low level”, then what would you call Umbra’s callbacks (a ready to use feature where all you do is create keybindings using ready-made tools and notify the engine of their existence)? Is that low level too? I will stick to my previous statement that Umbra takes programming to a higher level of abstraction – let’s just stress that this doesn’t make coding with Umbra high level.
Jice: Exactly.
WHAT ARE UMBRA’S RESPONSIBILITIES IN THE PROGRAM?
Mingos: Having talked about Umbra in general, what are Umbra’s responsibilities in the program? What does it take care of out of the box?
Jice: Umbra takes over the program’s main loop. This encourages you to use a better programming model by writing every game screen as a separate C++ class, but it’s up to you to decide how far you want to apply this model. You could as well put the whole game in a single module (which is not recommended) or do as I do in The Cave and have every independent UI component as a separate module (the message log, the status panel and so on). Once again: Umbra is not a restrictive framework. You can use it the way you like and two games using Umbra won’t look the same because Umbra has absolutely no impact on how the game looks like. Out of the box, Umbra takes care of anything not dependent on the game: fullscreen switch, screenshots, dynamic font switching and easy font customization for the end user (the player).
Mingos: Yes, this more or less sums it up. Umbra is the foudation of any application using libtcod, taking care of the innermost loop and the correct handling of all of the application’s elements. It also provides a way to log errors and some basic performance diagnostic tools. The developer focuses on the actual content, not the basic, low level functionalities.
WHAT IS A MODULE?
Jice: Ok, so basically, the developer only has to create the Umbra modules to feed the engine. But what are they exactly?
Mingos: I like to define UmbraModules as “separate logical elements of a program”. It’s really up to the developer to define a module: it can be as much as the entire game or as little as a single actor on the map. Neither of these extremes is recommended, of course. The developer needs to find a sane division and use it. The message log has its own separate logic and display, so it would intuitively be a module. Same applies, for instance, to the main map display, the menu or the inventory screen. Modules are generic enough to let the developer define them in any way. The only thing they provide are generic methods for updating their internal logic, displaying them on the screen and parsing mouse and keyboard input.
Jice: But modules are not limited to stuff displayed on screen. You don’t have to implement the render function. You can create modules that only implement the update function and act as optional gameplay rules. For example, imagine you code your game AI director as a module. It handles the monsters and items spawning. You can easily implement several totally different AI directors (for example for different dungeons or settings) and switch from one to another with Umbra’s activateModule/deactivateModule functions. You can have active quests handled as modules. There’s no limit to what a module can do.
Mingos: You can also go the other way round. The “Hello world” module only implements the render method, but not the update or keyboard/mouse parsing. In conjunction with inbuilt timeout support, I like to use such a combination to create the credits screen right before the main menu.
Jice: Oh that’s another interesting feature of Umbra: since modules are independent, you can easily switch their order or insert new ones. That means the links between game screens are no more hardcoded in every screen. All the links are defined through fallbacks in the initialization part of the code. Thus, adding a screen between the menu and the game is a piece of cake.
WHAT DOES THE DEVELOPER NEED TO CODE?
Mingos: Yeah, it is – just an extra argument to a method you’ll be using anyway. But then again, Umbra doesn’t exactly code the game for you, does it? Let’s talk about the developer’s responsibilities. What needs to be coded in order to make a program using Umbra?
Jice: Well your videos (http://www.youtube.com/watch?v=VRs38riiZw8, http://www.youtube.com/watch?v=nSpslD69qe0) are probably the best answer to this question. Basically, you create a module and a few lines of code to register and activate it, then you run Umbra, that’s it.
Mingos: Still, you need to write those “few lines of code”…
Jice: Yeah, Umbra is not a roguelike engine where you tweak a few config files and get your game. You still have to code the actual game.
Mingos: This is what I’m getting at. Even though the UmbraModule gives you a ready recipe, telling you where to insert your update code or your rendering code, you still need to write everything yourself. Sort of like adding your own ingredients to that recipe. The base classes, such as the map and the actors, the interactions between them, etc.: all this is absent in Umbra and needs to be coded. Umbra simply helps you organise all that so it doesn’t become a shapeless mass of unmaintainable code as the project becomes more and more complex.
WHAT ARE WIDGETS?
Jice: Ok but if modules can be anything and everything, what’s the meaning of a widget in Umbra?
Mingos: Well, modules are extremely abstract. Widgets are more defined and are oriented towards GUI functionality. As of Umbra 10.10, Widgets are a special class of modules that have a few extra features that let them behave like a window: they have support for mouse dragging, close and minimise buttons and a few GUI elements such as buttons and checkboxes. They aren’t documented in any way though, as they are going to be replaced by a more generic widget system. Since you’re the guy that’s devising that new system, why don’t you tell us a bit about it? How is it going to work? How is it going to be different from the current one?
Jice: The current widget system was an attempt to create a complete widget toolkit inside Umbra. An ASCII widget toolkit for roguelikes is a frequently asked for feature. But if we provide the complete toolkit, every game using it will have the same look, except if it comes with a very powerful, CSS-like skinning system. A shorter term goal is to leave the rendering part on the user side, but provide everything else. Event handling, drag and drop, scrolling, widget containers, everything that is a pain to code should be done by Umbra.
Mingos: So your idea is to convert widgets into containers that take care of the mouse input, but leave all rendering and updating to the developer? Isn’t that what the current system does?
Jice: No, the buttons and checkboxes have hardcoded rendering and the widget class is not generic enough to allow complex UI interactions like the ones I use in The Cave. This shall be improved soon.
THE FUTURE OF UMBRA
Mingos: Alright, that certainly sounds interesting. And how about other plans regarding Umbra development? Are there any features that are planned but aren’t yet present in the framework?
Jice: I think our current goal is rather to polish the existing features and make them as easy to use as possible rather than rush and add more features. Umbra’s current architecture must have its baptism of fire with real life projects (other than Deliquium Solis and The Cave, of course). Once it’s tried and tested, we’ll be able to expand it to that mythical roguelike framework :).
THE END
Mingos: OK, thanks for the chat, Jice. I think that answers the questions that have been asked over at Roguecentral forums. For all those interested in trying Umbra out, it’s available at http://umbrarumregnum.110mb.com/download/umbra. You can ask questions about it in its forum board: http://doryen.eptalys.net/forum/index.php?board=37.0
Jice: Hey, thanks to you and to Slash for hosting this!
Temple of The Roguelike 