Engine/README.md

90 lines
5.2 KiB
Markdown
Raw Permalink Normal View History

2024-06-08 15:33:03 +02:00
# StarOpenSource Engine
2024-06-27 20:25:32 +02:00
The StarOpenSource Engine (or sos!engine for short) is a modular, extensible and easy to use Java game and application engine.
2024-06-08 15:33:03 +02:00
2024-07-29 22:45:07 +02:00
## 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.
2024-06-08 15:33:03 +02:00
## Index
- [About](#about)
2024-07-29 22:45:07 +02:00
- [... the engine](#-the-engine)
- [... the repository](#-the-repository)
2024-06-08 15:33:03 +02:00
- [Priorities](#priorities)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Requirements](#requirements)
- [What IDE to use?](#what-ide-to-use)
- [Code style](#code-style)
2024-07-29 22:45:07 +02:00
- [Pull request guidelines](#pull-request-guidelines)
2024-06-08 15:33:03 +02:00
- [Making your first contribution](#making-your-first-contribution)
- [Gradle properties](#gradle-properties)
2024-06-08 15:33:03 +02:00
## About
2024-07-29 22:45:07 +02:00
### ... 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.
2024-07-29 22:45:07 +02:00
\
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).
2024-06-08 15:33:03 +02:00
### Priorities
2024-07-29 22:45:07 +02:00
These are in no particular order.
- configurable
2024-06-11 23:12:48 +02:00
- [do one thing and do it well](https://en.wikipedia.org/wiki/Unix_philosophy) (subsystems concept)
2024-07-29 22:45:07 +02:00
- fast
- few runtime dependencies (note: we will cut down on some of them during development)
- modular & extensible
- small & lightweight
2024-06-08 15:33:03 +02:00
## Documentation
2024-07-29 22:45:07 +02:00
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.
2024-06-08 15:33:03 +02:00
## Contributing
### Requirements
2024-06-11 23:12:48 +02:00
You need the following things to be able to contribute code to the StarOpenSource Engine:
2024-06-08 15:33:03 +02:00
- knowledge of Java
2024-06-11 23:12:48 +02:00
- knowledge about the internals of engine
2024-06-08 15:33:03 +02:00
### What IDE to use?
2024-07-27 12:42:34 +02:00
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.
2024-06-08 15:33:03 +02:00
### Code style
2024-07-29 22:45:07 +02:00
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.
2024-07-29 22:45:07 +02:00
- 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.
2024-07-29 22:45:07 +02:00
- 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),
2024-06-08 15:33:03 +02:00
- 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
2024-07-11 23:29:35 +02:00
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