The BetonQuest Organisation recommends IntelliJ (Community Edition) as the IDE (Integrated Development Environment). The advantage of using IntelliJ is that this guide contains some steps and the project contains some files that help to fulfill our requirements regarding code and documentation style. You can still use your preferred IDE, but then you need to check on your own that your changes fulfill our requirements.
First download IntelliJ and install it.
After you installed IntelliJ, we recommend installing the plugin Save Actions. The plugin automatically formats code, organizes imports, adds final modifiers, and fulfils some other requirements we have. You don't need to configure that plugin, the project contains the configuration file.
Check out the repository🔗
You need a Git installation to be able to check out code from GitHub. You can follow this guide if you don't know how to install Git.
Then you should fork the BetonQuest repository to your own account on GitHub.
After you have set up the IDE, clone the BetonQuest repository from your account. You can also directly clone the repository in IntelliJ.
In case videos and images are missing after cloning
We use Git LFS to store big files like media files, so you need to install that too.
Once you have executed the file that you downloaded from the Git LFS website, just run
git lfs install.
git lfs pull to actually download the files.
Adding remote repository🔗
In IntelliJ click on
Git in the left upper corner and then
In the new window you already see a remote called
origin. This remote is your fork of BetonQuest.
Now add a new repository with the name
upstream and the url
Formatting for .md (Markdown) files can break some features of
Material for MkDocs, so we disable it for these files.
File/Settings/Editor/Code Style then go to the
Formatter tab and add
*.md to the
Do not format: field.
File/Settings/Editor/Code Style/Java navigate to the
You will now configure when to use star imports, in general we don't want them at all, but there are some exceptions.
Class count to use import with '*': and
Names count to use static import with '*': to
Packages to Use Import with '*' configure the following:
Now we enable some automatic checks, when you commit things, that ensures everything is fine.
Commit tab click on the icon near the
Amend checkbox. Check the following entries under
- Reformat Code
- Rearrange Code
- Optimize Imports
- Analyze Code
- Check TODO (Show All)
Building the Plugin jar🔗
You can build the plugin with Maven. Sometimes, IntelliJ auto-detects that BetonQuest is a Maven project. You can see
a "Maven" tab on the right side of the editor if that's the case. Otherwise, do this:
First, open the "Project" tab on the left site. Then right-click the
pom.xml file in the projects root folder.
Select "Add as Maven Project".
At this point it is always recommended to run
mvn verify to check if the software builds fine before making any changes.
To build the BetonQuest jar, you also run
You can do this from the command line or use IntelliJ's
Maven tab (double-click on
You can then find a
BetonQuest.jar in the newly created folder
Build speed up🔗
As BetonQuest has a lot of dependencies, the build can take a long time, especially for the first build.
By default, the build speed up is only enabled when running Maven from the command line, but not when using IntelliJ.
To enable it, go to
File/Settings/Build, Execution, Deployment/Build Tools/Maven and check
Use settings from .mvn/maven.config.
Build on Start🔗
The first build of a day can take a while, because every version gets re-checked once every day.
This is the reason, why an automatic build on startup reduces the time of following builds. It is really worth it to set it up.
In IntelliJ navigate to
File/Settings/Tools/Startup Tasks click on the
Add button and click
Add New Config.
Maven, set a
BetonQuest Resolve Dependencies and write
into the field
Command line. Then confirm with
Now after starting IntelliJ the
BetonQuest Resolve Dependencies task should run automatically.
Building the Documentation🔗
Make sure Python3 is installed on your local system and added to the PATH environment variable. The Python installer allows you to do so with a checkbox called something like "Add Python to environment variables".
You also need to install GTK, the easiest way is to use this GTK installer if you are on Windows.
Install all other dependencies by entering
pip install -r config/docs-requirements.txt in the terminal on the project's root directory.
In case you are a Material for MkDocs insider (paid premium version)
Set your license key by executing
setx MKDOCS_MATERIAL_INSIDERS LICENSE_KEY_HERE /M (Windows) in the terminal.
Now you need to restart IntelliJ for the changes to take effect.
pip install -r config/docs-requirements-insiders.txt instead of
mkdocs serve --config-file mkdocs.insiders.yml to preview the docs.
See your changes live🔗
Run this command in IntelliJ's integrated terminal (at the bottom) to create a docs preview in your browser:
Then visit 127.0.0.1:8000 to make sure that everything works.
You can now continue by Creating a new Branch, before you start changing Code or Docs.