atom feed1 message in org.kde.kde-games-devel[Kde-games-devel] My review of Gluon
FromSent OnAttachments
Stefan MajewskyAug 22, 2010 12:49 pm 
Subject:[Kde-games-devel] My review of Gluon
From:Stefan Majewsky (
Date:Aug 22, 2010 12:49:49 pm


[cross-post to kde-games-devel and gluon; WARNING: I'm not subscribed on gluon]

people keep telling me that Gluon is the future of FOSS gaming, gaming communities and stuff, and that I need to consider it for new games and stuff. I finally took the time for a first look at the Gluon libraries. openSUSE has Gluon packages (even with some example games), but it requires me to change permissions in my /dev/. At least, this is what the website tells me. To me, this smells like a severe design issue: I have no joystick and stuff, so you would just need to get mouse events from Qt (or X at most). At least, this has worked perfectly for my needs the last years.

I did not look at Gluon Creator, because, although it surely is a very impressive tool, I highly doubt that it can be useful to create games that integrate with KDE to the highst possible extent. This is my primary concern, after all. I want to take our KDE games to the next level (technology-wise) without abandoning what we currently have, like our SVG theming and KGameRenderer, or the ability to include external libraries (as used e.g. by KSirk).

So let's have a look at the libraries. The website has no documentation, but the source tree comes with a Doxyfile¹. After some first orientation, I am at GluonCore::GluonObject, which sounds fairly central. Quite the right place to examine the quality of the API.

I won't go over coding style (e.g. Java-style getters like "getStringFromProperty" vs. Qt-style getters like "fullyQualifiedName"). What really scares me is stuff like: (quoting from GluonObject::toGDL) "Do we need the parsing code in the GluonObject? Or can we separate this into a parser class? We need to separate this into a parser class, imo. Can wait until post- alpha though."

Seriously: You want people to start to use your libraries, yet defer finalization of core API until the beta cycle? I expect an API to be frozen (or at least source-compatible) by the first beta. Wait, there is also a GluonCore::GDLHandler class. So if this API has been finalized, please update the documentation. Remember, you want me to use this API, and Qt and KDE have set the bar high when it comes to APIDOX.

While we are at GDLHandler, let's have a look at the Gluon Definition Language. There is a syntax sample in the documentation:

{ ClassName(ObjectName) PropertyName DataTypeName(Value) PropertyName2 DataTypeName2(Value2) { ClassName(ObjectName) PropertyName DataTypeName(Value) } }

Uh, WTF? You include the data type name in there? Ever heard of context-based data type coercion (i.e. implicit conversion of the GDL literal to the value, based on the data type of the property)? Now that explains why it takes you over 200 LOC to implement GluonObject::setPropertyFromString and GluonObject::getStringFromProperty. And that is only a part of the serialization code. Compare to Kolf 2, which does its whole object serialization and deserialization in 65 LOC. And it does not need to store the data types anywhere. The funnier parts of this code use KConfig, and this is what I mean by KDE integration: reusing algorithms that have been proven for years, in thousands of applications.

Continuing on the code reuse topic, it is interesting how you do not use QML, which was in the works long before the GDL, and will most probably be the future of Qt user interface design (i.e. there will be many people accustomed to this language). Has this possibility been evaluated? QDeclarativeItem and subclasses are surely tailored towards the needs of the QGraphicsView-derived QDeclarativeView, but the underlying QDeclarativeEngine and QDeclarativeContext just deal with QObjects, i.e. nearly exactly what you do, too.

Then there are those points in the code which indicate that you have never used the API to build games with this API outside Gluon Creator. One example is GluonObjectFactory::instantiateObjectByName³, which breaks if you try to instantiate a class which is not in a namespace (a very common scenario in hand-coded applications). Also, it would be quite fruitful to run krazy against the code. A "const float&" return value (GluonGraphics::Item::alpha) is just stupid.

I need to come back from code quality to the fundamental issues again. One of these fundamental issues is that GluonGraphics is mostly fixed to OpenGL. While OpenGL is a good choice for many games, I do want to be able to fall back to a software renderer on devices with bad OpenGL support. With plain Qt widgets (or QGV or QML), I have the possibility to change between different 2D graphics systems⁴ without even re-compiling.

So my fundamental issues with Gluon, after this one-hour review, are: 1. its partly bad code quality 2. its partly bad documentation quality 3. its partly abstruse API design 4. my impression that usage of existing Qt-style libraries above QtGui (like QML, or also KConfig) has not even been evaluated

Especially the last point is interesting to me because I feel like I am always accused of this when I am not considering Gluon to be ready for my needs. This review strengthens this opinion. Please take this text as an incomplete collection of points on which you need to improve if you want to be taken seriously by game developers who are too much limited by Gluon Creator. Regardless of that, your work on Gluon Creator is awesome. Continue on this way.

Greetings Stefan

¹ The Doxyfile is actually broken: "INPUT = /home/leinir/gluon-helper/gluon". ² The code is at trunk/playground/games/kolf2/base, lines 109-161 in managedobjectstate.cpp and lines 31-57 in utils-bytearraycodec.cpp. ³ This method could be much faster if you used m_objectTypes.find() instead of m_objectTypes.keys().indexOf(), esp. because you do not need to construct the keys list in every call, and because you can use the iterator returned by find() to obtain the value in the next line. ⁴ One of these graphics systems is 2D OpenGL, though this engine is not stable, but it is improving at an amazing pace.