This weekend I started thinking of how much I would like to write a modern-world survival game. “You wake up naked somewhere in the world, with no recollection of your past. Survive.”
I never complete such projects, but I usually learn a lot during them, so I decided to go ahead and attempt to use Grit again. I had attempted it in the past, but I had given up after being unable to change the build system to support shared ICU libraries in a reasonable span of time. Back then I ended up trying to write a GTA2-like game from scratch with Qt3D, on which I gave up after some months; it lasted longer than usual, though. User Experience
Since I have no idea how to use Grit, I start with the documentation. The ‘Grit Book’. The book starts with ‘(TODO: This book is incomplete, but is posted online in the hope that its existing content be useful.)’. So I read the whole book, and when I was done, I still had no idea of how to start a new project using Grit. It is incomplete indeed, and the fact that it mentions it in the beginning only makes me feel more stupid for reading it anyway.
I am not afraid of building stuff from source, so the fact that the only installation instructions in the book are in the section about compiling from sources was OK.
I did have trouble with the ICU libraries. The same had happened to me the first time I had tried to compile Grit
. I solved it by changing the Makefile paths, and I opened a pull request about it
, but I really think that the build system should use the ICU shared libraries by default, and provide an option to use the static libraries instead. I also think that it should be able to find the static ICU libraries even if they are not in a specific path.
What I did not find OK was that it turns out that the engine can be installed from prebuilt binaries, and the only part of the documentation that explains that to you is the section about compiling stuff from sources. I think that the most straightforward installation instructions should be in the first section of the documentation, right after the introduction.
After successfully compiling the engine, I started to check out the sources to try to understand how to go about creating my own game from scratch, since the documentation did not explain.
Based on the text of the compilation instructions section, I thought that the engine was comprised of the actual engine executable and some base resources (media). But after reading the sources, as far as I can tell, the media/ folder is just an example game. I think the documentation should explain this clearly, and not tell you that you will not be able to do much without the media/ folder. Instead, after providing straightforward installation instructions (for the engine executable), it should explain how you can download this example game from Subversion in order to test the engine. So that it is clear that, to do your own thing, you have to write your own media/ folder.
I’ve managed to create what I would call a Hello World game using Grit (it prints Hello World on the command line), and based on my experience so far I think that the documentation should clearly state the following (assuming I got it right):
- You must run the Grit executable with the root folder of your game (media/ in the case of the example game) as working directory, because resource paths will be resolved relative to it.
- Your game must be written in Lua (eventually the documentation should ellaborate, obviously). By default Grit expects the entry point of your game to be at /system/init.lua, but you can use the GRIT_INIT environment variable to define a different entry point (e.g.
I decided to try and perform these documentation changes on Grit myself, and keep completing the documentation as I learn myself to use Grit based on the game example, so that whoever comes after me has it a bit easier.
First I submitted a pull request to change the Git URL on the README file, which was pointing to sparkprime’s Git account, but I read a message from him in the forums stating that he had created a Github project to replace that.
Then I tried to extend the Fundamentals section of the documentation with two sections, one that explains how to install the engine executable from binaries, and one that explains how you may download the example game from Subversion.
First I needed to locate the Fundamentals section in the sources. And I found it.
[gallaecio@castelao grit_book]$ grep "This book is incomplete" * -FIR
xml/intro.xml: <todo>This book is incomplete, but is posted online in the hope that
XML is no documentation format, and the contents did not look like DocBook (the only XML-based documentation format I am familiar with), but I tried to perform the changes based on existing content, mimicking the syntax used in other parts of the documentation.
At some point I wanted to use bold font for some words (Windows, 64-bit Linux). <strong> did not work. <b> did not work. I ended up reading the custom Python scripts to try and find out what documentation format this was. It was dissapointing to find out that it was a custom documentation format, and that I would have to code my own syntax for whatever was not implemented.
Since I did not want to waste more time figuring out how to code my own XML tags, specially since it looked like I would have to make them export to HTML, Markdown and PDF, I used the existing tag for italics instead of using bold, and I used a regular paragraph where I would have preferred to write an indented note.
So, I implemented my changes in the sources, and I proceeded to run
to see the results. It failed because the Python scripts did not support the latest Pygments version, which is the one I have installed, and I was also missing two required command-line tools. I fixed the Pygments issue, and made some improvements to the scripts which I submitted on another pull request
, and I went on.
Before generating the documentation, Git reported the following modified files:
Afterwards, it reported these:
This is how I found out that there were autogenerated files on the repository. It is something I completely dislike unless it is justified, and it rarely is; I do not think it is justified in this case. But it is rarely a real problem, it is usually just irritating for me.
The real problem was the root README.md. Not only was it autogenerated from the XML, which meant that my first pull request to fix its Git URL was useless. It was generated from the Compilation Instructions section. The README, the page that should serve as an introduction to all aspects of a project, is autogenerated from the last section of the documentation.
I included the changes in my pull request ayway, but Spark did well in complaining about it, and I simply reverted my changes to the documentation content, and left the pull request only with minor improvements to the documentation generation scripts.Closing Notes
All in all, it has been a rather frustrating experience. I outline some specific issues here, but in general the first experience as a user or a contributor felt really awful. Which is in constrast with the actual engine, which I finally managed to run, and it looks awesome.
So, I definitely want to do something with Grit, but I think you should really work on making the project more accessible both to users and contributors. The switch to Github has been an awesome step in that direction, but I think there is still a lot to do.
Let me also throw in some general ideas:
- Switch to CMake as build system. It is cross-platform, it allows for graceful handling of dependency checks, and it is extremely popular among C++ open source projects.
- Switch to a proper documentation system, such as Sphinx; do not do your own thing. And you need to have guides and reference documentation for both users and contributors; do not try to keep them in separate documentation resources, just use different sections of the documentation for each.
- Revamp the website. Its design feels really dated, and some of the content feels outdated as well. Compare its design to that of the websites of 0 A.D. or SuperTuxKart, for example.