Game Engine Forum - Grit Open Source Streaming Game Engine
Site Header
It is currently Fri Apr 28, 2017 5:57 pm

All times are UTC




Post new topic Reply to topic  [ 11 posts ] 
Author Message
 Post subject: Awful first user and contributor experience
PostPosted: Sat Jan 07, 2017 12:42 pm 
Offline
Newbie

Joined: Fri Dec 11, 2015 2:55 pm
Posts: 13
Introduction

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.
    Code:
    GRIT_ENV=/main.lua grit
    ).

Contributor Experience

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.

Code:
[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
Code:
generate_doc.sh
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:
Code:
        modified:   xml/intro.xml
        modified:   xml/misc.xml


Afterwards, it reported these:

Code:
        modified:   ../../../README.md
        modified:   html/pygments.css
        modified:   md/README.md
        modified:   xml/intro.xml
        modified:   xml/misc.xml


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.


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Thu Jan 12, 2017 3:13 am 
Offline
Newbie
User avatar

Joined: Fri Mar 21, 2014 12:25 am
Posts: 112
Location: Rio Grande do Sul
Grit is mostly just a game engine, not an entire framework.

In common sense, most people probably think a game engine is composed by all necessary tools, or a system developed to end users of the finite list of possibilities in a pre dictated way. That's what most famous engines do, they create a bunch of tools to facilitate the most as possible the developers effort to build their games, in a pre defined way.

Grit may say you should make your game using Lua programming language, and it is mostly focused on this idea, but you actually can build your entire game using just pure c++ if you want to.

The cool thing about a game engine that uses Lua is that it unconsciously makes it a very versatile tool for game developers, even if you don't want to use it.
You have the core functionaties such as render, input system, physics system .. all organized in a way that you can create your own way to build your games. There is no "click here and create a project folder", "click here to create a new game mission", "add files to this specific folder so it can be used as specific and finite tasks", but you decide how exactly the whole System works: you have functions to the input system, functions to add physics objects, functions to add sound objects, functions to add 3d objects on your scene and a function to render your frame on a specific position and rotation (camera), and all Other necessary generic functions that any game needs, that's all you need to build a game, the rest is only limited by Lua, that is, you can do almost anything you want in the way you want.

The /media folder is actually a kind of example on how to build your game, not just a "demo" but all sorts of examples on user interface, input systems, character / vehicle controllers, editor, example maps and so on .. , It is something to help you to build your game the easy way as possible, like using the editor to build your object positioning list (map) or other tools that may be added later, where you decide if you want to use or not.

I agree that Grit forum/site should be updated to newest design (like ogre3d.org) and also have more media stuff, like screenshots, "games created with Grit" page, facebook page..


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Fri Jan 20, 2017 11:30 am 
Offline
Supreme Tyrant of All
Supreme Tyrant of All
User avatar

Joined: Sat Mar 27, 2010 1:13 pm
Posts: 768
Thanks for taking the time to write such detailed feedback, it is really appreciated. And also thanks for your PRs for updating pygments and such. I would like to help you make your game

Your criticism comes into a few categories:

1) Documentation

This is indeed sorely lacking. In some places it's not lacking but just disorganised. We have the old website, an old wiki, various README.md and the book. The problem with documentation is that unless you understand the system, you cannot write it. So necessarily the ones who understand the system have to take time from doing other tasks (like fixing / extending it) to document it. That is always frustrating, but necessary. It would help to have a concrete list of items that were missing. I'll try to do that now:

* How to install the prebuilt binaries
* Explain the role of the media/ directory and what's in it.
* How to make a simple "hello world" game

This isn't a plan for fixing the documentation, more like a list of requirements. The actual plan is going to have to consist of changes across a whole range of different places, like the website, maybe porting docs from the old wiki, README.md files, the book, and generated API docs. Part of the problem is probably that we have too many places where documentation lives, but that can be fixed.

