Engine/README.md

# StarOpenSource Engine
The StarOpenSource Engine (or sos!engine for short) is a modular, extensible and easy to use Java game and application engine.

## WARNING
The StarOpenSource Engine is under heavy development and is extremely unstable. Code will break often, prepare for potential major refactors when trying the engine out.

## Index
- [About](#about)
  - [... the engine](#-the-engine)
  - [... the repository](#-the-repository)
  - [Priorities](#priorities)
- [Documentation](#documentation)
- [Contributing](#contributing)
  - [Requirements](#requirements)
  - [What IDE to use?](#what-ide-to-use)
  - [Code style](#code-style)
  - [Pull request guidelines](#pull-request-guidelines)
  - [Making your first contribution](#making-your-first-contribution)
  - [Gradle properties](#gradle-properties)

## About
### ... the engine
The StarOpenSource Engine is a modular and extensible framework for building applications and games written in [one of the multiple JVM programming languages](https://en.wikipedia.org/wiki/List_of_JVM_languages).
The engine consists of various subsystems, each separate and responsible for only a few closely-related tasks.
 \
Not only that. The engine also features various useful classes, interfaces and methods making development fun and simpler, while being lightweight.
### ... the repository
The sos!engine repository is a monorepo, consisting of [the core engine](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/base), multiple official subsystems and [their documentation](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/docs).
### Priorities
These are in no particular order.

- configurable
- [do one thing and do it well](https://en.wikipedia.org/wiki/Unix_philosophy) (subsystems concept)
- fast
- few runtime dependencies (note: we will cut down on some of them during development)
- modular & extensible
- small & lightweight

## Documentation
You can view the engine documentation at [engine.staropensource.de](https://engine.staropensource.de). It provides information, guides and tutorials about the core engine and subsystems.
If you want the API reference, you can [visit the Javadoc](https://jd.engine.staropensource.de) for the engine and it's subsystems.

## Contributing
### Requirements
You need the following things to be able to contribute code to the StarOpenSource Engine:
- knowledge of Java
- knowledge about the internals of engine
### What IDE to use?
We recommend and are using [IntelliJ IDEA Community Edition](https://github.com/JetBrains/intellij-community) for development because it is flexible, extendable, customizable, provides good completions and error detection. It's also open source.
### Code style
We recommend looking at existing classes and code for a good understanding on how we'd like code to be written.
Here's a quick rundown on the most important things:
- Document EVERYTHING. Every single class, field and method, even if private.
- Make comments about your code, unless it's extremely simple and easy to understand.
- Make sure to add and update `@since` in javadoc comments (update if the javadoc changes a good amount).
- Keep stuff simple, no need to elaborate what a logger is. Though remember to not make it *too* simple.
- Make sure every field and method has a newline to separate it.
- Files must end with a newline or cats might get angry.
- Use your brain.
### Pull request guidelines
Before creating a pull request, make sure you've:
- created tests for the functionality you've added, changed or removed (if applicable),
- tested your changes,
- made sure that everything works,
- is compatible with other code in the monorepo, and
- is compatible with other applications. If not, tell us in your pull request description.
### Making your first contribution
TODO
### Gradle properties
Gradle's behaviour can be changed by changing gradle project properties.
To change them, simply append `-P<property>` or `-P<property>=<value>`, like this: `./gradlew -Pjobs=4 test`.
#### Parallelism
Use the `jobs` property to control how many jobs will get executed simultaneously.
On Linux, specify `-Pjobs=$(nproc)`. Defaults to `8`.
#### JVM Home
You can use the `graalHome` property to specify the `$JAVA_HOME` of your local GraalVM installation.
Only used in the `nativeImage` task. Useful if you aren't using GraalVM as your primary JDK.
#### Testing
You can use the following properties to modify the behaviour of the `test`-task:
- `test.control.mode` (default *empty*)
  - `force-enable`: Disables all test classes except the ones specified
  - `force-disable`: Enables all test classes except the ones specified
  - *everything else*: Enables all test classes
- `test.control.classes` (default *empty*): A comma-separated, case-sensitive list of test classes
  which (depending on `test.control.mode`'s value) enable or disable the specified classes.
  Example: `-Ptest.control.mode=MiscellaneousTest,DependencyResolverTest,EngineConfigurationTest`
- `test.control.warning` (default `false`): If `true`, will emit a warning before a restricted test method exits
- `test.loggerLevel` (default `silent_warning`): Will set `UnitLogger`'s logger level.
  Works like `-Dsosengine.base.loggerLevel`. See `UnitLogger#loggerLevel` for more information