Merge branch 'develop' into refactor/merge-universe-into-world-pregen…

…-screen

build-logic/src/main/kotlin/org/terasology/gradology/module_deps.kt

@@ -96,7 +96,7 @@ fun moduleDependencyOrdering(modulesConfig: Configuration): List<String> {
 
     val result = resolvable.resolutionResult
     val allDependencies = result.allDependencies
-    val resolvedDependencies = allDependencies.mapNotNull {
+    allDependencies.mapNotNull {
         if (it is ResolvedDependencyResult) {
             return@mapNotNull it
         }

build-logic/src/main/kotlin/reflections-manifest.gradle.kts

@@ -11,7 +11,7 @@ import java.net.URLClassLoader
 tasks.register("cacheReflections") {
     description = "Caches reflection output to make regular startup faster. May go stale and need cleanup at times."
 
-    val sourceSets = project.convention.getPlugin(JavaPluginConvention::class.java).sourceSets
+    val sourceSets = project.extensions.getByType(SourceSetContainer::class.java)
     val mainSourceSet: SourceSet = sourceSets[SourceSet.MAIN_SOURCE_SET_NAME]
 
     inputs.files(mainSourceSet.output.classesDirs)

build-logic/src/main/kotlin/terasology-module.gradle.kts

@@ -29,10 +29,10 @@ apply(from = "$rootDir/config/gradle/publish.gradle")
 // Handle some logic related to where what is
 configure<SourceSetContainer> {
     main {
-        java.destinationDirectory.set(buildDir.resolve("classes"))
+        java.destinationDirectory.set(layout.buildDirectory.dir("classes"))
     }
     test {
-        java.destinationDirectory.set(buildDir.resolve("testClasses"))
+        java.destinationDirectory.set(layout.buildDirectory.dir("testClasses"))
     }
 }
 
@@ -178,8 +178,8 @@ configure<IdeaModel> {
     module {
         // Change around the output a bit
         inheritOutputDirs = false
-        outputDir = buildDir.resolve("classes")
-        testOutputDir = buildDir.resolve("testClasses")
+        outputDir = layout.buildDirectory.dir("classes").get().asFile
+        testOutputDir = layout.buildDirectory.dir("testClasses").get().asFile
         isDownloadSources = true
     }
 }

build.gradle

@@ -41,7 +41,7 @@ plugins {
     // For the "Build and run using: Intellij IDEA | Gradle" switch
     id "org.jetbrains.gradle.plugin.idea-ext" version "1.0"
 
-    id("com.google.protobuf") version "0.8.16" apply false
+    id("com.google.protobuf") version "0.9.4" apply false
     id("terasology-repositories")
 }
 

docs/.gitignore

@@ -0,0 +1,2 @@
+.idea
+*.iml

docs/5.3-Migrating-to-Project-Reactor.md

@@ -0,0 +1,40 @@
+# Migrating to Project Reactor
+
+## Motivation
+
+The two main reasons we are adopting Reactor for our concurrent operations:
+
+1. Using a consistent API helps with thread management, making it easier to allocate the right amount of threads and clean them up when we need to.
+2. The Flux API offered by Project Reactor provides better ways to define and schedule asynchronous operations than the standard Java API does.
+
+## Deprecations
+
+- The creation of threads and threadpools is something that should be mediated by the engine.
+Modules should not be using `new Thread()` directly.
+- [o.t.e.utilites.concurrency.TaskMaster](https://github.com/MovingBlocks/Terasology/blob/v5.2.0/engine/src/main/java/org/terasology/engine/utilities/concurrency/TaskMaster.java) and its related `Task` class.
+
+## New Interfaces
+
+Most [Project Reactor](https://projectreactor.io) classes (from Reactor Core, Reactor Extra, and Reactor Test) are available to modules.
+The [Reactor Reference Guide](https://projectreactor.io/docs/core/release/reference/) includes an introduction to them.
+(It _occasionally_ assumes familiarity with the Reactive Streams specification, but its examples are complete on their own.)
+
+The [o.t.e.core.GameScheduler](https://jenkins.terasology.io/teraorg/job/Terasology/job/engine/job/develop/javadoc/org/terasology/engine/core/GameScheduler.html) class provides methods for scheduling work
+or obtaining a [Scheduler](https://projectreactor.io/docs/core/release/reference/#schedulers) instance.
+
+## Migration Guide
+
+### TaskMaster
+
+Replacements for TaskMaster methods:
+
+* `TaskMaster.create*(name, threads)`: Use `GameScheduler` to use an existing `Scheduler` instance.
+We do not expect modules need to create new Schedulers.
+* `Task`: [Runnable](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Runnable.html). (Runnable is a Functional Interface in Java; any zero-argument method may be passed anywhere a Runnable is expected.)
+* `task.getName()`: Pass a name to `GameScheduler.scheduleParallel(name, task)`.
+* `tm.offer(task)`: `GameScheduler.scheduleParallel(name, task)`.
+* `tm.put(task)`: This is a blocking method; no direct replacement is offered.
+Replace it with an asynchronous method, perhaps using Reactor's [Mono](https://projectreactor.io/docs/core/release/reference/#mono) to schedule work to continue after its completion.
+
+The above methods are only the ones that most directly correspond to the old TaskMaster interface.
+You will likely want to take advantage of other [Flux operations](https://projectreactor.io/docs/core/release/reference/#which-operator) to use the results of asynchronous methods and handle errors.

docs/Advanced-Options.md

@@ -0,0 +1,36 @@
+The `Terasology` command has some options to control its initial configuration. Run `Terasology -h` for a list. Some of the options are documented in more detail below.
+
+
+## Memory Usage
+
+<dl>
+<dt id="max-data-size">--max-data-size=N</dt>
+<dd><p>Enforced by the operating system instead of the Java Virtual Machine, this limits memory usage in a different way than setting Java's maximum heap size (the <code>-Xmx</code> <a href="https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE">java option</a>).
+Use this to prevent Terasology from gobbling all your system memory if it has a memory leak.
+
+Set this limit to a number larger than the maximum java heap size.
+It is normal for a process to need <em>some</em> additional memory outside the java heap.
+
+This value is in bytes, such as `2048M` or `4.7GB`.
+
+This is currently only implemented on Linux.
+
+On Windows, you may be able to set a limit using one of these external tools:
+ - <a href="https://docs.microsoft.com/en-us/windows-hardware/drivers/devtest/application-verifier">Application Verifier (<code>AppVerif.exe</code>)</a>, available from the Windows SDK
+ - <a href="https://github.com/lowleveldesign/process-governor">Process Governor (<code>procgov</code>)</a>, an open source third-party tool
+
+</dd>
+<dt id="oom-score">--oom-score=N</dt>
+<dd><p>Make the Linux Out-of-Memory killer more likely to pick Terasology.
+
+When a Linux system runs out of available memory, it invokes the Out of Memory killer (aka <i>OOM killer</i>) to choose a process to terminate to free up some memory.
+
+Add **N** to this score if you want to make Terasology a bigger target.
+Why? If you'd rather the game process be the thing that gets killed instead of some other memory-hungry program, like your browser or IDE.
+A [score][proc5] of 1000 is equivalent to saying “this process is taking <em>all</em> the memory.”
+
+This out-of-memory score is a Linux-specific mechanism.
+
+[proc5]: https://man7.org/linux/man-pages/man5/proc.5.html#:~:text=/proc/%5Bpid%5D/-,oom_score_adj,-(since
+</dd>
+</dl>