Skip to main content

sos!engine documentation

Welcome to the documentation for the StarOpenSource Engine!

What is it?​

The StarOpenSource Engine (or sos!engine for short) is a modular, extensible and easy to use Java game and application engine.
It is responsible for printing log messages, providing utility methods, creating and managing windows, playing audio and much more.

There are n different game engines and application frameworks. Why another one?​

True, there are many game engines and application frameworks out there. I (JeremyStarTM) however have never seen an engine or framework be modular, extendable and easy to configure at the same time. Additionally, we intend on supporting applications and games. This means that you don't need to remember different APIs for your different projects and can instead focus on just one, perfecting your skills along the way.

Why Java?​

Java. Some say it's an awful language. We disagree, strongly.

While it has some pitfalls, it's almost the embodiment of OOP, providing the perfect base for creating a modular engine and framework like the sos!engine.

Additionally, because of it's interpreted nature it's easy to modify the bytecode at runtime and perform various things to it before it's executed. This isn't really doable in other programming languages easily. Just see what Minecraft modders are doing to the game using the Mixin framework. It's a perfect example.

Also important to note is Java's portability. Yes, it has it's constrains in some cases (like when accessing files), but these can be worked around easily (see our FileAccess class for an example). But generally, the code is portable. There's no need to cross-compile for different CPU architectures and operating systems. You don't have to deal with compilers and their 581^51 ways of configuring them. Just javac your source tree, pack your compiled bytecode into a .jar and you're good to go.

Lastly, you can use and mix various languages and compile them to different things. Have Groovy code and want it to interact with Java code? That works! You want to use Ruby to create a game using the sos!engine? You could do that. Want to compile your entire Java codebase to JavaScript for usable on the web? TeaVM has you covered. Want to compile your Java code into binaries for fast execution? There exists GraalVM native-image. Once you've written your Java code you can compile and interact with it however you like. As far as I know no language is as good in this aspect as Java.

And these are the reasons as to why we use Java over C++, Rust or other languages for example. While yes, performance naturally suffers a bit, the JVM and computers in general have improved heavily in performance over the years. From the slow thing Java once was it's almost as fast as compiled code on modern machines. Most of the time you don't notice the difference. And if performance is your concern, use GraalVM native-image as described above (note: the StarOpenSource Engine does not yet support native-image, see #3).

Architecture of the engine​

The engine is built as a modular system, containing the core engine (called base) and various different subsystems.

The job of the core engine is to provide a logging system, utility methods, ways for subsystems to seamlessly function and much more required for building applications.

Subsystems on the other hand usually handle complex tasks. They usually provide abstractions for libraries or handle complicated tasks. "But why are there so many of them?" you might ask. Good question! Subsystems are intended to do one thing and do it well. This avoids unnecessary bloat, having too many dependencies in your project while reducing the size and memory footprint of your project.

Official subsystems​

Besides the base engine, there are two stable subsystem and three experimental subsystems.

There may be other subsystems out there. Please note though that they are not maintained by the StarOpenSource Project directly and are not automatically updated with the engine.

Stable​

  • ansi: Provides an ANSI logger and a ShortcodeParserSkeleton implementation for all your terminal formatting needs
  • slf4j-compat: Provides a SLF4J compatibility logger for redirecting all log calls to the engine's logging system

Experimental​

  • windowing: Provides abstract APIs for creating and managing windows as well as monitors
  • windowing-glfw: Windowing API; allows using GLFW for creating windows
  • notification: Provides an API for sending and receiving notifications inside a program

API documentation​

To read the engine API documentation, visit jd.engine.staropensource.de.