Oolite interaction with Expansion Packs

[cim]

http://wiki.alioth.net/index.php/OXP_howto might be helpful - with the exception of manifest.plist (and the deprecated requires.plist and info.plist) all PLists must go in the Config subfolder of the OXP. That page has a full list of which plists are supported for OXP use, mostly documented ... as well as broader documentation of OXP structure.

There are five plists starting with "ship" which are used to register ships - but shipdata.plist is generally the important one
(shipdata.plist would be more accurately called objectdata nowadays - a "ship" in Oolite might be a ship, a station, a rock, basically any solid object smaller than a planet)

[Cholmondely]

http://wiki.alioth.net/index.php/OXP_howto might be helpful - with the exception of manifest.plist (and the deprecated requires.plist and info.plist) all PLists must go in the Config subfolder of the OXP. That page has a full list of which plists are supported for OXP use, mostly documented ... as well as broader documentation of OXP structure.

There are five plists starting with "ship" which are used to register ships - but shipdata.plist is generally the important one
(shipdata.plist would be more accurately called objectdata nowadays - a "ship" in Oolite might be a ship, a station, a rock, basically any solid object smaller than a planet)

What about moons?

[cim]

That depends how the moon is implemented - is it a very small planet, or a very large space station? Depending on what you want to do with it, it could be either.

[hiran]

http://wiki.alioth.net/index.php/OXP_howto might be helpful - with the exception of manifest.plist (and the deprecated requires.plist and info.plist) all PLists must go in the Config subfolder of the OXP. That page has a full list of which plists are supported for OXP use, mostly documented ... as well as broader documentation of OXP structure.

There are five plists starting with "ship" which are used to register ships - but shipdata.plist is generally the important one
(shipdata.plist would be more accurately called objectdata nowadays - a "ship" in Oolite might be a ship, a station, a rock, basically any solid object smaller than a planet)

This helps, thank you. I will start with equipment and ships - that should be sufficient for a start.

[hiran]

Again a pitfall:
http://wiki.alioth.net/img_auth.php/8/8 ... _2.5.2.oxz // Content/equipment.plist
has XML content. This speciality seems to be lurking potentially everywhere...

so I decided to dodge them for now and found another interesting artifact:

http://wiki.alioth.net/img_auth.php/5/5 ... rs_0.9.oxz
/Config/shipdata.plist
line 517 contains:

Code: Select all

orientation = ( 1.0, 0.0, 0.0, 0.0); position = ( -67.5.0, 19.0, -97 );},

Now what does the Oolite parser do to the value -67.5.0?
For my proof of concept I will simply dodge all these little pitfalls and check what remains...

[hiran]

Finally I was able to create something. The zipped output directory is about 6 MB.
How can I share that with others who are online here?

[montana05]

Finally I was able to create something. The zipped output directory is about 6 MB.
How can I share that with others who are online here?

You can try https://account.box.com/login, it's free and was for a while the preferred location for OXP's.

[hiran]

So then I have this document for the interested ones: https://app.box.com/s/feinumgcaq9p2n6h4uffouy2yev1ph8u
Feedback is welcome.

[hiran]

Ok, now I had a better look at the world scripts, and this page lists nicely the events that the script may react on:
http://wiki.alioth.net/index.php/Oolite ... t_handlers

How about threading/timing?
What happens if the world script takes a (too) long time to finish, or never returns, or returns with failure?
Will this block/crash the game, or block/fail just the thread that Oolite spawned for this OXP?

If this could break the game, would it make sense if an OXP with long-running handlers could internally create a queue of events to process with a thread pool to work them off?

[hiran]

Ok, now I had a better look at the world scripts, and this page lists nicely the events that the script may react on:
http://wiki.alioth.net/index.php/Oolite ... t_handlers

How about threading/timing?
What happens if the world script takes a (too) long time to finish, or never returns, or returns with failure?
Will this block/crash the game, or block/fail just the thread that Oolite spawned for this OXP?

If this could break the game, would it make sense if an OXP with long-running handlers could internally create a queue of events to process with a thread pool to work them off?

I think I can answer some of my own questions now. After all I started creating my own OXP with a world script and added two event handling functions.
Things I find noteworthy:

• * Oolite is pretty unimpressed if not all script functions are implemented. It just runs the functions it can and still functions.
  * Oolite is pretty unimpressed if functions cannot perform their work. I had a typo in one of them, and all I got was a Javascript error in the logfile. Oolite still functions.
  * It seems timing issues do not occur due to the nature of JavaScript. See more at https://www.sitepoint.com/delay-sleep-pause-wait/
  * When forcing timing problems (I implemented some sleep()), the code gets terminated with this log message: ***** ERROR: Script "speedtest" ran for 1.46696 seconds and has been terminated.

All in all the JavaScript implementation seems really suitable for coding OXP stuff.

[hiran]

