[Kde-games-devel] My review of Gluon

[Stefan Majewsky]

Hi,

[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.