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
  • ... the engine
  • ... the repository
  • Priorities
• Documentation
• Contributing
  • Requirements
  • What IDE to use?
  • Code style
  • Pull request guidelines
  • Making your first contribution
  • 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. 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, multiple official subsystems and their documentation.

Priorities

These are in no particular order.

• configurable
• do one thing and do it well (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. It provides information, guides and tutorials about the core engine and subsystems. If you want the API reference, you can visit the Javadoc 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 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