Update documentation
This commit is contained in:
parent
d1d8e305ed
commit
6425442c25
GPG key ID:
E366BAEF67E4704D
5 changed files with 120 additions and 110 deletions
|
|
@ -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."
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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!
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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/)
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Reference in a new issue