More Documentation

Propose and discuss new features yet to come.

Moderator: PPS-Leaders

Post Reply
User avatar
Nowic
Thanathon, God of the lower Planes
Posts: 186
Joined: Tue Oct 03, 2006 7:53 pm
Location: Zürich
Contact:

More Documentation

Post by Nowic » Thu Jan 04, 2007 4:24 pm

Orxonox needs more documentation!!! To attract new users and devs it should be easy to add new content, change things or test the cool features of orxonox.

At least all XML files and the console should be documented, so I created these two new wiki pages:

https://dev.orxonox.net/wiki/LevelHowTo (thx to Beni for writing the first part)
https://dev.orxonox.net/wiki/Console

I know nobody likes it... but please join us and write some documentation. thx.
"I've always lived cheaply. I live like a student, basically. And I like that because it means that money is not telling me what to do. I can do what I think is important for me to do. It freed me to do what seemed worth doing." -- Richard Stallman

User avatar
patrick
Baron Vladimir Harkonnen
Posts: 350
Joined: Mon Oct 02, 2006 6:03 pm
Location: Bern

Post by patrick » Fri Jan 05, 2007 12:09 am

You are right! I will do some work on the shell documentation, since I probably am the only one to have an overview (except for bensch)

User avatar
bensch
Admiral Alexi Sarkhov
Posts: 101
Joined: Tue Oct 03, 2006 2:28 pm
Contact:

Post by bensch » Fri Jan 05, 2007 10:29 am

Shell Commands
I think, writing a page about the shell's commands does not make much sense. A developer's overview of the shell is already existing on https://dev.orxonox.net/wiki/Shell.
What we could explain is how to use the console, and what some basic commands (like the tab key and the help dialog).

A complete list of commands is useless, as the shell features autocompletion, and because these commands can change on a daily basis.
If you like, I can write a handler, that lets you write out the list of shell commands with a ShellCommand :) but you have to upload it any time it changes.

Level Howto
This is much more important, and I also thought about a simple level editor, but for now, it seems the best if we just make some simple overview, and reference to examples.
[/b]

User avatar
Nowic
Thanathon, God of the lower Planes
Posts: 186
Joined: Tue Oct 03, 2006 7:53 pm
Location: Zürich
Contact:

Post by Nowic » Fri Jan 05, 2007 10:59 am

Well that's true... maybe I shouldn't have written "complete" list.
The list should be for a (non technical) user and should just show the most important and most interesting commands. If you don't tell them, they won't find out that there is a waterGUI or a weather engine!
You have to think from a consumer perspective. Technical documentation is fine... but nobody reads it if you just want to take a short look at the game and see what the engine can do.
"I've always lived cheaply. I live like a student, basically. And I like that because it means that money is not telling me what to do. I can do what I think is important for me to do. It freed me to do what seemed worth doing." -- Richard Stallman

User avatar
beni
Baron Vladimir Harkonnen
Posts: 949
Joined: Tue Oct 03, 2006 9:15 am
Location: Zurich
Contact:

Post by beni » Fri Jan 05, 2007 12:54 pm

I think a reference to the code where one can have a look what commands are working in the console couldn't hurt. Same goes for the handler of the level files if that's possible.
"I'm Commander Shepard and this is my favorite forum on the internet."

User avatar
bensch
Admiral Alexi Sarkhov
Posts: 101
Joined: Tue Oct 03, 2006 2:28 pm
Contact:

Post by bensch » Fri Jan 05, 2007 5:54 pm

Wow.. thanks a lot! The page looks good and the most important sections are described.

Good work!

Marc
Human Space Navy Major
Posts: 41
Joined: Tue Oct 24, 2006 7:45 pm
Contact:

Post by Marc » Tue Jan 09, 2007 9:30 am

The most imporant thing I think which Orxonox codewise needs, is an "introduction" guide. Its like a little trip to hell if you start coding with the engine as it seems to work quite differently compared to other engines.
A general idea, behavior etc. guide is badly needed (especially if further PPS are planed to happen).

