93 lines
5.6 KiB
Markdown
93 lines
5.6 KiB
Markdown
---
|
|
sidebar_position: 0
|
|
title: Welcome
|
|
---
|
|
|
|
# sos!engine documentation
|
|
Welcome to the documentation for the StarOpenSource Engine!
|
|
<!-- StarOpenSource Fly verification links -->
|
|
<link href="https://fly.staropensource.de/@staropensource" rel="me"/>
|
|
<link href="https://fly.staropensource.de/@sosengine" rel="me"/>
|
|
<link href="https://fly.staropensource.de/@soscore" rel="me"/>
|
|
<!-- StarOpenSource Fly verification links -->
|
|
|
|
## 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](https://git.staropensource.de/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](https://en.wikipedia.org/wiki/Object-oriented_programming),
|
|
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](https://github.com/SpongePowered/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](https://jruby.org). Want to compile your entire Java codebase
|
|
to JavaScript for usable on the web? [TeaVM has you covered](https://teavm.org/).
|
|
Want to compile your Java code into binaries for fast execution?
|
|
[There exists GraalVM native-image](https://www.graalvm.org/latest/reference-manual/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](https://git.staropensource.de/StarOpenSource/Engine/issues/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](https://en.wikipedia.org/wiki/Unix_philosophy).
|
|
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 two 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`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/ansi): Provides an ANSI logger and a ShortcodeParserSkeleton implementation for all your terminal formatting needs
|
|
- [`slf4j-compat`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/slf4j-compat): Provides a [SLF4J](https://slf4j.org/) compatibility logger for redirecting all log calls to the engine's logging system
|
|
### Experimental
|
|
- [`rendering`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/rendering): Provides an API for creating, managing and rendering windows
|
|
- [`notification`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/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](https://jd.engine.staropensource.de).
|