Inactive Modding Guide and API Docs

[Cervator]

Name: Modding Guide and API Docs
Summary: Documentation & Tutorial type stuff for supporting mod making
Scope: Documentation / Tutorial
Current Goal: First useful iteration of modding documentation and tutorials aimed at end-users (mod authors)
Phase: Implementation
Curator: Cervator trying to pawn it off on somebody else
Related: Modding Arc thread, various pages in the GitHub wiki

Here's my first draft of a Modding Guide in the wiki

I'm not necessarily trying to own this item and would be happy for somebody else to jump in, but it is something we need right now as an important prerequisite for the next stable build - which will include the new modding system in full and hopefully allow more users/devs to jump in. At least I think that'll be in the build, bit hard to keep track with low time availability

There's more to do and I'll try to pitch in with additional effort. I've also realized that for all the talk about "Modding APIs" in general (not just here) I'm not actually totally sure what that actually includes. The Javadoc for relevant public classes you can extend in mods, a guide, some conventions for use of our JSON data/config files, an example/tutorial or two - is that about it, or is there an international association for APIs that have decreed a standard?

I left in a link to an uncreated "Modding API" page in the GH wiki I suspect we could use as a primer for links there to Javadoc we need to host somewhere and other related info. We also need to look at updating / linking some relevant pages, some of which probably are still waiting for me to migrate from the old wiki

Another big topic is mod-related dependency management, which probably should be described via this incubator process but really needs some consideration elsewhere if we have a lot of work to do there (I'm unsure). I haven't tested it yet (getting late), but can we refer to one mod's namespace from another mod? Does loading order matter? Or do we need to add some metadata to mods (in the mod.txt I'd guess) about what other mods (of which version?) it requires present to load?

I'm still playing with the idea of using GitHub repos for individual mods (so own code space, wiki space, issue tracker, etc) and may make that one of the next few things I test, which will impact this but really is more of its own item. Another item I'd be thrilled to pawn off on somebody else, too

I put a stub in for a goofy tutorial on making a new block that's both a chest and a portal (why not) which will certainly exercise those needs, but I'm not sure how doable it is yet or if I should just re-implement everything for the example

After some initial review and a bit more work I'm going to post this to the social outlets along with a new stable build then hawk it like the best thing since sliced cheese to get some more people interested in making content - so I'd really appreciate some feedback and corrections so the guide is in decent shape when it gets some interest

 

[Immortius]

There's more to do and I'll try to pitch in with additional effort. I've also realized that for all the talk about "Modding APIs" in general (not just here) I'm not actually totally sure what that actually includes. The Javadoc for relevant public classes you can extend in mods, a guide, some conventions for use of our JSON data/config files, an example/tutorial or two - is that about it, or is there an international association for APIs that have decreed a standard?

I guess generally an API represents a contract - its says "this is what is available to use, and how it behaves". While we're in pre-alpha it will be a fairly loose contract of course. It should include Javadoc for those classes which are approved for direct interaction, details on how to implement things like components and components systems, information on assets types and formats, and so forth. Unity's various documentation is a pretty good example.

Another big topic is mod-related dependency management, which probably should be described via this incubator process but really needs some consideration elsewhere if we have a lot of work to do there (I'm unsure). I haven't tested it yet (getting late), but can we refer to one mod's namespace from another mod? Does loading order matter? Or do we need to add some metadata to mods (in the mod.txt I'd guess) about what other mods (of which version?) it requires present to load?

You should be able to reference assets from other mods fine at the moment, at least as long as all the necessary mods are active for a world. Explicit dependency setup is missing at the moment though - I was thinking some extra information in mod.txt, yes. This information would need to be used by the gradle build as well. Version handling is another thing which is missing at the moment.

After some initial review and a bit more work I'm going to post this to the social outlets along with a new stable build then hawk it like the best thing since sliced cheese to get some more people interested in making content - so I'd really appreciate some feedback and corrections so the guide is in decent shape when it gets some interest

Alright. What you have so far is pretty solid. One piece of feedback - my intention with setting up new mods was that you enter the new mod into settings.gradle's include list, and run "gradlew cleanIdea idea". This actually creates the mod directory, and generates the subproject and links it to the main project. At the moment the mod.txt, and subdirectories still need to be created
manually though.

Also IntelliJ 12 has a the new "Make project automatically" option (under Compiler settings) which causes it to build things as you change them rather than only when you run, Eclipse style - this has the side effect of fixing the problem with modules not being compiled when you run Terasology.

I'm not sure newcomers need to be exposed to philosophical meandering about the nature of a mod . Perhaps we should just refer to them as modules throughout.

 

[Cervator]

Alright - thanks for the feedback, I've taken it to heart and tweaked some stuff

The compiler settings tweak works, that's very nice to have. I left both mod creation options in there with a future bias toward the Gradle way. It is pretty easy but does require you to again set source control integration, project SDK, and what not. Unless I'm doing that wrong

I also took out the philosophy lesson

 

[overdhose]

uch guys, I was looking at your modding api after figuring some stuff out through debugging
and uch you claim:

/src - actual source code for custom functionality goes under here. Usually this will be custom Components and Systems that make up the core content in our Entity System Architecture

however looking at the mod / modmanager it seems it looks for a "classes" folder to determine if it has code or not, or a jar. So I was pondering what the correct way is now... or if this is supposed to work at all atm...

nm looking at the portals mod cleared my prob

 

[Immortius]

When you are creating a mod, you put the the java source in the src folder (strictly, src/main/java). When the mod is compiled, the compiled code ends up in a classes folder, or in a jar.

Basically I'm expecting mods to work like any other sort of java project - and gradlew will set them up like this in the generated intellij/eclipse project, at least if the mod is added to build.settings and the directories exist (we should improve the process to create the folder structure, really).

 

[overdhose]

Yeah it's ok it's my noobisch understanding that caused the problem really. I should have read this guide before I started poking things around again only to end up here after debugging through the modmanager.

Anyway I'm just toying around a bit, possibly producing something usefull.