forked from StarOpenSource/Engine
89 lines
5.2 KiB
Markdown
89 lines
5.2 KiB
Markdown
# 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
|