So we've all started playing with the SDK. What fun playing with a powerful bunch of c++ code hey. We've all worked out we have to use the hard-to-find VS 2003 or manually configure Code::Block to even compile it. Hey we've even managed to make some very subtle changes (kudos to all those who have posted tutorials on the SDK, keep em coming.)

Now we need to get serious. I find my self trawling through lines of code jumping from class to class and method to method trying to get a picture in my head about how this thing is working. Then i imagine that every other SDK hacker out there is combing through this doing the same thing. Wouldn't it be great if we shared our knowledge of the SDK so that we weren't going over the same lines of code that others are?

I propose we create a project whereby we document ALL our findings on the SDK in an organised documentation system that is completely open to all to add to.

I wanted to propose this first and scope out some ideas from others. I am willing to host a wiki and moderate the project, with a couple of others.

We need to decide on a model for presenting the docs. My first thought is a wiki page for every seperate .cpp file. With headers for each class and subheading for each method outlining its function, what other classes use the class (the power of wiki, we can link directly to those class docs and make it really easy for people to build their knowledge) and what other classes are used by that class (if i say class one more time someone will shoot me, i'm sure). Finally a description of variables, linkage to python and other misc. items. The format needs to be nutted out heavily first, but you get the idea.

Those are just first thoughts, please add your own. Feel free to PM me, or add my google talk (mail.phatlip@gmail.com) if you want to help out.

Just very finally (skip this bit if you're bored) i'll make daily copies of the wiki into .odt (open office) format, host the offline version along with specific tutorials, copied from this forum, with the permission of the respective author.

Perhaps if we all contribute we'll actually have time to PLAYthe game. Wouldn't that be something.

I think this would be a great idea I am just learning C & C++ now (well have been for almost 2 months) and if this goes ahead then it would make it alot easyier for us begginers to find and change things as well as you hard core programmers

There is already a Civ 4 Wiki set up that this project would probably fit nicely into (see my sig).

The trouble is with this sort of thing is it's quite a chore to go through everything documenting it all. There are also many functions that are quite obvious, and don't really need documenting.

That doesn't mean I don't think it's a good idea.

@The Great Apple

It may be a chore initially, but with many people adding to it, it would become quite simple and then a great resource.

Secondly, functions are obvious according to whom? I don't think its wise to make that assumption, especially when the documentation should entail how to use the function, what uses it and other misc items, not just 'does this, take this as arg, done.' Some files will need less information, naturally - but all should be covered. This will be real documentation.

Thirdly, i assumed the wiki you had was for elements of civilization, however if we could create a 'sub wiki' for the SDK then that would be great. It would need to have its own space, due to the scope.

I think the most important thing is that it should be thorough, and have a consistent theme throughout the pages, like regular docs.

phatlip.

p.s - have added a SDK page on the civ4wiki.

You make a good point. I supose after fiddling with python for quite a while I have become accustomed to alot of the basic functions, and rather take them for granted.

This is an awesome idea, but why open office. (I have open office, but I don't think may other people have it.) You can save as .doc and everyone can veiw it.

Perhaps if we all contribute we'll actually have time to PLAYthe game. Wouldn't that be something.

Play? Do you mean play test? That's all I've been able to find time to do :P

But anyway, yeah, I'd be willing to perhaps put up a small comment here and there on various functions on a wiki. However, the documentation on the wiki for the python functions doesn't seem as complete, I wonder if that's just a sign of things, considering you actually have less people working with the SDK (that's my assumption anyway).

@unit8765

Open Office is free download and you can save all files as .doc for those who don't want to download.

I won't save something in a proprietry format if i can avoid it.

@Gerikes

True, but lets see where we can go with this anyway. Just taking notes can sometimes be useful for you own self. I keep the wiki open now and just jot down random things. Later we can format the random notes into real documentation.

Man, that would be great!!!

To have a documentation on the code would help so much!
I'va started learning C++ some weeks ago, and did like 2763 versions of HelloWorld and Tetris clones, but a real game would be fun to understand...
I ventured into the GameCore a couple of time, only to find myself puzzled quite rapidely;), so I started commenting my dll, trying to get a grasp on it...
Hopefully, people with a better knowledge of C++ than me (wich I'm sure most "real" programmers out there have;)) will help us all by contributing to this project!

Also, even though, as I said, I'm pretty new to C++, if I could contribute in any way, I would be most happy!

You know, I'm getting tired of having my computer saying Hello to me;)

Has anything come of this idea? I think an SDK doc project would be great

Has anything come of this idea? I think an SDK doc project would be great
Same question from me. I just had a look at the SDK c/c++ code and it looks overwhelming. It sure looks like a good reference would help.

I could spend some time, too, to help, but there is a major risk around: "look, the stuff you worked on already existed at xxx.yyy.com!". And this is a highly demotivating risk.

So, again, is there a SDK doc project ? Or several of them ?

None that I know of

I have added some structure to the SDK documentation on the civ4 wiki

I'm hoping that this will encourage everyone to contribute to this project.

I for one will be adding an entry for each function as I use it in my own projects. For now I have only written about the CvGame::doControl method as its the only one I have used. If everyone does this then it should take shape!!

:p

http://civ4wiki.com/wiki/index.php/SDK

Gareth

Count me in, although im extremely rusty on c++. I jumped over to vb.net when that debuted because c++ was too nuts and bolts. *kicks self* I'm not what you would call a real dev, as im only a lowly pc/net techie. I cant sit still long enough to be a thoroughbred code thrasher lol.

Anyway, I decided last week to build my own overly ambitious and far too huge mod and thus won't even start any dev work until I have full knowledge of the SDK. So, looks like many months in the trenches, but hey, Civ is a lifestyle =)

So, if I manage to wring anything out of the sdk code, i'll pass it along.

I read somewhere on a thread -not sure which (maybe niftools) that the problem is with the .exe. It won't communicate with vc++ 8. If I misunderstood what I read, then disregard anything further.

I have a somewhat usable program for decompiling .exe files as I am sure most of you do, my thought is (though I have never attempted this) is to map out the code base and rewrite it in vc++ 8. Then the sdk recompiled in vc++ 2005 should be streamlined?!

Any intelligent thoughts? or Your off your rocker comments?

Hello everyone!
This is my first post and I am really keen on knowing if this project has taken off! :crazyeye:

If you have to go with licensing on the wiki/documentation, may I suggest MIT for the code and public domain for the wiki/documentation portion (or just public domain for it all)?
GPL, LGPL, GPLD would all impose restrictions on people as would many Creative Commons licenses, but the MIT and, especially, the public domain would basically be free for all.

Figuring out the SDK isn't too hard so long as you've got a bit of time and C++ experiance, or have a brain like TheLopez. But making docing the whole thin is going to take a lot of time and a full time leader. He'd have to get the more experianced SDK modders and ask them to write out parts. But like I said, it will be very time consuming and very possibly if you can't figure it out and have little C++ experiance no amount of doc is going to help.

Figuring out the SDK isn't too hard so long as you've got a bit of time and C++ experiance, or have a brain like TheLopez. But making docing the whole thin is going to take a lot of time and a full time leader. He'd have to get the more experianced SDK modders and ask them to write out parts. But like I said, it will be very time consuming and very possibly if you can't figure it out and have little C++ experiance no amount of doc is going to help.
Maybe just start off with a simple listing of functions, classes, etc... and how to access them? Then, as people use them, they can fill out simple descriptions. Then, you could eventually group them into categories.

Figuring out the SDK isn't too hard so long as you've got a bit of time and C++ experiance, or have a brain like TheLopez. But making docing the whole thin is going to take a lot of time and a full time leader. He'd have to get the more experianced SDK modders and ask them to write out parts. But like I said, it will be very time consuming and very possibly if you can't figure it out and have little C++ experiance no amount of doc is going to help.
Maybe just start off with a simple listing of functions, classes, etc... and how to access them. Then, as people use them, they can fill out simple descriptions. Then, you could eventually group them into categories.

Regarding the wiki... perhaps a better option would be to setup the wiki software here on civfanatics. Thunderfall would probably be interested in allowing that -- supposing he has a way to give partial access for the wiki software.

Another update...

How about the following:
For the wiki: http://trac.edgewall.com/
Then, added to the wiki a special WYSIWYG editor: http://xinha.gogo.co.nz/xinha-nightly/examples/ext_example.html

Both products are BSD license (aka a free source license). I took great effort to find a non-GPL Wiki (instead looking for MIT, BSD, or public domain).

I, of course, need to check on a few things first; but what do you think about using this?

There is already a wiki up and running here (http://civ4wiki.com/wiki/index.php/SDK) but unfortunately it's all structure and no content. Lots of topic but no one has posted any data.

There is also a pretty good Civ4-oriented Python intro http://civ4wiki.com/wiki/index.php/Python_Tutorial_-_Introduction#Contents:]wiki (http://civ4wiki.com/wiki/index.php/Python_Tutorial_-_Introduction#Contents:)

Sadly, those who know the code appear too busy to share that knowledge. Understandable, of course, but disappointing. Even the XML files aren't fully documented yet. It'd sure be nice to know what "NoTradeThreshold" does....

One would think that since it's modability was a major selling point for Civ 4, Firaxis/Take2 would release the *real* documentation rather than force everyone to flounder helplessly. I know that my frustration factor gets fairly high; I've got a busy enough life without having to teach myself a new language.

Aye, Civ4 is more 'moddable' than most, but there is a still an enormous amount of time being wasted as everyone re-invents the wheel. Full documentaion would help tremendously in this regard.

But, we must look on the bright side. A game company that engages with the mod-fan base...a released SDK...effort made while writing the code to make it more 'mod friendly'...as much written into XML as possible...

These are great leaps forward. I've been a gamer for many years and you rarely, if ever, get this kind of support from a game company.

I guess my stand is typically American - thank you very much, I love it, and I want more.

Here's an idea:

Use Doxygen (http://www.stack.nl/~dimitri/doxygen/) to generate your own API. You'll be commenting code and documenting it in one go.

Just my two cents.

Hi!

Creating a comprehensive (community) documentation is a great idea. Is there any progress on this?
I tried the mentioned page at civ4wiki, but the site seems to be down?

Regards
ollej

UML would be nice. I'm going to look into this PyDev eclipse project, I may be able to generate some models.