Simutrans Code for Dummies?

[Chups]

Hi everybody,

Simutrans has been immensely enjoyable for me the past couple years and I think I have come to a stage where I would like to contribute in some way.
I understand that Simutrans is a very complex project with a lot of legacy code and an overworked (and small) team of volunteer developers, but that understanding did not prepare me for the confusion I experienced when I started to try and make sense of the gobbledygook the code is.
To tell the truth, even though I spent about a week on and off, I can't even make a solid picture of the program's high-level architecture in my head or guess what the design intent was, how is it supposed to be laid out and what major interdependencies are there.

I'm sure I'm not the only amateur banging his head against this steep initial learning curve, and it may take me months to start getting some insight. I would really appreciate some UML diagrams (current and/or planned) as well as any documentation there is out there - I cannot believe that a project of this magnitude does not have any architectural documentation besides the code comments. It doesn't make sense, even if just from a project continuity standpoint - what if someone with unique knowledge of a cryptic but very important part of the project gets into a car accident? *knocks on wood*

We could possibly make this into a FAQ or a crash course for those wanting in on the development. The easier it is to get in for those enthusiasts out there, the more people will participate in the project, which could be beneficial in the long run.

Looking forward to being a part of the effort,

[prissi]

Comparing to some other project I am involved with, simutrans is actually quite hierachiacal structures, as it was a learning project for OOP once.

It starts all with karte_t, which holds an array of planquadrat_t (a 2D coordinate), which holds arrays of grund_t (the actual ground, or foundations, tunnel, bridges, highways, water). Each ground holds a dinglist, which contains stuff (as dinge = stuff), like moving stuff (car, trains, airplanes, .. ) and other stuff like buildings, trees, ... The stuff is derived from ding_t and sits all in dinge/ folder.

Each stuff can have three periodic calls: for very regulary and fast actions which require exclusive access on the map (moving cars, collision avoidance) there is sync_step, called before every frame. Slower actions like route_finding, way building etc. is done in step(), where the map can change in between slightly. Some objects (most notable trees) require seasonal changes, which are covered by the relatively new action method of check_season();

The UI is completely separated from this. All dialogues are nowadays derived from gui_frame_t and fully object oriented.

Moreover the program was developed by a single person most of the time. It was a challenge enough, without writing documentation (which is for me rather like work, and surely not a spare leisure). There was some sketches from early development, which still holds, but the site containing them is currently down.

Honestly, I had to google what an uml diagram is. The wikipedia page is quite good for falling asleep while reading. I will translate the above stuff into UML. Not sure that will help you though ... [Ok, the two programs I looked are nearly completely unusable without reading lots of specs and manuals. Well go ahead and create a structure like I said above]

But other than that, most of simutrans is quite local and quite separate from other modules. Therefore it is imho best to just work locally on one issue, and submit a patch. You will get some critical reception then.

[inkelyad]

When I started to study simutrans code, I just feed it to Doxygen. It was very helpful.

[Dwachs]

@Chups: What do you want to achieve? Which part of the program would you like to alter? Then we can point you to the relevant portions of the code.

[Chups]

Which part of the program would you like to alter? Then we can point you to the relevant portions of the code.

Problem is, to know what I would like to apply myself to, I prefer to acquaint myself with the overall architecture (concept, structure) of the project, so that when I decide to try and alter something, or when I'm coding, I know that I'm doing it for good reasons and I'm aware of where I'm at and what I'm doing in respect to the big picture.

That's just the kind of person I am, that's how my brain works. 

[prissi]

Then you are in for a month or so. Actually it took me about a year to have visited and understood all corners of the code. But this is highly unneccessary. For instance you do not need to know about the pak loader, the network code, or the UI as long as you do not want to modifiy anything in this part.

And any such diagram is progably in the end not much better than doxygen or what MSVC does with the code (actually, the recent MSVC Studio is one of the best development UI I did ever use. It also generates class dependencies and the like you inquire automatically).

[jamespetts]

There is something to be said for stickying this thread, as Prissi's description of the code in his first reply is likely to be very useful to anyone starting working on Simutrans development.

[Erik]

Good idea.
I have the same problems as Chups.

I believe the hierarchy was sufficient before, but now Simutrans has actually a bit grown out of it.
It should also be nice to have some more comments with different parts of code.

[Markohs]

Indeed this is very useful, I wish this was already been written when I started the branch!

[Randy007]

Hi,
the tip from inkelyad is exelent. In kombination with "DOT" you get a first glimse. But caution i have got a dokumantion of roundabout 1,3G! It tooks about 1H to produce it.

[Dwachs]

There is also this documentation topic by Isidoro:

http://forum.simutrans.com/index.php?topic=8789

CHAPTER 1+2: WORLD + WAYS (AND ROADS)
CHAPTER 3: RIBI and SLOPES
CHAPTER 4: SIGNS
CHAPTER 5: VEHICLES AND CONVOYS
CHAPTER 6: SCHEDULES AND ROUTES
CHAPTER 7: MOVEMENT OF CONVOYS
CHAPTER 8: IST_WEG_FREI and friends