Engine/docs/docs/welcome.md

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).