There is another angle on documentation and that's that until you have a lot of users, it doesn't really pay off. It's more effective to for users to ask questions and community members to answer. This is what we have effectively been doing for the last n years and it has allowed contributors to get up to speed and do things. But it means spending time on IRC and there are issues with timezones and such. So there are pros/cons and it's also possible to have a certain base level of documentation and then have Q/A on top of that.

It used to be more clear that the SVN contained prebuilt executables and that you can just download the svn and start running the engine in most cases. However since the switch to github I think people are coming in through that front door now, as opposed to via http://www.gritengine.com/download. So maybe README.md is the solution to that.

Speaking of the website, it is very old and it's a long term objective to replace it all with some static gh-pages. Even the forums I think are better replaced with a google groups mailing list. This avoids the moderator overhead and so on.

How did you find Grit, what documentation did you find, and in what order?

2) Build system

The ICU issue should be fixed, that was an oversight. I did evaluate CMake about a year ago but found some problems with it that I can't remember now, something to do with incremental rebuilds and/or precompiled headers. The current build system consists of a basic set of VC project files and a set of custom GNU make files. It's really simple and supports everything we need. Anything system-specific is dynamically identified with pkg-config.

The benefit systems like CMake bring is to be able to generate both VC and Makefiles from the same script but with only 2x duplication (and significant differences between the two cases because of D3D etc) it's not actually that much benefit.

There is also Bazel, but not sure that can build using msvc.

3) Prebuilt docs

There isn't really any reason to have pre-built docs in git. They'd be better off built into the media directory (or maybe just to gh-pages).

I understand your frustration with seeing a new documentation format, but when I evaluated a bunch of different systems several years ago when I wrote the first version of the book, none of them did what I wanted, which was to have clear paragraphs of text separated by newlines and marked up with high level semantic formatting information which is then generated into a variety of sources with automatic indexes and so on. That is why there is no bold tag, because that's too low level. There is <emph> for emphasis, and a <def> which is rendered in bold in HTML but is really intended for generating indexes. These higher level things are more like Latex.

The problem with using existing systems is they never have exactly the featureset you want. I don't think a thousand lines of python is a big deal and it means we're fully unconstrained. It does have no documentation though. I suppose if it had a one pager explaining the available XML tags and the structure of the source code, you would not have been so frustrated. I will extend your rst file to add that.

I don't think we really need any target formats beyond HTML at the moment. It was Augusto who added them so I'll let him defend that decision :)


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Sun Jan 29, 2017 8:27 pm 
Offline
Newbie

Joined: Tue Oct 09, 2012 11:14 pm
Posts: 46
Hi,
i do not want to speak higher than my rank, but have you seen those pages, for kodi :

http://kodi.wiki/view/Development
http://forum.kodi.tv/forumdisplay.php?fid=93
https://github.com/xbmc/xbmc

somehow, i think that they look nice and appealing.

Also, i was wondering if there is someone that would explain me this:
When you give money to a opensource project, who gets it, who is in charge of making decision for that money

thank you!
bye!


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Mon Jan 30, 2017 6:33 am 
Offline
Newbie

Joined: Fri Dec 11, 2015 2:55 pm
Posts: 13
> When you give money to a opensource project, who gets it, who is in charge of making decision for that money

In small projects, that’s usually the project leader. In medium-size projects, there may be a person other than the leader taking care of the finances. In big projects, there is usually an organization that takes responsability of handling the money.


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Mon Jan 30, 2017 9:48 pm 
Offline
Newbie

Joined: Tue Oct 09, 2012 11:14 pm
Posts: 46
Thank you for your answer Gallaecio, so ,the project leader can do anything he wants with the money, and there is no legal obligation for him to release the comptability of his project to the peoples who gave him that money.


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Tue Jan 31, 2017 6:19 am 
Offline
Newbie

Joined: Fri Dec 11, 2015 2:55 pm
Posts: 13
If you are really interested you should probably talk to a lawer, but no, I believe there is no legar obligation to be open about the finances unless you signed some kind of contract (and then it would probably not be a donation, but some kind of payment).

