Maintenance gestalt-module

[Immortius]

Name: gestalt-module
Summary: An independent library extracting out the core module support from Terasology
Scope: Engine base-library
Current Goal: None
Phase: Maintenance
Curator: Immortius


Description:

gestalt-module is a library providing support for sandboxed modules that can be loaded and unloaded at runtime. These features currently exist in Terasology's engine - this module extracts them into a self contained library that can be used in other projects. It is the first step in modularising the engine, with several other future libraries dependent upon it (e.g. assets).

In additional to extracting the functionality, the API is being reviewed and improved.

Some specific improvements include:

• Full dependency resolution support using a constraint based resolver.
• Remove active/inactive module handling from the registry, replacing with a concept of "module sets" that can be loaded and disposed.
• Improved ability to determine the current executing module
• Improved documentation

 

[Immortius]

I'm in the wrapping up stages of this now. The library is feature complete, and integrated with Terasology (PR ready for review and merge). I've started work on the documentation - the Quick Start guide is up, and I will do a more thorough user guide shortly.

 

[manu3d]

As you write "feature complete": is the "planned work" section above still relevant?

 

[Immortius]

The stuff in green in done, the black is not. But that could be clearer.

 

[manu3d]

'specially, if it's done why is it still in the "planned" list???? It's DONE!

 

[Immortius]

Ok, User Documentation is complete and up at https://github.com/MovingBlocks/gestalt-module/wiki

Moving this incubator into maintenance.

 

[Cervator]

Nice and thorough, reading through it now during a waiting period after-hours at work

Questions:

• Is it module.txt or module.info? I noticed Adeon updated to .info in Rails, which I didn't understand at the moment, since that broke the job in Jenkins (gradle still expects module.txt). But then I saw a note on the Quick Start page about .info being the new default. I guess the game is lenient and still allows .txt which is why our modules work at all? Easy enough to change though, even across all the module repos (there are some other global changes to apply anyway)
• Can we follow the "condensed" format in the module metadata file where id, minVersion, and maxVersion are on the same line? I saw that in use somewhere and thought it looked nice and succinct (especially for larger dependency sets).
• Should the example maybe use the internationalization format in one spot and the "generic" string in another, just for clarity of what's available?
• In the Modules section for reflection might it make sense to point out the example is in Gradle, or is it meant as a more generic version adaptable to various build settings?
• Would it be worth supporting an alternative more detailed author section in the module metadata akin to the internationalization vs generic string block? You could potentially list multiple authors that way with structured data useful for automation or prettified display (author x has email y and contributed z) - low priority certainly
• There's an odd triple tick in an example on Module Sandboxing / Permissions I'm not sure what's about - excess markup?
• Is the mention of sun.reflect as a commonly allowed API package right related to the "Don't use Sun" stuff? I think that came up lately and for some part of reflection we have no other choice, and behavior in cases like OpenJDK is unknown but probably working?

That's all I can spot right now

 

[Immortius]

• Is it module.txt or module.info? I noticed Adeon updated to .info in Rails, which I didn't understand at the moment, since that broke the job in Jenkins (gradle still expects module.txt). But then I saw a note on the Quick Start page about .info being the new default. I guess the game is lenient and still allows .txt which is why our modules work at all? Easy enough to change though, even across all the module repos (there are some other global changes to apply anyway)

module.info is the default for gestalt-module, but Terasology overrides it to be module.txt to maintain compatibility.

• Can we follow the "condensed" format in the module metadata file where id, minVersion, and maxVersion are on the same line? I saw that in use somewhere and thought it looked nice and succinct (especially for larger dependency sets).

If you mean

{ "id" : "core", "minVersion" : "1.0.0" }

then sure, that's valid JSON. IntelliJ formatter would probably alter it though.

• Should the example maybe use the internationalization format in one spot and the "generic" string in another, just for clarity of what's available?
• In the Modules section for reflection might it make sense to point out the example is in Gradle, or is it meant as a more generic version adaptable to various build settings?

Good points, addressed.

• Would it be worth supporting an alternative more detailed author section in the module metadata akin to the internationalization vs generic string block? You could potentially list multiple authors that way with structured data useful for automation or prettified display (author x has email y and contributed z) - low priority certainly

Given requirements, sure.

• There's an odd triple tick in an example on Module Sandboxing / Permissions I'm not sure what's about - excess markup?

Fixed. Missing the end of the previous code block.

• Is the mention of sun.reflect as a commonly allowed API package right related to the "Don't use Sun" stuff? I think that came up lately and for some part of reflection we have no other choice, and behavior in cases like OpenJDK is unknown but probably working?

That's all I can spot right now

It is awkward, but because we allow the package using a string we avoid actually using Sun stuff. Otherwise I don't think we have a choice, and have been informed that OpenJDK implements that package - which makes sense since it has to run standard Java byte code and if the compiler is adding references to that package then they have to support it too.

 

[manu3d]

I went through the docs and I don't have much to comment on the specifics. I look forward using it as a base for modules.

The whole gestalt module made me think how much there is to game development beside the game itself. Of course most people have some peripheral understanding that there is much more to a game than just loading 3d models, moving them around and rendering them. But one thing is to sort of see those aspects with the corner of your eyes, another is to stare right at them as you need to design them and implement them. It's unsexy work and yet it needs to be done, and done well.

I guess this is a convoluted way to say that I remain impressed by the amount of solid work that is getting into Terasology.

 

[manu3d]

I went through the docs again, a bit more in depth. I'm a bit puzzled by it all. The docs are a well organized description of classes/features gestalt-module provides. Somehow however, I can't quite see the whole picture. Who is this for? Module developers? Engine developers? If I want to write a module, what do I need to do so that Terasology's engine can load it and fire it up? And once the module is fired up, how does it take advantage of anything the engine or other modules provide? I see the ingredients, but I can't quite see how to cook the whole thing. Or perhaps I'm misunderstanding the whole thing?

Perhaps a tutorial describing the workings of a fictional "Hello World" module would help. This module could provide one class printing "Hello World" in the log, one class getting/setting something in one of Terasology's config objects, another class interacting with another fictional module and perhaps a class appending "Hello World" to a file, hence requiring disk IO permissions. I'm sure more meaningful examples could be added to this, but these simple one would be helpful to start seeing how everything works together.

 

[Cervator]

The trick about gestalt-module is probably that nobody outside of core devs / architects really need to worry about it as far as Terasology content development goes. Where it is potentially super interesting is for entirely other projects that need a module system library

General content devs / modders new to Terasology with the desire to make a new module would probably just want to go through a general modding guide. Then if they just so happen to later want to make their own game of some sort in Java and need a module system - gestalt-module to the rescue!

 

[manu3d]

Understood. I guess I thought gestalt-module was already part of Terasology and new modules had to use it. Never mind then.

 

[Cervator]

Oh, it is! It is just so well integrated you don't generally need to think about it at that level It has been there for a long time already.

The asset system for Gestalt on the other hand is still under development and hasn't been integrated yet. When that's ready we'll tear out our current asset handling code and replace it with a dependency on the new external lib.

Later I believe the entity system and NUI are likely to go the same route. Helps keep the engine well-organized and exposes our frameworks for external use by other projects (including other things any of us might want to do)