From 6425442c25f2e04998821bedf4e8279aabf8aa66 Mon Sep 17 00:00:00 2001 From: JeremyStarTM Date: Fri, 8 Nov 2024 22:15:25 +0100 Subject: [PATCH] Update documentation --- docs/docs/getting-started/_category_.json | 2 +- docs/docs/getting-started/initializing.md | 117 +++++++--------------- docs/docs/getting-started/installing.mdx | 15 ++- docs/docs/javadoc.md | 9 ++ docs/docs/welcome.md | 87 ++++++++++++---- 5 files changed, 120 insertions(+), 110 deletions(-) diff --git a/docs/docs/getting-started/_category_.json b/docs/docs/getting-started/_category_.json index 3ee8e151..7bff476f 100644 --- a/docs/docs/getting-started/_category_.json +++ b/docs/docs/getting-started/_category_.json @@ -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." } } diff --git a/docs/docs/getting-started/initializing.md b/docs/docs/getting-started/initializing.md index f8f946fc..43fe15f8 100644 --- a/docs/docs/getting-started/initializing.md +++ b/docs/docs/getting-started/initializing.md @@ -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: - - + + + - - + + + - - + + + - - + + + - + + - - + + + - + + - + +
LevelDescriptionLEVELMETHOD NAMEDESCRIPTION
DIAGNOSTICProvide detailed information about what is happening`DIAGNOSTIC``diag`Detailed information about what is happening
VERBOSEAdditional information that may not be useful`VERBOSE``verb`Additional information about what is happening
SILENT_WARNINGWarnings that can be ignored or are caused by invalid (API) user input`SILENT_WARNING``sarn`Less important warnings. Useful for logging parsing errors and such
INFORMATIONAL`INFORMATIONAL``info` Useful information about what is happening
WARNINGWarnings about dangerous or weird behaviour`WARNING``warn`Warnings about dangerous, deprecated or weird behaviour
ERROR`ERROR``error` Non-fatal errors
CRASH`CRASH``crash` Fatal errors which may or may not halt the running program (see below)
- -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! diff --git a/docs/docs/getting-started/installing.mdx b/docs/docs/getting-started/installing.mdx index 7799ea3d..60498924 100644 --- a/docs/docs/getting-started/installing.mdx +++ b/docs/docs/getting-started/installing.mdx @@ -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 - de.staropensource.engine base - 1-alpha7 + 1-alpha8 @@ -113,35 +112,35 @@ After that declare the engine as a dependency in your project: de.staropensource.engine ansi - 1-alpha7 + 1-alpha8 --> diff --git a/docs/docs/javadoc.md b/docs/docs/javadoc.md index 9a3be9aa..b829f76c 100644 --- a/docs/docs/javadoc.md +++ b/docs/docs/javadoc.md @@ -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/) diff --git a/docs/docs/welcome.md b/docs/docs/welcome.md index c0430f26..e16ecc9e 100644 --- a/docs/docs/welcome.md +++ b/docs/docs/welcome.md @@ -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).