Added documentation for engine modules and permissions

docs/architecture/class-inclusion.md

@@ -0,0 +1,19 @@
+# Class Inclusion in Terasology
+
+This document explains the criteria and methods for including classes in Terasology’s engine and modules. It covers:
+- Adding classes to the permission list
+- Including classes in the `classesOnClasspathsToAddToEngine`
+- Annotating classes with `@gestalt.module.sandbox.API`
+- Class inclusion in the permission set
+
+## 1. Adding Classes to the Permission List
+
+### Purpose:
+- **Security**: Ensure only trusted classes are allowed to execute.
+- **Access Control**: Grant permissions to specific classes or packages.
+
+### Code Example:
+```java
+// ModuleManager.java
+permissionProviderFactory.getBasePermissionSet().grantPermission("com.google.gson", ReflectPermission.class);
+permissionProviderFactory.getBasePermissionSet().grantPermission("com.google.gson.internal", ReflectPermission.class);

docs/architecture/engine-modules.md

@@ -0,0 +1,13 @@
+# Engine Modules and Subsystems
+
+## Overview
+
+This document describes the structure and components related to engine modules in Terasology. It covers how subsystems and engine modules are defined and managed.
+
+## Subsystems
+
+Subsystems are components of the engine that are managed separately. In `TerasologyEngine.java`, the `allSubsystems` list is used to collect all subsystems.
+
+```java
+// TerasologyEngine.java, Lines 184-185
+allSubsystems.stream().map(Object::getClass).forEach(this::addToClassesOnClasspathsToAddToEngine);

docs/architecture/module-environment.md

@@ -0,0 +1 @@
+classPredicate: Predicate to determine what classes to include from the main classpath.

docs/architecture/permission-management.md

@@ -0,0 +1,23 @@
+# Permission Management in Terasology
+
+This document provides guidelines on managing permissions in Terasology. It covers:
+- Configuring permissions for classes and packages
+- Managing property permissions
+- Granting and revoking permissions
+
+## 1. Configuring Permissions for Classes and Packages
+
+### Purpose:
+- **Security**: Ensure that only authorized classes and packages can perform certain operations.
+- **Access Control**: Control what classes and packages can access or modify.
+
+### Steps to Configure Permissions:
+
+1. **Identify Classes/Packages**: Determine which classes or packages need specific permissions.
+2. **Grant Permissions**: Use the `PermissionProviderFactory` to grant permissions to these classes/packages.
+
+### Code Example:
+```java
+// ModuleManager.java
+permissionProviderFactory.getBasePermissionSet().grantPermission("com.google.gson", ReflectPermission.class);
+permissionProviderFactory.getBasePermissionSet().grantPermission("com.google.gson.internal", ReflectPermission.class);

docs/examples/case-studies.md

@@ -0,0 +1,18 @@
+# Case Studies in Terasology
+
+This document provides detailed case studies on class and permission management issues in Terasology. These examples illustrate how specific problems were identified and resolved, offering insights into effective management practices.
+
+## Case Study 1: Handling Missing Classes in Third-Party Libraries
+
+### Issue:
+A class from a third-party library failed to load, even though it was directly referenced in the engine code.
+
+### Solution:
+1. **Identify the Class**: Determine the specific class or package causing issues.
+2. **Update Permission Lists**: Add the class/package to the `ExternalApiWhitelist` to ensure it is accessible.
+3. **Adjust Security Settings**: Modify the security policy to grant necessary permissions.
+
+### Code Example:
+```java
+// ModuleManager.java
+permissionSet.grantPermission(new PropertyPermission("reactor.bufferSize.x", "read"));