GC3 API

From Galacticraft Wiki
Jump to: navigation, search
This tutorial is for Galacticraft 3 and Minecraft 1.7.10. For later versions, adapt accordingly.

Introduction

The API allows you to code Add-ons for Galacticraft. For example it could be new planets, new rockets, or new displays for the Display Screen. (The API can also be used by other mod authors for specific compatibility reasons, for example compatibility with Galacticraft's energy systems.)

You should not normally need to include the Galacticraft API in your finished .jar - just include GalacticraftCore as a dependency, like this: @Mod(name = "Your Mod Name", version = "1.0.1", useMetadata = true,

modid = "YourModID", dependencies = "required-after:GalacticraftCore;)"

While developing your Add-on, you will need to either:


Prerequisites

  • You know a little bit of Java
  • You have an IDE installed, such as Eclipse (recommended) or Netbeans
  • You have some understanding of the principles of Forge modding, or you are at least comfortable googling what you do not know. Micdoodle8 actually wrote an excellent + easy to understand series of modding tutorials a while back (2013) and most of it is still relevant: [Tutorial].


Also and most importantly, you must have successfully installed Forge sources for Minecraft 1.7.x (1.7.2 or 1.7.10) in your IDE at least once!

Installing Forge sources the first time is not so easy to do - it's hard to find a good clear guide to it online. The basic principles are like this. This is not a complete guide, so if it does not work for you maybe Google some of the words used here (like setupdecompworkspace) or go search the MinecraftForge forum.

  • Install the vanilla version of Minecraft you want to develop for and login to the game once, this is just to make sure that's all set up OK with the correct libraries downloaded
  • Download Forge source and unpack the zip to the folder you want to use as a workspace
  • From that folder, from the command line, run Gradle with a setup script for Forge. Note depending on how your PC and OS are setup already, to get that to work correctly you might first need to download the JDK and/or Gradle and/or Maven or add paths for those to your environment path.
  • The intended way to set up Forge is to run two setup scripts, like this:

gradlew setupdecompworkspace

gradlew eclipse

(Use gradlew on a Windows machine, on a Mac or Linux machine it's just gradle.)

    • The first script, which is slow (10 minutes or longer), decompiles and deobfuscates Minecraft locally on your PC (like setting up MCP in older versions of Minecraft). To be exact, it generates decompiled Forge, Forge fmled, Forge fmlinjected, Forge mcped, Forge source nojd, Forge srg and Forge source. It then prepares all that to be available to your IDE as a referenced library named forgeSrc-1.7.10-[version].jar. Specifically, it generates Forge javadoc, Forge bin patches, Forge binaries, and the forgeSrc file which is all of that in the form of a library jar.
    • The second script sets up a basic IDE workspace with that library jar referenced - this one is for Eclipse and the decompiled vanilla + Forge sources should be in your workspace in the Referenced Libraries group.
  • If you get into trouble setting up, try running the same scripts again, in the same order, adding clean and --refresh-dependencies, like this: gradlew clean setupdecompworkspace --refresh-dependencies.
  • Sometimes the vanilla Minecraft and Forge classes in your IDE may have no source code. In this case you can add their source code by linking to another forgeSrc file with a filename ending: -sources. The location of this file seems to vary according to Forge version or maybe according to the steps you took to set up Forge, but try looking in the folder build\dirtyArtifacts in your workspace, or else in %USERPROFILE%\.gradle\caches\minecraft\net\minecraftforge\forge\ (that's on a Windows machine).

Galacticraft API

  • Download the full Galacticraft sources from Github - either use Git locally or from a Code page on Github you can download a Zip file with the sources
  • Out of those sources, copy into your workspace only the folder src/main/java/micdoodle8/mods/galacticraft/core/api ([here])
  • The API will have some compile errors, because it references other parts of the Galacticraft source in a few places, for example in the prefab classes, and you didn't copy the main Galacticraft sources for those. There are two ways to go here:
    • If you do not need these erroring parts of the API for your Add-on, just delete those classes of the API from the copy of the API in your source folder and everything else should be good to go - for example you can probably delete the whole prefab folder
    • If you do need the erroring parts of the API for your Add-on, then you will need to copy the Galacticraft .jar files into your workspace and use them as a library - take the .jar files from the dev/de-obf versions of Galacticraft (see link on main download page) that is what these are for.


The Dev version of Galacticraft (access it from the usual [downloads] page) is a compiled copy of the Galacticraft .jar for use in a de-obfuscated Forge environment - for example it can be used as a library, and if you run Minecraft from inside your IDE it should also be playable. You will need the Dev version of MicdoodleCore as well, of course.

We cannot support crashes or failure to launch the dev version of the game: people using it are expected to be experienced coders able to sort out these issues for themselves. But you can find help from other Add-on authors at the Galacticraft [forum].

Full Galacticraft Sources

Maybe you need the full Galacticraft sources in your IDE because you are patching or customising Galacticraft, or you want to submit a Pull Request.

You need two sets of source files: the Galacticraft project (which includes Galacticraft-Planets) and the MicdoodleCore project. These are designed to be used together, and both are needed in your project folder.

The sources off of the Github should drag and drop into a Forge workspace for Minecraft 1.7.10 (or any later version up to 1.12.2) and compile correctly, if you do one important thing first:

  • First, you will need to setup Forge again with access transformers, which change the visibility of a few classes in vanilla Minecraft.
  • The access transformers you will need are [micdoodlecore_at.cfg] and [nei_at.cfg] (later versions of Galacticraft, for example GC4, may need only micdoodlecore_at.cfg, check the resources folders for MicdoodleCore project and Galacticraft project, dependencies files)
  • With both of those access transformers in your Forge workspace - it's best to copy those two files into src/main/resources - you will need to rerun the Forge gradle script gradlew setupdecompworkspace


If you did that correctly, everything should just work afterwards: you should have the exact same workspace as the mod developers have, and Galacticraft should compile error-free - you should also be able to run the game from inside your IDE.

Note that to be precise, your Forge workspace needs to use the same (or similar) Forge version and MCP mappings as the ones which our source code targets. Look in the build.gradle file to see which versions we use.

Also if running the game inside a dev environment for Minecraft 1.12.2, you will need to set JVM argument: -Dcofh.rf.crashOnOldAPI=false. It's because the cofh api included as a dependency in the codebase actually installs itself as a mod and runs a startup check - alternatively just delete the preInit check in cofh.redstoneflux.RedstoneFlux.java.


The downloaded project files from Github include a few dependencies - those are needed so that Galacticraft has the imports needed to compile correctly. Compiling the project will compile those dependencies as well, but except for the TConstruct client tabs, do not include the compiled dependencies in any production .jar. The dependencies are, in the main, APIs from other mods, recent enough so that the Galacticraft code compiles correctly, but they might not be the latest versions of those other mods' APIs and you certainly don't want to be distributing them!

If for some reason you are developing in a Minecraft 1.7.2 environment then the Galacticraft sources should still compile correctly - Galacticraft is dual compatible with 1.7.2 and 1.7.10 - but some of the dependencies will not. You can either replace the dependencies with equivalent sources from the 1.7.2 version of the other mod's API, or find some other way to fix it.