Developing

So, you want to develop for the Electrical Age codebase? Find a bug with a component? Are we missing the killer feature for your use case? Want to add some pretty artwork? Look no further!

This document assumes you would like to do more than just submit an issue telling us about your bug or request. While we appreciate all of the issues, do note that we're open-source developers working on this project for free in our spare time, and it can be very hard to improve it by ourselves. Thus, if you want to take the initiative to improve it on your own, please go ahead--we greatly appreciate it! The rest of this article should acquaint you with what you need to work on your own.

Getting Started

The mainline Electrical Age codebase is maintained on GitHub, along with numerous forks maintained by other developers. If you're intending to modify the source (to propose a bug fix or new feature), you should create a fork and clone from your own repository. Otherwise, if you're just looking to build from source (including, perhaps, the latest features not yet available in the downloadable JARs), go ahead and clone from mainline, or the fork you want to try.

Note: A Git repository, like the one you're cloning from GitHub, is a standalone copy of the project and all of its history. It's likely to be large, so avoid doing it on a metered or slow connection. Once you have it, however, you can contribute to the history locally, and--if you're on your own fork, or have permission from the repository owner--push that history back to GitHub when you're ready. Check out some beginner documentation on using Git to get started, and feel free to ask us if things go awry.

Before you do any work, you should make sure you can get a working build on your system. Electrical Age requires both a Java 1.8 SDK and a Kotlin SDK (recommended 1.3 or greater for development builds). To do the initial build:

On UNIX-like systems (basically, not Windows): Open a terminal, cd to the repository you cloned, and execute:

$ ./gradlew runClient

(where $ is your shell prompt--don't actually type that.) Additionally, if you have a local install of Gradle, which you can probably install through whatever software manager you have on your system, you can use that in lieu of ./gradlew.

On Windows: Basically the same: run a Command Prompt (or cmd.exe; you can find it in the Start Menu if you search for it), cd to the cloned repository, and run

> gradlew.bat runClient

(where, again, > is your prompt--don't type it.) If you're afraid of the command prompt, you can put that line in some ".bat" file (e.g. runClient.bat) inside the repository, and double-click it. (You can do this from Notepad, but make sure to select "All files" from the "Save As" dialog, or it might name it runClient.bat.txt.)

From IDEA (all platforms): Import a project consisting of the repository you just cloned, and add a Gradle configuration for the target "runClient". (This setup is especially useful for developers, because you'll have access to the source to modify at your whim right afterward.)

Other IDEs: Probably the same as above, but consult your IDE's documentation. At worst, you may have to figure out how to tell it to run one of the command prompt/terminal commands above.

Project Structure

If you want to make changes, it's very wise to have a good Java IDE set up; being able to cross-reference is an incredibly valuable tool for large projects like this. (I personally recommend IntelliJ IDEA, but the choice is ultimately yours.)

From the root of your repository, you should see:

• README.md: The "README" file that GitHub presents on the front page of the repository. You can change this in your own fork to reflect your changes, for example.
• LICENSE.md: The license of distribution. If you've created a fork, you're creating a derivative work, and this grants you the right to do so. Electrical Age's source is licensed under the LGPL v3, which means you must preserve the right for others to copy your work, too. Similarly, the assets are CC-BY-NC-SA 3.0, which means you must give credit if you use them elsewhere, only for non-commercial purposes, and you have to retain that license with them. See the file itself for details.
• src: The all-important source code directory. If you're modifying the code or assets, this is where you'll spend most of your time. Check out the codebase for a tour of what exists in and below here.
• libs: Some JAR files that represent linked libraries. As of this writing, this includes the Apache Commons math libraries, as well as an API for IndustrialCraft. If you want to add compatibility with another mod, and they provide an API, this is a likely place to put it for use.
• script: Some scripts, ancillary to the project. This includes Blender exporters, and some repo-checking tools.

Additionally, if you've already built the client as above (which you should before starting, to be sure that you can), you might see a few more directories, which you do not need to keep track of in Git:

• build, out: Generated by your IDE or Gradle, these contain the build artifacts for the project (the compiled code). This is what gets packaged into a JAR file.
• run: Set up by Gradle, this is the ".minecraft" directory for the local instance of Minecraft. It has all of the usual ".minecraft" content, like screenshots, saves, config, mods, etc. . Note that mods doesn't contain the Electrical Age mod JAR in this build--it's compiled in by the build process instead.

Next Steps

Assuming you've gotten a running copy, and you're looking to develop, you should continue with a tour of the codebase.

If you want to give out a copy of your work to your friends, run Gradle as above, but with jar instead of runClient. The output, under the repo, will be in build/libs. Be careful distributing this JAR if you've changed the code; unless you changed the version, too, it will attest as being "the same as" the mainline ELN distribution, which is probably not what you want to advertise when you connect, e.g., to a "vanilla" ELN server. Please also remember that, if you're distributing your built JAR files, you must push your work to your fork to remain in compliance with the LGPL.