Update documentation
This commit is contained in:
parent
d1d8e305ed
commit
6425442c25
5 changed files with 120 additions and 110 deletions
|
@ -3,6 +3,6 @@
|
||||||
"position": 2,
|
"position": 2,
|
||||||
"link": {
|
"link": {
|
||||||
"type": "generated-index",
|
"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."
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
@ -8,8 +8,20 @@ To initialize the sos!engine, simply add this to the initialization code of your
|
||||||
```java
|
```java
|
||||||
Engine.initialize();
|
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
|
## Printing something
|
||||||
Now you'll probably want to print some log output. Before you try using `System.out#println`,
|
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:
|
There are eight log levels you can use:
|
||||||
<table>
|
<table>
|
||||||
<tr>
|
<tr>
|
||||||
<th>Level</th>
|
<th>LEVEL</th>
|
||||||
<th>Description</th>
|
<th>METHOD NAME</th>
|
||||||
|
<th>DESCRIPTION</th>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<th>DIAGNOSTIC</th>
|
<th>`DIAGNOSTIC`</th>
|
||||||
<th>Provide detailed information about what is happening</th>
|
<th>`diag`</th>
|
||||||
|
<th>Detailed information about what is happening</th>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<th>VERBOSE</th>
|
<th>`VERBOSE`</th>
|
||||||
<th>Additional information that may not be useful</th>
|
<th>`verb`</th>
|
||||||
|
<th>Additional information about what is happening</th>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<th>SILENT_WARNING</th>
|
<th>`SILENT_WARNING`</th>
|
||||||
<th>Warnings that can be ignored or are caused by invalid (API) user input</th>
|
<th>`sarn`</th>
|
||||||
|
<th>Less important warnings. Useful for logging parsing errors and such</th>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<th>INFORMATIONAL</th>
|
<th>`INFORMATIONAL`</th>
|
||||||
|
<th>`info`</th>
|
||||||
<th>Useful information about what is happening</th>
|
<th>Useful information about what is happening</th>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<th>WARNING</th>
|
<th>`WARNING`</th>
|
||||||
<th>Warnings about dangerous or weird behaviour</th>
|
<th>`warn`</th>
|
||||||
|
<th>Warnings about dangerous, deprecated or weird behaviour</th>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<th>ERROR</th>
|
<th>`ERROR`</th>
|
||||||
|
<th>`error`</th>
|
||||||
<th>Non-fatal errors</th>
|
<th>Non-fatal errors</th>
|
||||||
</tr>
|
</tr>
|
||||||
<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>
|
<th>Fatal errors which may or may not halt the running program (see below)</th>
|
||||||
</tr>
|
</tr>
|
||||||
</table>
|
</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!
|
|
||||||
|
|
|
@ -80,7 +80,7 @@ dependencies {
|
||||||
... and add this property to the `settings.gradle` file:
|
... and add this property to the `settings.gradle` file:
|
||||||
```properties
|
```properties
|
||||||
# Set this to the engine version you want to use
|
# Set this to the engine version you want to use
|
||||||
dependencyStarOpenSourceEngine=1-alpha7
|
dependencyStarOpenSourceEngine=1-alpha8
|
||||||
```
|
```
|
||||||
|
|
||||||
## Maven
|
## 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:
|
After that declare the engine as a dependency in your project:
|
||||||
|
|
||||||
```xml
|
```xml
|
||||||
|
|
||||||
<dependencies>
|
<dependencies>
|
||||||
<!-- sos!engine base -->
|
<!-- sos!engine base -->
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>de.staropensource.engine</groupId>
|
<groupId>de.staropensource.engine</groupId>
|
||||||
<artifactId>base</artifactId>
|
<artifactId>base</artifactId>
|
||||||
<version>1-alpha7</version>
|
<version>1-alpha8</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
|
|
||||||
<!-- sos!engine subsystems -->
|
<!-- sos!engine subsystems -->
|
||||||
|
@ -113,35 +112,35 @@ After that declare the engine as a dependency in your project:
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>de.staropensource.engine</groupId>
|
<groupId>de.staropensource.engine</groupId>
|
||||||
<artifactId>ansi</artifactId>
|
<artifactId>ansi</artifactId>
|
||||||
<version>1-alpha7</version>
|
<version>1-alpha8</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
-->
|
-->
|
||||||
<!-- SLF4J compatibility
|
<!-- SLF4J compatibility
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>de.staropensource.engine</groupId>
|
<groupId>de.staropensource.engine</groupId>
|
||||||
<artifactId>slf4j-compat</artifactId>
|
<artifactId>slf4j-compat</artifactId>
|
||||||
<version>1-alpha7</version>
|
<version>1-alpha8</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
-->
|
-->
|
||||||
<!-- creating and managing windows, requires a Windowing API implementation
|
<!-- creating and managing windows, requires a Windowing API implementation
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>de.staropensource.engine</groupId>
|
<groupId>de.staropensource.engine</groupId>
|
||||||
<artifactId>windowing</artifactId>
|
<artifactId>windowing</artifactId>
|
||||||
<version>1-alpha7</version>
|
<version>1-alpha8</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
-->
|
-->
|
||||||
<!-- Windowing API implementation using GLFW
|
<!-- Windowing API implementation using GLFW
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>de.staropensource.engine</groupId>
|
<groupId>de.staropensource.engine</groupId>
|
||||||
<artifactId>glfw</artifactId>
|
<artifactId>glfw</artifactId>
|
||||||
<version>1-alpha7</version>
|
<version>1-alpha8</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
-->
|
-->
|
||||||
<!-- sending and receiving notifications inside your application
|
<!-- sending and receiving notifications inside your application
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>de.staropensource.engine</groupId>
|
<groupId>de.staropensource.engine</groupId>
|
||||||
<artifactId>notification</artifactId>
|
<artifactId>notification</artifactId>
|
||||||
<version>1-alpha7</version>
|
<version>1-alpha8</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
-->
|
-->
|
||||||
</dependencies>
|
</dependencies>
|
||||||
|
|
|
@ -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](https://jd.engine.staropensource.de/v1-alpha7/windowing/)
|
||||||
- [windowing:glfw](https://jd.engine.staropensource.de/v1-alpha7/windowing:glfw/)
|
- [windowing:glfw](https://jd.engine.staropensource.de/v1-alpha7/windowing:glfw/)
|
||||||
- [notification](https://jd.engine.staropensource.de/v1-alpha7/notification/)
|
- [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/)
|
||||||
|
|
|
@ -13,31 +13,82 @@ Welcome to the documentation for the StarOpenSource Engine!
|
||||||
|
|
||||||
## What is it?
|
## What is it?
|
||||||
The StarOpenSource Engine (or **sos!engine** for short) is a modular, extensible and easy to use Java game and application engine. \
|
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?
|
## There are `n` different game engines and application frameworks. 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.
|
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, which can be extended easily, without having to fork it and without a complicated development setup.
|
I ([JeremyStarTM](https://git.staropensource.de/JeremyStarTM)) however have never seen an engine or framework be modular,
|
||||||
And I don't mean what you make within the bounds of the engine or framework, no, I mean the engine/framework itself.
|
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
|
## Architecture of the engine
|
||||||
The engine consists of the core engine (`base` dependency in your project) and various subsystems (`slf4j-compat`, `windowing`, etc.). \
|
The engine is built as a modular system, containing the core engine (called `base`)
|
||||||
\
|
and various different subsystems.
|
||||||
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).
|
|
||||||
|
|
||||||
## 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.
|
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
|
### Stable
|
||||||
- [`ansi`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/ansi): Provides an ANSI logging implementation and a ShortcodeParserSkeleton implementation
|
- [`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 [SLF4J](https://slf4j.org/) compatibility logger that redirects all log calls to the engine.
|
- [`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
|
### Experimental
|
||||||
- [`windowing`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/windowing): Provides abstract APIs for creating and managing windows and monitors.
|
- [`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, allowing GLFW to be used for creating windows and recieving input.
|
- [`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.
|
- [`notification`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/notification): Provides an API for sending and receiving notifications inside a program
|
||||||
|
|
||||||
## API documentation
|
## API documentation
|
||||||
To read the engine API documentation, visit [jd.engine.staropensource.de](https://jd.engine.staropensource.de).
|
To read the engine API documentation, visit [jd.engine.staropensource.de](https://jd.engine.staropensource.de).
|
||||||
|
|
Loading…
Reference in a new issue