With 8 - 10 hours a week it is simply impossible to get anywhere (so far I had at least 15 hours a week to get stuff running the way I wanted it to, because some stupid background handler inverted or ignored my stuff so I normally end up with "ignore orx, use gl", although that's the highly undesired way ...)

User avatar
patrick
Baron Vladimir Harkonnen
Posts: 350
Joined: Mon Oct 02, 2006 6:03 pm
Location: Bern

Post by patrick » Tue Jan 09, 2007 10:51 pm

Thanks for the great work!
Marc wrote: Its like a little trip to hell if you start coding with the engine as it seems to work quite differently compared to other engines.
A general idea, behavior etc. guide is badly needed (especially if further PPS are planed to happen).
Yes. I agree, tutorials are needed badly.
Everyone is saying that, including the main programmers of the project, only problem: the main programmers never take time to do such a thing. Because if they stop working, the whole project stops.
If there is no documentation, people will have a hard time starting to work with the framework, but if the framework is not worked on, there will be no people that are interested in the project...

What most people forget about Orxonox: It's a young project that started as a two-man project. Because of the fast development in the last year (because of the PPS) Orxonox now has nice graphical effects and many people were very much impressed by those. Now suddenly Orxonox rose from a small unknown project to a game that is compared with other big projects.
We never had the intention of camparing Orxonox to any big project like Ogre3D, Crystalspace or other well established frameworks. If we would have at any time, we wouldn't have programmed a whole engine from scratch.

I'm not sure if we want Orxonox to play in the same league as Ogre3D and all the other famous engines. It's still a hard and long way to reach such a goal and we would need many motivated hard working people. From my point of view, there is nothing which is not reachable!
But unfortunately I personally won't have much time anymore to lead on to reach such a goal in the near future.

I'm very happy to see you all think about ways to enhance Orxonox, beyond a funny project towards a real game. I also think that with such a combination of different people Orxonox will be able to attract a community and people having fun playing!

Marc
Human Space Navy Major
Posts: 41
Joined: Tue Oct 24, 2006 7:45 pm
Contact:

Post by Marc » Wed Jan 10, 2007 8:09 am

I'm actually not comparing Orxonox to any "large scale project"
I just compare the way the engine behind it works and is handled to some "standards" I got used to when toying around with OGRE, Irrlicht, Blitz3D, Dark Basic Pro and Torque.

Even though those engines are much larger in size, they still are able to transfer the "common thoughts and ways to use" to the end user and allow those to be expanded in ways, which allow them to be used even more powerfully.

That's the point where Orxonox somehow fails.
Not only documentation wise but the implementation itself breaks with that (as a simple thing to point out: Collision. CollidesWith is omnipresent in sources, yet we were told that Hit is the new way, yet it is the useless way as hit is bound to 1 target, 1 damage instead of 2 objects + position to allow custom reactions. That's just a small example of problematic inconsistency).

I think what Orxonox needs is a serious clean up before progressing any further. There are that many outdated parts in it, which should not be used or can lead to serious problems, that it is nearly impossible to extend it without break it once again.
And I don't think it's fun for you, the main devs, to work on something where you mainly fix problems instead of expanding the experience...

User avatar
patrick
Baron Vladimir Harkonnen
Posts: 350
Joined: Mon Oct 02, 2006 6:03 pm
Location: Bern

Post by patrick » Wed Jan 10, 2007 9:13 am

Marc wrote: Not only documentation wise but the implementation itself breaks with that (as a simple thing to point out: Collision. CollidesWith is omnipresent in sources, yet we were told that Hit is the new way, yet it is the useless way as hit is bound to 1 target, 1 damage instead of 2 objects + position to allow custom reactions.
You probably might remember, that positions are saved within Worldentity objects, therefore reducing the number of arguments. Since one object of the collision is the called WE itself the nr of arguments can be reduced further.

You are right saying that documentation would help, so we can get around situations like these. Another possibility would be to ask someone from the old crew here in the forum instead of trying finding out the correct solution for yourself (with can be very anoying, I know).

About the interfaces of the framework: the people who wrote this code (including me) would be grateful to hear concrete ideas instead of general complaints.

What one would hope for is a collection of inputs/questions/ideas to be able to work these problems out. Without knowing your individual problems with the framework we can't do anything about it and things will stay the way they are. It won't help anybody if we start blindly writing documentation now, so please help us and yourself :D start a thread in the Engine Development forum or a wiki page with a technical description of your problems.

Thank you!

Marc
Human Space Navy Major
Posts: 41
Joined: Tue Oct 24, 2006 7:45 pm
Contact:

Post by Marc » Wed Jan 10, 2007 10:06 am

Sorry if it was unconstructive.
I'll collect the problems I had and write them down when finished.
It were no "core problems", more problems with too many objects that refer to deprecated usage which makes it hard to find the "current implementations".


I agree that the collision does not need other datas as the other entity is given.
For that reason, I do not understand a damage value is provided.
Normally I would assume a collision event object there but orxonox has internal collision reaction, so it does not need to provide collision normals etc to the entity.

Orxonox in general is quite good, no question.
Otherwise I would have gone mad long ago instead of creating new stuff :-)

User avatar
patrick
Baron Vladimir Harkonnen
Posts: 350
Joined: Mon Oct 02, 2006 6:03 pm
Location: Bern

Post by patrick » Wed Jan 10, 2007 10:18 am

Hi marc!

Thanks very much for your effort! I really appreciate your work and I'm sure that Orxonox is only going to benefit from your critical view of the Orxonox framework!

patrick

Marc
Human Space Navy Major
Posts: 41
Joined: Tue Oct 24, 2006 7:45 pm
Contact:

Post by Marc » Fri Jan 26, 2007 10:21 pm

I've started to write down the problems I had when using Orxonox at first or during the first weeks. As there is already a programmer FAQ, just with not that much information, I decided to put it there, instead of putting it here on the board, where it will most likely be missed quite regulary, if more threads are going to appear in the future.

https://dev.orxonox.net/wiki/ProgramerFAQ

User avatar
patrick
Baron Vladimir Harkonnen
Posts: 350
Joined: Mon Oct 02, 2006 6:03 pm
Location: Bern

Post by patrick » Mon Jan 29, 2007 10:39 pm

Hey marc!

This really rocks! Thx!

Post Reply

Who is online

Users browsing this forum: No registered users and 1 guest