Terasology/docs/Contributor-Quick-Start.md

Required Knowledge

• Git Basics - We use Git for version control, so you should be familiar with the concept of branches, fetching and committing changes, and pushing to a code repository.
• GitHub Basics - We host our code on and collaborate via GitHub, so you should be familiar with repositories, pull requests, and forks.
• Bash Basics⁰ - While you can avoid the command-line in most situations, in some situations you'll need to use it, for instance to fetch additional modules into or update your workspace. Especially, any groovyw or gradlew commands you find in our documentation need to be executed from the command-line.

Required Tools

• Java 11 JDK (e.g. OpenJDK 11 from AdoptOpenJDK)
• Git Client (e.g. Git for Windows or GitKraken)¹
• IDE (e.g. IntelliJ²)

Set up your Terasology Development Workspace

1. Clone https://github.com/MovingBlocks/Terasology to a local workspace
2. Change into the new "Terasology" directory
3. Grab our module foundation ("iota" line-up)³
   • groovyw module init iota⁴
4. (Optional) Open your workspace directory into IntelliJ; choose "Import Gradle Project" if prompted.
   • Note: Simply open the directory, don't pick "New Project". Our Gradle config will setup the project for you.
5. Compile and start Terasology from source for the first time
   • On the command-line, use gradlew game
   • In IntelliJ, run the "TerasologyPC" run configuration
6. Select the "CoreSampleGameplay" gameplay
7. Start the game

Start a Custom Basic Gameplay

1. Grab additional modules and their dependencies
   • groovyw module recurse <module> will fetch all the modules used by that in source form
2. Compile and start Terasology (see #Dev-Setup)
3. Select "CoreSampleGameplay" and click on "Advanced Game Setup"
4. Double-click on the module you grabbed to activate it
5. Start the game

Get Help when Facing Issues

• Check out our wiki pages on Troubleshooting
• Join our community on Discord and ask questions

Start Contributing

• Take the Gooey Tour to find resources for the contribution area you're interested in
• Look through the code, change small things and see how they affect your game
• Find some "Good First Issues" to work on
• Code and test your changes locally in-game
• Push to your fork for engine changes, create module forks and push module changes there
• Make PRs and ask the community for review

Check out the general contributing guidelines.

Go deeper

You can read through the intro topics for more details on exactly how to set up and develop.

• Resources for Learning Git & GitHub
  • Recommended Git Tutorial
  • Recommended GitHub Tutorial
• Codebase Structure
• Module Dependencies - explains how you can have module X depend on module Y even at a specific version level
• Developing Modules - shows you how to interact with and organize modules that hold most the content for the game
• Advanced Gradle and Groovy usage: take a look at gradlew tasks and groovyw usage
• Using Locally Developed Libraries

Notes

0 If you feel more comfortable on other shell types, e.g. fish, zsh, powershell, etc. that's fine. ↩

1 For Windows users, we highly recommend Git for Windows which comes with both, a GUI client and shell integration for Git, and in addition brings the Git Bash which allows Windows users a unix-style command-line experience. ↩

2 We recommend IntelliJ, because we have a series of customizations that prepare run configurations, Git integration, and so on for the project. You can use any IDE (or none at all) that you like, however you will not be able to benefit from these customizations. ↩

3 To get all modules that are part of our release, grab the "omega" line-up instead. Please note, that this line-up requires more memory and time for compilation and start-up. Check our Index repo to see all available line-ups. ↩

4 Please note, that both gradlew and groovyw are scripts locally present in your workspace root directory. On *nix systems, you can execute them from within the root directory by prefixing them with ./. ↩