Changes to IntelliJ IDEA configuration


New Member
Oh hello forum! We merged a significant change to the developer set-up process this week. Thought it might be worth a post to give a heads-up to those of you who didn't hear about it on Discord.

For quite a while now, the guides on how to set up IntelliJ IDEA for Terasology development have said “Do not import the gradle project! Run gradlew idea instead!”

Now it is just the opposite: please do have IntelliJ import the Gradle project, and you do not need to run gradlew idea.

See #3954 and its follow-up #3974 if you want all the messy details, but the technical highlights are:

  • Works with IntelliJ IDEA version 2020.1 (and newer, hopefully).
  • The project no longer uses the old .ipr file format. It uses the .idea/ directory instead.
  • We are keeping much of that directory in version control; it is not git ignored. I wrote a bunch about the merits and pitfalls of version-controlled .idea. I could cross-post that to this forum or the wiki if that would be useful.
  • It works with JDK 11. Using JDK 8 for Terasology development is still supported, but this configuration assumes that you're using 11, and IDEA even has a download-a-JDK option built-in that can help with that.
I think those are the most important highlights. If you're attached to your current configuration, you probably want to back up your Terasology.ipr and Terasology.iws files.

I think we've caught all the places that talked about gradlew idea on the wiki. I still have some ambitions about freshening up the docs on preparing a development workspace, but I think the current version is at least not-misleading.

I'm not entirely sure what the best migration path is if you do want to merge in your prior workspace settings. I expect it's something like this:

  • back up ipr and iws
  • upgrade to IntelliJ IDEA 2020.1 if you haven't yet
  • Use the "Save as directory based format" action in the file menu. That will make the .idea/ directory with your settings.
  • back up that, so you have a backup of the directory-based settings
  • pull changes from git, merge its configuration directory with yours
  • Import Gradle Project if you haven't yet
If you run in to conflicts with files in that config directory, do ping me on Terasology discord or in a GitHub issue and let me know. I expect we'll need to continue to tune the ignore files a bit.

Pleasure onward, my associates!