Merge branch 'develop' into typehandlerlibrary-qa

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>