JeremyStarTM/Engine
1
0
Fork 0
forked from StarOpenSource/Engine
Code Pull requests Activity Actions

Update documentation

Browse source
This commit is contained in:
JeremyStar™ 2024-11-08 22:15:25 +01:00
parent d1d8e305ed
commit 6425442c25
Signed by: JeremyStarTM
GPG key ID: E366BAEF67E4704D
5 changed files with 120 additions and 110 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/docs/getting-started/_category_.json
View file

@ -3,6 +3,6 @@
"position": 2,
"link": {
"type": "generated-index",
"description": "Contains pages explaining how to setup the sos!engine in your project."
"description": "Provides a complete guide on how to get started with the StarOpenSource Engine."
}
}

117
docs/docs/getting-started/initializing.md
View file

@ -8,8 +8,20 @@ To initialize the sos!engine, simply add this to the initialization code of your
```java
Engine.initialize();
```
... or if you want error handling (recommended):
```java
try {
Engine.initialize();
} catch (Exception exception) {
// Make sure this kills your
// game or application. This
// example is assuming that this
// code lives inside a Main class.
return;
}
```
This is enough to initialize the engine and all installed subsystems. No need to manually initialize them.
This is enough to initialize the core engine and all subsystems found in the classpath. No need to manually initialize them.
## Printing something
Now you'll probably want to print some log output. Before you try using `System.out#println`,
@ -19,104 +31,43 @@ provides it's own logging implementation and is HIGHLY recommended to be used ov
There are eight log levels you can use:
<table>
<tr>
<th>Level</th>
<th>Description</th>
<th>LEVEL</th>
<th>METHOD NAME</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<th>DIAGNOSTIC</th>
<th>Provide detailed information about what is happening</th>
<th>`DIAGNOSTIC`</th>
<th>`diag`</th>
<th>Detailed information about what is happening</th>
</tr>
<tr>
<th>VERBOSE</th>
<th>Additional information that may not be useful</th>
<th>`VERBOSE`</th>
<th>`verb`</th>
<th>Additional information about what is happening</th>
</tr>
<tr>
<th>SILENT_WARNING</th>
<th>Warnings that can be ignored or are caused by invalid (API) user input</th>
<th>`SILENT_WARNING`</th>
<th>`sarn`</th>
<th>Less important warnings. Useful for logging parsing errors and such</th>
</tr>
<tr>
<th>INFORMATIONAL</th>
<th>`INFORMATIONAL`</th>
<th>`info`</th>
<th>Useful information about what is happening</th>
</tr>
<tr>
<th>WARNING</th>
<th>Warnings about dangerous or weird behaviour</th>
<th>`WARNING`</th>
<th>`warn`</th>
<th>Warnings about dangerous, deprecated or weird behaviour</th>
</tr>
<tr>
<th>ERROR</th>
<th>`ERROR`</th>
<th>`error`</th>
<th>Non-fatal errors</th>
</tr>
<tr>
<th>CRASH</th>
<th>`CRASH`</th>
<th>`crash`</th>
<th>Fatal errors which may or may not halt the running program (see below)</th>
</tr>
</table>
Here's an example:
```java
Logger.info(getClass(), "APPLICATION", null, "Hello World!");
// ^ ^ ^ ^
// | | | |
// | | | --- The message you want to print.
// | | -------- Metadata string (can be null). If your class/method processes data or something, you can include it here.
// | ---------------------- Origin of the message. It identifies from which part of your application the message came.
// -------------------------------------- Log priority/type. In this case, we want to emit an informational message
```
Now, why do I need to supply so many arguments just for a simple "Hello World!"?
It's simple: It describes the class issuing the log call.
Here's an example:
```java
class ExampleClass() {
private @NotNull String string;
public ExampleClass(@NotNull String string) {
this.string = string;
}
public boolean checkForEscapes() {
Logger.diag(getClass(), "APPLICATION", string, "Checking for escapes");
return string.contains("\\");
}
public boolean checkIfEmpty() {
Logger.diag(getClass(), "APPLICATION", string, "Checking if empty");
return string.isEmpty();
}
}
```
Now that's nice and all, but it's annoying to pass three arguments describing your class to log methods
and will – over time – make log messages unorganized and unmaintainable. That's not good. That's why
the `LoggerInstance` class exists. It's purpose is to pass these to every log call you make. The only
thing you need to do it to is to pass it some data about your class and it does the job for you.
Here's an example of the code before, but with `LoggerInstance`:
```java
class ExampleClass() {
private @NotNull LoggerInstance logger;
private @NotNull String string;
public ExampleClass(@NotNull String string) {
this.string = string;
logger = LoggerInstance.Builder()
.setClass(getClass())
.setOrigin("APPLICATION") // If you intend on 'origin' being set to "APPLICATION", you can leave this out. This has just been included for completeness.
.setMetadata(string) // Include the string we are doing stuff with as metadata
.build();
}
public boolean checkForEscapes() {
logger.diag("Checking for escapes");
return string.contains("\\");
}
public boolean checkIfEmpty() {
logger.diag("Checking if empty");
return string.isEmpty();
}
}
```
As you can see, it's much simpler. No need to pass that to every call now!

