Looking for API Documentation or Reference documentation

[crazycodr]

Started modding Minecraft a few weeks ago, doing good but simple, but i can't seem to find any api documentation of the classes, hooks, endpoints, enums, etc. Lots of tutorial lingering the world but no documentation it seems.

 

I'm kinda tired reading tutorials that say copy and paste this, do that and it'll work... I want to understand what i am doing and not listen to 13 videos to know how to do a custom furnace with a person that doesn't even seem to know what he's doing!

 

So where is that documentation?

[Kwibble]

So... Your asking for minecrafts documentation? Have fun with that. I wish you luck. Forges documentation on the other hand... Have you looked into Javadocs? Specifically the forge ones?

 

If you want to understand the what you are doing, start reading. Go up through the classes reading what method calls and this and what does this do etc.. It takes a lot of work and effort, but its worth it.

[TheGreyGhost]

Hi

 

There isn't much around to be honest.  Some of the Forge documentation is really good, some of it... isn't.

 

I have put together some things myself about how vanilla works, enough to help folks get a grasp of the basic concepts and how the various bits hang together, but isn't not comprehensive by any stretch (and it's currently based on 1.6.4, which is a bit different to 1.7.2 sometimes).

 

http://greyminecraftcoder.blogspot.com.au/p/list-of-topics.html

 

Most of the time, I find a useful strategy is

1) think of a vanilla object that does similar to what I want

2) look at the code, flip back and forth until I figure out how it works (can sometime take a while!) and then test it myself.

 

-TGG

 

[crazycodr]

I'll need to check out your docs, but right off the start, it looks good. At least, that's some documentation.

 

Looking at the javadoc comments and interpretting obfuscated source code... that has to be even less efficient than watching 15h of video tutorial about someone trying to do something and not knowing how to explain and do it

[jabelar]

Looking at the javadoc comments and interpretting obfuscated source code... that has to be even less efficient than watching 15h of video tutorial about someone trying to do something and not knowing how to explain and do it

 

@crazycodr, I think you have to understand what Minecraft modding is.  Minecraft was not really meant to be modded -- so Mojang does not document and in fact obfuscates their code.  So any modding has to essentially be reverse engineered by the community of interested modders.  The people that are reverse engineering it are (as far as I know) essentially a volunteer group that is painstakingly tracing the undocumented result of decompilation and creating mapping to human-readable method and field names and adding comments to the code.  Then there is FML and Forge, which again are volunteer group adding hooks to the code to make it easier to intercept and interact with the vanilla code.

 

The key here is that this is volunteer community.  So the work is incomplete and inconsistent, and even buggy at times.  There are some functions that are well understood and named well and documented well, and there are others that are still called something like f_423435_a() with no documentation at all.  I've found bugs where things are mis-named, sometimes dangerously (i.e. the logic is backwards).

 

Lastly, every time Mojang does a major update the entire process has to be done over again.  That is why there are only a couple supported versions of Forge (common are 1.6.4 and 1.7.2) and frankly 1.7.2 is still a work in progress (although it is pretty useable now).

 

Basically I'm saying you're asking for too much.  There is no commercial company providing this, there are several different contributors that are loosely working together, and it is still a work in progress.

 

So the best way to learn it is simply to follow the decompiled source provided and put that together with your knowledge of Minecraft (like if you see code that treats an anvil differently, you should know that is because an anvil is different in behavior in Minecraft) and get hints from tutorials.

[crazycodr]

Give that man a jar of cookies for that answer.

 

Thank you for explaining that Jabelar, but i still think, for the good of the whole minecraft modding community, there should be a documentation effort put in place. It would help all modders get the best of Forge and Minecraft... Yes, the work has to be done again on each new supported version but hey, the code can move, but it's not a whole new version each time, some principles stay, some change. So creating a multi-version documentation shouldn't be too hard.

 

If you think at how much time is put all around the web at people creating countless video tutorials, text tutorials and then all the work put into the forums to help each other, i'm sure it possible to convert a bit of that into a documentation base that can be reused over time.

 

I actually like documenting a lot, and if there is support from the community, i wouldn't mind putting my efforts into documenting Forge, FML and Minecraft along with directing a small team of dedicated people that want to make this possible.

 

What would be the best way to launch this initiative in your opinion?

[jabelar]

I like documentation too.  That is why I've been trying to write a number of text tutorials that actually explain (rather than just give example).

 

Since it is a really big project and I assume you'd want to allow multiple contributors, I think wiki format would be suitable.  But I think the problem is still the format of the information.  Do you want this to just be a simple API documentation where every public method is explained? 

 

The question then is what the level of explanation is.  For example, listing methods and parameter types isn't much more useful than the code itself in my opinion.  That is why I've been concentrating on tutorials -- they may be haphazard in terms of topics covered, but when they cover a topic a tutorial give a lot of explanation that is difficult to document except in the context of trying to implement something specific.

 

Anyway, can you give an example of what kind of documentation you're really interested in providing/collecting?

[crazycodr]

I think that documentation must always focus on 3 aspects:

 

- Concepts : They explain the general item of something or a group of things. For example, a really important aspect to conceptualize in minecraft is the concept of Items and Blocks. It's the first thing a modder will want to do and the first thing that every modder should know how to handle.

 

- Tutorials : They explain how to achieve something. Direct links from the concept pages would link to those tutorials. So, how to do your custom "furnace" or "crusher" or "mechanical block", how to create blocks with adaptive structure (block lookups), etc.

 

- Reference : Listing of the different classes and parameters using a javadoc analyser to extract that information. Someone that doesn't know where to look in the code is bound to look for a long time. A well defined wiki with a search engine is always faster to find what you are looking for. User comments, examples, links to corresponding tutorials maybe, etc.

 

The documentation would use a Wiki approach for sure, we need to make version branches so we can keep the whole documentation for each version change. I think documentation should not be open to all, but thats me, i think it's a collective decision of all the initial writters that has to be taken into account.

 

What do you think?

[crazycodr]

I found something interresting this morning that can simplify our work greatly and promote easier collaboration on the documentation aspect of Forge and Minecraft.

 

First of all, I love Markdown as a documentation language. Is it very similar to most wiki language but just better and it's pretty much a standard now in community based projects due to GitHub's adoption of it. GitHub flavored markdown is even better at this and there are libraries to parse github flavored markdown and render it to HTML.

 

How i see the reference being built is by generating a markdown documentation using a javadoc scanner and you push the changes to a GitHub profile. The rest of the documentation can simply be another folder in the doc, one for tutorials and one for concepts. So you'd have folders like :

 

• 1.6.4
  
  • Concepts
    
  • Tutorials
    
  • Reference
    

   

  [*]1.7.2

  • Concepts
    
  • Tutorials
    
  • Reference
    

 

People can fork the documentation and issue pull requests to update the documentation... Makes it simpler to review changes and promotes community work. And then, we could have a server that check's out the documentation from GitHub and use "http://parsedown.org/" to render it to HTML and get it styled easily.

 

What do you think?