[...]
Run Doxygen on the Doxyfile in the source's root folder. It will generate full documentation for the game's code and provide you with a map of the entire codebase. Very useful when questions like "how does it all fit in" are asked. I have uploaded the full documentation for whatever version we had back in 2018 here, but you will have to build your own for version 1.90. Warning: The full documentation weighs at around 700MB.

I followed your advice, and now we have the first pre-release with up to date doxygen:
https://github.com/OoliteProject/oolite ... tag/latest

After a quick look I am impressed by the amount of information, despite the fact that there is hardly any comment in the code.
And I am wondering whether I got it right. At first glance it looks like, but then the archive size is 37 MB, while the archive you provided is 152 MB.
What could cause that a big difference?

[another_commander]

I followed your advice, and now we have the first pre-release with up to date doxygen:
https://github.com/OoliteProject/oolite ... tag/latest

After a quick look I am impressed by the amount of information, despite the fact that there is hardly any comment in the code.
And I am wondering whether I got it right. At first glance it looks like, but then the archive size is 37 MB, while the archive you provided is 152 MB.
What could cause that a big difference?

It could be a lot of things, depending on doxygen version used, how the documentation was generated and its target architecture. I skimmed through it very quickly and it seems alright, although I noted that it was Linux oriented. It makes sense I guess, if the worker that produced it ran Linux.

One difference might be the doxygen version. I don't remember what I used in 2018, but chances are it will be something more recent now. Also, I had specifically targeted my output to Windows. You can pass a set of defines to doxygen when it executes so that it follows specific code paths when analyzing the source code it's working with. I am not sure what the doxygen github action did or how it was setup, but this is something to be aware of. Finally, I remember I had used some command line arguments which resulted in a large set of graphs for code flow (e.g. I could start from main and follow the code execution as it was going through its various paths using these diagrams as visualization guides and I remember it was very helpful, but I could not find the equivalent in this set. But maybe I just don't remember exactly how to navigate to such diagrams, so I once again can't be sure. But these or any combination thereof could all be possible culprits for the size difference.

[hiran]

It could be a lot of things, depending on doxygen version used, how the documentation was generated and its target architecture. I skimmed through it very quickly and it seems alright, although I noted that it was Linux oriented. It makes sense I guess, if the worker that produced it ran Linux.

One difference might be the doxygen version. I don't remember what I used in 2018, but chances are it will be something more recent now. Also, I had specifically targeted my output to Windows. You can pass a set of defines to doxygen when it executes so that it follows specific code paths when analyzing the source code it's working with. I am not sure what the doxygen github action did or how it was setup, but this is something to be aware of. Finally, I remember I had used some command line arguments which resulted in a large set of graphs for code flow (e.g. I could start from main and follow the code execution as it was going through its various paths using these diagrams as visualization guides and I remember it was very helpful, but I could not find the equivalent in this set. But maybe I just don't remember exactly how to navigate to such diagrams, so I once again can't be sure. But these or any combination thereof could all be possible culprits for the size difference.

Is there a difference in doxygen running on Linux vs Windows? That surprises me - after all it is documenting the same code.
For me it is the first time to actually use that tool, so I cannot tell what you had or where to find it.

But if we find out what is missing and how to get it we can still change the process, so I do not mind. Same if you find the command you used again (I do not see too many options on the command line: https://www.doxygen.nl/manual/doxygen_usage.html).
The important part is that we now have an up to date documentation set matching every build.

[another_commander]

Is there a difference in doxygen running on Linux vs Windows? That surprises me - after all it is documenting the same code

Not exactly. Linux and Windows share common code for the most part, but they follow different paths in many cases. Just check out all the #if OOLITE_WINDOWS #else conditionals spread all over the place for some examples.

For a more specific example, in the case of the doxygen output released yesterday, you will notice that all methods pertaining to HDR are described as either being void or returning false. That is because there are no implementations for those methods for Linux. If you were documenting the actual Windows code, you would find that doxygen would be providing you with the implementation of those HDR methods.

Having sat that, the differences are not that many or important and the goal of having a tool to help one navigate through the quarter million lines of Oolite's source is still nicely achieved.

[hiran]

Is there a difference in doxygen running on Linux vs Windows? That surprises me - after all it is documenting the same code

Not exactly. Linux and Windows share common code for the most part, but they follow different paths in many cases. Just check out all the #if OOLITE_WINDOWS #else conditionals spread all over the place for some examples.

For a more specific example, in the case of the doxygen output released yesterday, you will notice that all methods pertaining to HDR are described as either being void or returning false. That is because there are no implementations for those methods for Linux. If you were documenting the actual Windows code, you would find that doxygen would be providing you with the implementation of those HDR methods.

Rats! I did not think of that. So doxygen understands the code way better than I had anticipated, and the fact that I work on the 'no worries it runs anywhere anyway' Java platform allows me to completely ignore such facts.

Having sat that, the differences are not that many or important and the goal of having a tool to help one navigate through the quarter million lines of Oolite's source is still nicely achieved.

True again. If need be, we can still spawn a Windows runner and generate doxygen there in parallel. Just let me know.