Rewrote README, wrote building guides and cleaned up

- Updated/prettified README.md
- Wrote extensive building guides
- Removed pictures/
- Removed music samples
- Made sure that git creates run/ when cloning

.gitignore

@@ -16,7 +16,12 @@ bin
 # Ignore MacOS
 **/.DS_Store
 .idea/
-run/
+
+# Ignore the dedicated working directory
+run/*
+
+# ... Except the dummy file inside to make sure that the directory exists
+!run/.dummy
 
 # Ignore package building artifacts
 build_packages/*

README.md

@@ -1,46 +1,58 @@
 # Progressia
-A free, open source sandbox survival game currently in early development.
+A free, open-source sandbox survival game currently in early development.
+
+## Description
+
+The game has barely begun development so much of its features are yet to be implemented.
+
+In broader terms, Progressia is a challenging game about survival, exploration and
+engineering in a realistic voxel sandbox environment. The game is heavily inspired by
+Minecraft technology mods, Factorio, Vintage Story and Minetest. Progressia's main unique
+features will include highly composite items and blocks, a realistically-scaled world,
+temperature mechanics and a parallelism-capable server.
+
+## System requirements
+
+- GNU/Linux (x64, arm32 or arm64), Windows XP or later (x64 or x86) or MacOS (x64)
+- Java 8 or later
+- OpenGL 2.1 or later
+- Probably at least 4 GiB RAM
+- Less than 1 GiB of storage space
+
+See [Build Guide](docs/building/BuildGuide.md) for compilation requirements.
 
 ## Contributing
 
-For now, contact @Javapony in Telegram for details. Contributing is completely allowed, but we don't have any set guidelines yet.
+All contributors welcome. Please contact Javapony in [Telegram](https://t.me/javapony)
+or join our [Discord server](https://discord.gg/M4ukyPYgGP) for details or help.
 
 ## Building
 
+On GNU/Linux and MacOS:
+
 1. `$ git clone https://github.com/OLEGSHA/Progressia.git`
-2. `$ gradlew build`
+2. `$ chmod +x gradlew`
+3. `$ ./gradlew buildLocal`
 
-### Additional setup for Eclipse IDE
+On Windows:
 
-If you have Buildship plugin installed, use File - Import - Gradle - Existing Gradle Project. Main class is `ru.windcorp.progressia.client.ProgressiaClientMain`.
+1. Download and unpack the repository
+3. Run `gradlew.bat buildLocal` in the same directory that contains `gradle.build` file
 
-Alternatively do the following:
+Alternatively use Linux/MacOS steps in a Bash shell.
 
-1. Add `id 'eclipse'` into `build.gradle` inside `plugins { ... }`:
+For a more in-depth explanation, solutions for common problems and tips for IDE configuration
-```
+please see the [Build Guide](docs/building/BuildGuide.md).
-plugins {
-    // Apply the java-library plugin to add support for Java Library
-    id 'java-library'
-    id 'eclipse'
-}
-```
-2. `$ gradlew eclipse`
-3. Import the project with File - Import - Existing Projects into Workspace
-4. On Windows, make sure the project has UTF-8 encoding with <RMB on project in project tree> - Properties - Resource - Text file encoding - Other - UTF-8
-
-### Additional setup for IntelliJ IDEA
-
-1. Open the project with File - Open Project
-2. Press button 'Add configuration...' and open 'Application' in templates list
-3. Add `ru.windcorp.progressia.client.ProgressiaClientMain` in 'Main class' text field
-4. Choose `Progressia.main` in 'Use classpath of module' drop-down list
-5. Click 'Create configuration' and press 'Apply'
 
 ## Libraries
 
-* LWJGL - OpenGL, OpenAL, GLFW and several more libraries ported to Java
+- [LWJGL](https://www.lwjgl.org/) ([GitHub](https://github.com/LWJGL/lwjgl3)) – OpenGL, OpenAL, GLFW and STB libraries ported to Java
-* Google Guava
+  - [OpenGL](https://en.wikipedia.org/wiki/OpenGL) – a low-level graphics interface
-* Trove4j
+  - [OpenAL](https://en.wikipedia.org/wiki/OpenAL) – a low-level audio interface
-* java-graphics/glm - GLM ported to Java. _Maven Central contains an outdated version, a custom repository used instead_
+  - [GLFW](https://www.glfw.org/) ([GitHub](https://github.com/glfw/glfw)) – a minimalistic OpenGL-capable windowing library
-* OpenSimplex2
+  - [STB (GitHub)](https://github.com/nothings/stb) – a collection of various algorithms. `stb_vorbis` is used
-* log4j
+- [Guava (GitHub)](https://github.com/google/guava) – a generic utilities library
+- [Trove4j (BitBucket)](https://bitbucket.org/trove4j/trove) – optimized primitive collections 
+- [java-graphics/glm (GitHub)](https://github.com/java-graphics/glm) – GLM ported to Java. _Maven Central contains an outdated version, a custom repository used instead_
+- [OpenSimplex2 (GitHub)](https://github.com/KdotJPG/OpenSimplex2) – a minimalistic highly optimized noise generator
+- [Log4j](https://logging.apache.org/log4j/2.x/) [(GitHub)](https://github.com/apache/logging-log4j2) – a logging library

docs/building/BuildGuide.md

@@ -0,0 +1,203 @@
+# Build Guide
+
+This document is a guide to building Progressia from source.
+
+Compilation should be possible on all platforms that support JDK 8 or later, however, packaging scripts require Bash.
+
+This guide assumes you are familiar with using a terminal or Windows Command Prompt or PowerShell.
+
+See [Eclipse Guide](EclipseGuide.md) and [IntelliJ IDEA Guide](IntelliJIDEAGuide.md) for IDE-specific configuration.
+
+## Basic compilation
+
+### Installing prerequisites
+
+Compiling Progressia requires that a JDK (Java Development Kit) 8 or later is available in your system path. Please
+note that JDK is not the same as a JRE (Java Runtime Environment), the software required to execute Java programs;
+you may be able to run Progressia but not compile it.
+
+To check whether you have the correct JDK installed please run
+	`javac --version`.
+If this command fails or outputs version 1.7 or lower, then you need to (re-)install JDK. (javac is the Java
+Compiler.)
+
+Progressia developers recommend [OpenJDK](https://openjdk.java.net/) as the free, open-source Java implementation.
+Confusion may arise from the project's name: OpenJDK issues both JRE and JDK; an OpenJDK JRE is not enough to compile
+Progressia. Another popular choice is [Oracle Java](https://www.oracle.com/java/technologies/), which is proprietary
+and thus not recommended.
+
+To install OpenJDK JDK on GNU/Linux, install the appropriately named package with your package manager (on Debian,
+Ubuntu and other dpkg-based distributions, run
+	`apt-get install default-jdk`
+with root privileges).
+
+To install OpenJDK JDK on MacOS or Windows, Progressia developers recommend [AdoptOpenJDK](https://adoptopenjdk.net/),
+which creates and distributes OpenJDK installers and packages. Please confirm that JDK installed correctly using
+the aforementioned test.
+
+### Getting the source code
+
+Progressia source code is managed with [git](https://git-scm.com/), a popular open-source tool. It is a program that
+automatically keeps track of changes in a set of source code and allows synchronization of those changes between
+different computers. A copy of the source code is called a repository. This guide will assume that
+[Progressia's GitHub repository](https://github.com/OLEGSHA/Progressia/) is accessible; if it is not, please look up
+the relevant instructions.
+
+If git is installed on your system, perform a clone of
+	`https://github.com/OLEGSHA/Progressia.git`.
+The details may vary depending on your git frontend; if you are not using a frontend, issue the following command:
+
+```
+git clone https://github.com/OLEGSHA/Progressia.git
+```
+
+Run the command in your directory of choice, git will create a subfolder. After the action completes you should
+have a local copy of the source code.
+
+If you do not have git installed, use GitHub's 'Download ZIP' option (available through the green 'Code' button at
+the time of writing this). Unpack the downloaded archive into any directory.
+
+### Compiling
+
+Compilation and related tasks are managed by [Gradle](https://gradle.org/), another popular open-source tool. The repository
+contains a Gradle Wrapper which automatically detects and installs the appropriate Gradle version. Gradle is most
+conveniently controlled with one of two scripts, `gradlew` or `gradlew.bat` for Bash and Windows Command Prompt respectively,
+which are distributed within the repository as well. Gradle itself uses another file, `build.gradle`, that contains the
+relevant instructions in Groovy.
+
+On GNU/Linux and MacOS, the script may need to receive the execution permission before being run:
+
+```
+chmod +x gradlew
+```
+
+A most basic compilation is achieved with:
+
+```
+./gradlew buildLocal
+```
+
+This instructs Gradle to compile, check and test a JAR archive with the game, as well as to download all necessary
+dependencies. The resulting JAR file will only reference libraries required to run the game on your current platform.
+
+The compiled JAR and all necessary libraries can be found in `build/libs/`. The `lib` directory next to `Progressia.jar`
+contains all runtime dependencies; the game may be run with a simple
+	`java -jar Progressia.jar`
+if `lib` is located in the same directory as the JAR file. (On many systems double-clicking `Progressia.jar` has the
+same effect.) Otherwise, if there is no `lib` directory next to the JAR, classpath must be set manually with command
+line options for `java`.
+
+A more conventional command, `./gradlew build`, may be used to the same effect; however, Progressia developers recommend
+against using it as their effects might start to differ with future updates.
+
+## Building for other platforms
+
+### Native libraries and why platforms matter
+
+Although Java is well-known for its portability, Progressia has a limited set of architectures that it supports.
+This is a consequence of the fact that Progressia uses [OpenGL](https://en.wikipedia.org/wiki/OpenGL),
+[OpenAL](https://en.wikipedia.org/wiki/OpenAL), [GLFW](https://www.glfw.org) and [STB](https://github.com/nothings/stb),
+four libraries originally implemented in the C language. In order to access them, a Java wrapper library,
+[LWJGL](https://www.lwjgl.org/), is used. Unfortunately such wrappers need to be hand-written for each platform
+and require complicated compilation.
+
+In practice this means that along with the pure Java libraries, such as Guava or GLM, Progressia carries several
+LWJGL libraries that each consist of a Java interface and a compiled binary implementation (called a native library).
+A separate version of a single native library is required to run Progressia on different platforms; if a game only
+contains natives for Windows, it cannot be run on GNU/Linux.
+
+### How Gradle is set up
+
+Gradle builds Progressia by first choosing which platform or platforms should be supported. It then downloads,
+if necessary, and processes only dependencies that are relevant to the current configuration. When creating the JAR
+file, Gradle appends only selected libraries to the JAR's manifest file. It finally copies only the libraries included
+in the manifest to the `build/libs/lib` directory.
+
+Why not package all natives all the time? This is inefficient when producing temporary builds for development purposes
+because unnecessary dependencies need to be downloaded and processed. This mechanism is also used to trim down the
+size of various system-specific installers and packages since, for example, a Windows Installer is not expected to
+produce a installation that runs on anything other than Windows, so GNU/Linux and MacOS natives need not be packaged
+with it.
+
+Unless instructed otherwise, Gradle only chooses the local platform. Thus the procedure described in 'Basic Compilation'
+produces an output that only contains the natives for the platform that performed the compilation. It is unsuitable for
+publication and may be generally inconvenient.
+
+### Building cross-platform
+
+Fortunately it is possible to produce a maximally cross-platform version by running Gradle with a different task:
+
+```
+./gradlew buildCrossPlatform
+```
+
+This command performs the same actions as the `buildLocal` command, except that all possible native libraries are
+included in the JAR manifest and copied into `build/libs/lib`. The result may be run on any supported platform.
+However, because of the large amount of libraries, it has significantly greater size than a platform-specific
+build.
+
+### Building for a specific platform
+
+Some users might find the need to build for a specific set of platforms. Inclusion of GNU/Linux, Windows or MacOS
+dependencies individually can be controlled with the following arguments to the `./gradlew build` command:
+- `requestLinuxDependencies` requests that `natives-linux`, `natives-linux-arm32` and `natives-linux-arm64` binaries are included;
+- `requestWindowsDependencies` requests that `natives-windows` and `natives-windows-x86` binaries are included;
+- `requestMacOSDependencies` requests that `natives-macos` binaries are included.
+These requests can be applied in any combination. For example, the following command produces a build containing only
+GNU/Linux and Windows natives:
+
+```
+./gradlew build requestLinuxDependencies requestWindowsDependencies
+```
+
+For finer control please edit `build.gradle` manually by adding the desired natives to the `project.ext.platforms` set like so:
+
+```
+project.ext.platforms = new HashSet<>()
+project.ext.platforms.add 'natives-windows-x86'
+```
+
+## Packaging
+
+A Debian package and a Windows installer can be created automatically on systems that support Bash. These tasks are delegated
+by Gradle to `buildPackages.sh` in repository root. This script checks the environment and assembles the requested output; the
+resulting files are moved into `build_packages`.
+
+### Creating a Debian package
+
+A Debian package can be created with the following Gradle task:
+
+```
+./gradlew packageDebian
+```
+
+Gradle will then build all artifacts necessary to run the game on GNU/Linux (all three architectures) and invoke
+`./buildPackages.sh debian`. Commands `dpkg-deb` and `fakeroot` must be available in system path in order to build the package.
+
+### Creating a Windows installer
+
+A Windows installer can be created with the following Gradle task:
+
+```
+./gradlew packageWindows
+```
+
+Gradle will then build all artifacts necessary to run the game on Windows (both x64 and x86 architectures) and invoke
+`./buildPackages.sh windows`.
+
+Windows installers are implemented with [NSIS](https://nsis.sourceforge.io/). Command `makensis` must be available in system
+path in order to build the installer.
+
+## Gradle tasks summary
+
+- `buildLocal` – creates a build optimized for current platform. Use this to quickly build the game during development.
+- `buildCrossPlatform` – creates a build that supports all known architectures. Use this to build a universal version of the game.
+- `build` – currently a synonym of `buildLocal`; creates a default build.
+- `packageDebian` – creates a Debian package. Do not invoke together with `packageWindows`.
+- `packageWindows` – creates a Windows installer. Do not invoke together with `packageDebian`.
+- `requestLinuxDependencies` – requests that `natives-linux`, `natives-linux-arm32` and `natives-linux-arm64` binaries are included when building.
+- `requestWindowsDependencies` – requests that `natives-windows` and `natives-windows-x86` binaries are included when building.
+- `requestMacOSDependencies` – requests that `natives-macos` binaries are included when building.
+- `requestCrossPlatformDependencies` – requests that all binaries are included when building.
+
+All other basic and Java-related Gradle tasks are available as well.

docs/building/EclipseGuide.md

@@ -0,0 +1,113 @@
+### Eclipse Guide
+
+This document is a guide to configuring Eclipse IDE for developing Progressia.
+
+## Setup
+
+### Downloading project
+
+Although the project may be downloaded manually or using git directly (as described in the
+[Build Guide](BuildGuide.md)), it may be more convenient to use Eclipse's EGit. If you
+choose not to, skip the following subsection.
+
+#### Using EGit
+
+[EGit](https://www.eclipse.org/egit/) is a git interface for Eclipse. It is currently shipped
+with Eclipse IDE.
+
+1. Open Git perspective. (Git perspective is not visible by default. To open it, use
+'Window' menu > 'Perspective' > 'Open Perspective' > 'Other' > select Git.)
+2. In 'Git Repositories' view, click 'Clone a Git Repository and add the clone to this view'
+button.
+3. Paste
+`https://github.com/OLEGSHA/Progressia.git`
+or the appropriate git URI into the 'URI' field and click 'Next'.
+4. Review the branches and click 'Next'.
+5. Edit the local repository path if necessary and click 'Finish'.
+
+Note: avoid importing the project from the Git Clone Wizard as doing so will fail to specify
+Gradle dependencies.
+
+### Importing project
+
+Gradle dependencies need to be imported into the IDE for proper code analysis and launching.
+
+#### Using Buildship plugin for Eclipse
+
+[Buildship](https://projects.eclipse.org/projects/tools.buildship) is an Eclipse plugin
+that integrates Gradle into the IDE. This is the recommended method.
+
+1. In 'File' menu, select 'Import...'.
+2. In the Import Wizard, select 'Gradle' > 'Existing Gradle Project'. Click 'Next'.
+3. In the Gradle Import Wizard, click 'Next' to arrive at directory selection.
+4. Select the directory that contains `build.gradle` file in 'Project root directory' field.
+5. Click 'Finish' and allow the plugin to import the project.
+
+When using this method, any changes to the `build.gradle` file must be followed by a Gradle
+refresh ((Project context menu) > 'Gradle' > 'Refresh Gradle Project').
+
+
+#### Using Eclipse plugin for Gradle
+
+Gradle features a plugin for Eclipse that can generate project specifications for the IDE.
+It is deactivated by default.
+
+1. Enable the Eclipse plugin by uncommenting the `id 'eclipse'` line in `build.gradle`
+(note the disappearance of `//`). Please make sure not to accidentally commit this change in git!
+
+```
+plugins {
+    // Apply the java-library plugin to add support for Java Library
+    id 'java-library'
+    
+    /*
+     * Uncomment the following line to enable the Eclipse plugin.
+     * This is only necessary if you don't use Buildship plugin from the IDE
+     */
+    id 'eclipse'
+}
+```
+
+2. Run
+	`./gradlew eclipse`
+in the directory that contains `build.gradle`. This command will
+generate Eclipse project files.
+3. In 'File' menu in the Eclipse IDE, select 'Import...'.
+4. In the Import Wizard, select 'General' > 'Existing Projects into Workspace'. Click 'Next'.
+5. Select the directory that contains `build.gradle` file in 'Select root directory' field.
+6. Click 'Finish' and allow the IDE to import the project.
+
+When using this method, any changes to the `build.gradle` file must be followed by
+`./gradlew eclipse` command and a project refresh ((Project context menu) > 'Refresh').
+
+
+### Creating a Run Configuration
+
+Run configurations are used by Eclipse IDE to specify how a project must be run.
+
+1. In 'Run' menu, select 'Run Configurations...'.
+2. In the Run Configurations, select 'Java Application', then click 'New launch configuration'.
+3. Specify the project and the name of the new configuration.
+4. Put
+`ru.windcorp.progressia.client.ProgressiaClientMain`
+into 'Main Class' field.
+5. In the 'Arguments' tab, put
+`${workspace_loc:Progressia}/run`
+into 'Working directory:' > 'Other' field. Replace `Progressia` with your name of the project.
+Alternatively specify another location outside of the project's root directory.
+6. Click 'Apply' to save changes. Exit Run Configurations.
+
+Step 5 is required to specify that the game must run in some directory other than the project root,
+which is the default in Eclipse.
+
+## Common problems
+
+### Buildship plugin fails with a cryptic message
+
+This may be caused by a lack of Java in your system path. Eclipse stores the path to the JVM it
+uses in its settings and is thus not affected by the changes to the system path. However, Gradle
+searches for Java installations in system path regardless and may fail independently of Eclipse.
+
+__Solution:__ the simplest solution is to reinstall JDK making sure that system path is affected.
+See [Build Guide](BuildGuide.md) for details. Another course of action is to manually append the
+Java installation directory (specifically its `bin` folder) to the system `PATH` variable.

run/.dummy

@@ -0,0 +1 @@
+This is a dummy file to make sure run/ directory is stored and created by git.