When you donate, you usually do so to people or organizations that you trust to some level. If a person or project is not currently open about its finances (to everyone, not just to the current donors), it may not be that wise to donate to them. If they are already open about their finances, it is unlikely that they will stop doing so for just your donation.

If we are talking about free, open source software, if the development team is made of a few people, you can usually trust that they are going to keep themselves in check regarding the money. If it is one person, that person may take the donated money as some kind of salary, in which case that person will obviously not publicly discuss what he used the money for; and I think that is fine as long as that person does not promise to use the money for something else when you donate.

In free software, I don’t recall any case where donated money was used for things other than what was promised when it was donated, and when that happens it is usually for a good reason. For example, 0 A.D. had a fundraiser to pay a developer for full-time dedication to the project, and they did not ues the money for that because they could not find a suitable candidate; I donated quite some money during that fundraiser and I do not regret doing so.


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Tue Jan 31, 2017 6:01 pm 
Offline
Supreme Tyrant of All
Supreme Tyrant of All
User avatar

Joined: Sat Mar 27, 2010 1:13 pm
Posts: 768
The "right" thing to do in order to take donations would probably be to set up some sort of charitable foundation. I suppose in that case there would be some legal reporting requirement and that would provide at least some public information.

I'm not sure money helps though, what we need is hands on the job (mine in particular) :)


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Tue Jan 31, 2017 9:00 pm 
Offline
Newbie

Joined: Tue Oct 09, 2012 11:14 pm
Posts: 46
Thank you, Gallaecio and Spark for your greats answers, like i always says, the human mind and life work in mysterious ways. Then, how about the possibility to hire a developer that would get paid (i do not know actuals quotes for a developer's salary) 3000.00$ us (i am just throwing numbers in randoms) , when the job is done, but with a first payment of 1000,00$ us to get him started, the other part , 3000,00$ us, when the job is done. I wonder if a developer would accept those conditions?. The job migth be to implement netcode in grit, or the job mitgh be to create 2 scripts (1 for 3DS Max and 1 for Blender) that would convert a avatar created with MakeHuman
http://www.makehuman.org/ into a avatar playable in grit, (just an idea). Hey, i have a humongous respect and admiration and gratitude for those working to make grit, Unfortunatly, i kinda feel that ritgh now , it is to soon to hire such a developer, beside , those that i know can develop in english, but speak in french,wich bring me to suggest a more multi-language approach for grit , at least adding french and the native language of augusto mourra.

thank you to you all!


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Tue Jan 31, 2017 9:51 pm 
Offline
Newbie

Joined: Fri Dec 11, 2015 2:55 pm
Posts: 13
Hiring a developer for a free software project is not easy.

You usually need to hire someone that is already familiar with the project; otherwise, that necessary first step would require several (paid) weeks. And a developer with the required skill will probably not accept a job offer for a month. In fact, a developer with the required skills and motivation for a game would probably already have a job.

Also, the project should be mature, and the person should be hired with clear goals. Grit is not there. Not even 0 A.D. is there, which as I said had trouble precisely with this topic, hiring a developer, and the 0 A.D. project is far more advanced community-wise than Grit.

In my opinion, hiring a developer for Grit at this moment would not help that much. In fact, it could be a headache for whoever has to act as product manager for that developer, and it may even hurt the project.

What we need is to try to keep Spark motivated (GO SPARK! :D), and spread the word about the project. We cannot attract players at this stage, but we could attract some developers so that Spark is not alone.

I also believe, and this is something where I think 0 A.D. exceled, is to develop an actual game to build on top on the engine, and develop it along with the engine. The game would find bugs, performance bottlenecks and missing features in the engine, while also atracting both players and developers.


Top
 Profile  
 
 Post subject: Re: Awful first user and contributor experience
PostPosted: Mon Feb 06, 2017 3:35 am 
Offline
Newbie

Joined: Tue Oct 09, 2012 11:14 pm
Posts: 46
Hi,
Thank you for your answer Gallaecio, i agree with you

bye


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 11 posts ] 

All times are UTC


Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum

Search for:
Jump to:  
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group
Localized by Maël Soucaze © 2010 phpBB.fr