15
docs/docs/getting-started/installing.mdx
View file

@ -80,7 +80,7 @@ dependencies {
... and add this property to the `settings.gradle` file:
```properties
# Set this to the engine version you want to use
dependencyStarOpenSourceEngine=1-alpha7
dependencyStarOpenSourceEngine=1-alpha8
```
## Maven
@ -99,13 +99,12 @@ Add StarOpenSource's maven repository to your `pom.xml` file first:
After that declare the engine as a dependency in your project:
```xml
<dependencies>
<!-- sos!engine base -->
<dependency>
<groupId>de.staropensource.engine</groupId>
<artifactId>base</artifactId>
<version>1-alpha7</version>
<version>1-alpha8</version>
</dependency>
<!-- sos!engine subsystems -->
@ -113,35 +112,35 @@ After that declare the engine as a dependency in your project:
<dependency>
<groupId>de.staropensource.engine</groupId>
<artifactId>ansi</artifactId>
<version>1-alpha7</version>
<version>1-alpha8</version>
</dependency>
-->
<!-- SLF4J compatibility
<dependency>
<groupId>de.staropensource.engine</groupId>
<artifactId>slf4j-compat</artifactId>
<version>1-alpha7</version>
<version>1-alpha8</version>
</dependency>
-->
<!-- creating and managing windows, requires a Windowing API implementation
<dependency>
<groupId>de.staropensource.engine</groupId>
<artifactId>windowing</artifactId>
<version>1-alpha7</version>
<version>1-alpha8</version>
</dependency>
-->
<!-- Windowing API implementation using GLFW
<dependency>
<groupId>de.staropensource.engine</groupId>
<artifactId>glfw</artifactId>
<version>1-alpha7</version>
<version>1-alpha8</version>
</dependency>
-->
<!-- sending and receiving notifications inside your application
<dependency>
<groupId>de.staropensource.engine</groupId>
<artifactId>notification</artifactId>
<version>1-alpha7</version>
<version>1-alpha8</version>
</dependency>
-->
</dependencies>

9
docs/docs/javadoc.md
View file

@ -76,3 +76,12 @@ The engine API documentation covers the core engine and all official subsystems.
- [windowing](https://jd.engine.staropensource.de/v1-alpha7/windowing/)
- [windowing:glfw](https://jd.engine.staropensource.de/v1-alpha7/windowing:glfw/)
- [notification](https://jd.engine.staropensource.de/v1-alpha7/notification/)
- v1-alpha8
- [All subsystem](https://jd.engine.staropensource.de/v1-alpha8/all/)
- [base](https://jd.engine.staropensource.de/v1-alpha8/base/)
- [testing](https://jd.engine.staropensource.de/v1-alpha8/testing/)
- [ansi](https://jd.engine.staropensource.de/v1-alpha8/ansi/)
- [slf4j-compat](https://jd.engine.staropensource.de/v1-alpha8/slf4j-compat/)
- [windowing](https://jd.engine.staropensource.de/v1-alpha8/windowing/)
- [windowing:glfw](https://jd.engine.staropensource.de/v1-alpha8/windowing:glfw/)
- [notification](https://jd.engine.staropensource.de/v1-alpha8/notification/)

87
docs/docs/welcome.md
View file

@ -13,31 +13,82 @@ 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 the logging infrastructure, creating and managing windows, playing audio and much more.
It is responsible for printing log messages, providing utility methods, creating and managing windows, playing audio and much more.
## Why another one?
Yeah, it's true that there are many game engines and frameworks out there that intend to ease development of applications and games.
I ([JeremyStarTM](https://git.staropensource.de/JeremyStarTM)) however have never seen an engine or framework, which can be extended easily, without having to fork it and without a complicated development setup.
And I don't mean what you make within the bounds of the engine or framework, no, I mean the engine/framework itself.
## 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 consists of the core engine (`base` dependency in your project) and various subsystems (`slf4j-compat`, `windowing`, etc.). \
\
The job of the base engine is to provide minimal classes and interfaces required for building a basic application.
It contains among other things a default logger implementation, useful methods, event system and a placeholder system. \
\
Subsystems on the other hand usually handle complex tasks. They provide abstractions for libraries and operating system calls. \
"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).
The engine is built as a modular system, containing the core engine (called `base`)
and various different subsystems.
## Available official 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 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`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/ansi): Provides an ANSI logging implementation and a ShortcodeParserSkeleton implementation
- [`slf4j-compat`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/slf4j-compat): Provides [SLF4J](https://slf4j.org/) compatibility logger that redirects all log calls to the engine.
- [`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
- [`windowing`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/windowing): Provides abstract APIs for creating and managing windows and monitors.
- [`windowing-glfw`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/windowing/glfw): Windowing API, allowing GLFW to be used for creating windows and recieving input.
- [`notification`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/notification): Provides an API for sending and receiving notifications inside a program.
- [`windowing`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/windowing): Provides abstract APIs for creating and managing windows as well as monitors
- [`windowing-glfw`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/windowing/glfw): Windowing API; allows using [GLFW](https://glfw.org) for creating 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).