diff --git a/README.md b/README.md index c5b0efebba..16ace85dc4 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,12 @@ Start Screen

+

+ Download as an AppImage + Download on Flathub + Get it from Pi-Apps +

+ # Minecraft: Pi Edition: Reborn Minecraft: Pi Edition Modding Project diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index 2dbc3a97df..0000000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,106 +0,0 @@ -# Architecture - -## Launch Sequence - -### Common -1. The launcher forks itself. - 1. The child process continues the launch sequence. - 2. The original process monitors the child process for crashes. - -### Client -1. The launcher is started by the user. - 1. The launcher starts several Zenity dialogs to configure MCPI-Reborn. - 1. If the corresponding environmental variable for a setting is specified, it will be used instead of the dialog. - 2. If a setting is cached, then the dialog's default value will be the cached value instead of the normal default. - 3. When configuration has been completed, the settings specified will be cached. -2. The launcher replaces itself with MCPI. - 1. MCPI-Reborn components are loaded using `LD_PRELOAD` and `LD_LIBRARY_PATH`. - 2. If the Media Layer Proxy is enabled, then the Media Layer Proxy Client is started as a sub-process. - -### Server -1. The launcher is started by the user. -2. The launcher replaces itself with MCPI. - -## Components - -### Launcher -This component configures the various environmental variables required for MCPI-Reborn to work. When running in client-mode, this component will also launch several Zenity dialogs for interactive configuration. - -The environmental variables configured by this component includes: -* `LD_PRELOAD` -* `LD_LIBRARY_PATH` -* `MCPI_FEATURE_FLAGS` -* `MCPI_RENDER_DISTANCE` -* `MCPI_USERNAME` - -This is always compiled for the host system's architecture. - -### Media Layer -The Media Layer handles MCPI's graphics calls and user input. It replaces MCPI's native usage of SDL 1.2 with GLFW. - -#### Core -This sub-component re-implements a subset of SDL 1.2 calls with GLFW. It also provides a few utility functions that are used internally by MCPI-Reborn. - -The utility functions include: -* Fullscreen -* Audio -* Etc - -This is always compiled for the host system's architecture unless the Media Layer Proxy is disabled. - -This was created because SDL 1.2 has numerous bugs and is in-general unsupported. - -#### Proxy -This sub-component must be used if the host system's architecture isn't ARM. It uses UNIX pipes to cross architectural boundaries and allow MCPI to use the Media Layer Core (which is always compiled for the host system's architecture). - -It is made of two parts: -* Media Layer Proxy Server - * Links To MCPI - * Creates The UNIX Pipes - * Same External API As The Media Layer Core - * Compiled For ARM -* Media Layer Proxy Client - * Links To The Media Layer Core - * Connects To The Media Layer Proxy Server - * Uses The System's Native GLES Driver (ie. Mesa) - * Compiled For The Host System's Architecture - -While proxying all Media Layer Core API calls across UNIX pipes does hurt performance, it is better than emulating the entire graphics stack. - -Using this in server-mode is redundant (but is possible). - -#### Extras -This sub-component contains code that must always be linked directly to MCPI. - -This is always compiled for ARM. - -#### Headers -This sub-component includes headers for SDL, GLES, and EGL allowing easy (cross-)compilation. - -### Mods -This component patches MCPI to modify its behavior. It's loaded using `LD_PRELOAD`. - -This is always compiled for ARM. - -### `libreborn` -This component contains various utility functions including: - -* Code Patching (ARM Only) -* Logging -* Etc - -The code patching is ARM only because it relies on hard-coded ARM instructions. However, this is irrelevant since code patching is only needed in ARM code (to patch MCPI). - -### `symbols` -This component contains all MCPI symbols. - -## Dependencies -MCPI-Reborn has several dependencies: -* MCPI (Bundled) -* GLFW (Only In Client Mode; Bundled) - * OpenGL ES 2.0 -* OpenAL (Only In Client Mode) -* ZLib (Required By LibPNG; Bundled) -* LibPNG (Bundled) -* QEMU User Mode (Only On Non-ARM Hosts; Runtime Only) -* Zenity (Only In Client Mode; Runtime Only; Bundled) diff --git a/docs/BUILDING.md b/docs/BUILDING.md deleted file mode 100644 index 61654b4d0b..0000000000 --- a/docs/BUILDING.md +++ /dev/null @@ -1,13 +0,0 @@ -# Building - -## Dependencies - -### Debian/Ubuntu -```sh -./scripts/install-dependencies.sh -``` - -## Instructions -```sh -./scripts/build.mjs [--clean] [--install] [-Dvar=value...] -``` diff --git a/docs/COMMAND_LINE.md b/docs/COMMAND_LINE.md deleted file mode 100644 index 1683ea75d5..0000000000 --- a/docs/COMMAND_LINE.md +++ /dev/null @@ -1,64 +0,0 @@ -# Command Line Usage - -## Command Line Arguments - -### `--version` (Or `-v`) -If you run MCPI-Reborn with `--version` it will print its version to `stdout`. - -### `--debug` -This sets `MCPI_DEBUG`. - -### `--copy-sdk` -This extracts the modding SDK and immediately exits. (This allows the SDK to be extracted without starting the game.) - -### Client Mode Only - -#### `--print-available-feature-flags` -This print the available feature flags (and their default values) to `stdout` and then immediately exit. - -The feature flags are printed in the following format: -``` -TRUE This Flag Is On By Default -FALSE This Flag Is Off By Default -``` - -#### `--default` -This will skip the startup configuration dialogs and just use the default values. This will use the cached configuration unless `--no-cache` is used. - -#### `--benchmark` -This will make MCPI-Reborn enter a simple benchmark mode. This means automatically loading a newly generated world, then rotating the camera for a period of time. When it has finished, it will then exit and print the average FPS while the world was loaded. In this mode, all user input is blocked. However you can still modify rendering settings by changing feature flags. - -The world used will always be re-created on start and uses a hard-coded seed. - -#### `--no-cache` -This will skip loading and saving the cached launcher configuration. - -#### `--wipe-cache` -This will wipe the cached launcher configuration. - -### Server Mode Only - -#### `--only-generate` -This will make MCPI-Reborn immediately exit once world generation has completed. This is mainly used for automatically testing MCPI-Reborn. - -## Environmental Variables - -### `MCPI_DEBUG` -This enables debug logging if it is set. - -### `MCPI_API_PORT` -This configures the API to use a different port (the default is 4711). - -### Client Mode Only -If any of the following variables aren't set, one configuration dialog will open on startup for each unset variable. - -#### `MCPI_FEATURE_FLAGS` -This corresponds to `--print-available-feature-flags`. This is just a list of all enabled feature flags separated by `|`. - -For instance, the string `Feature A|Feature B` would enable both `Feature A` and `Feature B` and *disable every other available feature flag*. - -#### `MCPI_RENDER_DISTANCE` -This is the render distance. The possible values are: `Far`, `Normal`, `Short`, and `Tiny`. - -#### `MCPI_USERNAME` -This is the username. diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md new file mode 100644 index 0000000000..6932bc70f9 --- /dev/null +++ b/docs/GETTING_STARTED.md @@ -0,0 +1,69 @@ +--- +gitea: none +include_toc: true +--- + +# Getting Started +Welcome to the official guide for setting up Minecraft: Pi Edition: Reborn (also known as MCPI-Reborn)! This document will help you through the installation and setup process. + +## System Requirements +Following in the footsteps of the original Minecraft: Pi Edition, MCPI-Reborn can be run on just about anything, but there are some restrictions. + +Specifically, it requires support for OpenGL ES v2.0 (unlike the original game which used OpenGL ES v1.1). It also only supports Linux-based systems. + +In addition, while the original game could only be run on the Raspberry Pi, MCPI-Reborn is much more flexible. It supports running on 32-bit ARM (known as `armhf`), 64-bit ARM (known as `arm64`), and 64-bit x86 (known as `amd64`). + +## Installation +There are three supported ways to install MCPI-Reborn. + +### AppImage +The first supported way to install MCPI-Reborn is with an [AppImage](https://appimage.org). An AppImage is a portable application format that allows users to run software without installation. + +To run MCPI-Reborn, all you have to do is [download the latest AppImage](https://gitea.thebrokenrail.com/minecraft-pi-reborn/minecraft-pi-reborn/releases/latest) for your architecture and run it. + +More details can be found [here](https://docs.appimage.org/introduction/quickstart.html#how-to-run-an-appimage). + +
+Additional System Requirements +The AppImage requires Debian Bullseye or higher. This is equivalent to Ubuntu 20.04. + +It also requires some additional packages. To install them, just run: +```sh +sudo apt install -y libfuse2 libgtk-3-0 libopenal1 +``` +
+ +### Flatpak +The next method is the official [Flatpak](https://www.flatpak.org/). This had the additional benefit of built-in sandboxing. Unfortunately, it does not support 32-bit ARM systems. + +It can be installed through [Flathub](https://flathub.org/apps/details/com.thebrokenrail.MCPIReborn), + +### Pi-Apps (Limited Support) +The final supported method is [Pi-Apps](https://github.com/Botspot/pi-apps). It is ["a well-maintained collection of app installation-scripts"](https://github.com/Botspot/pi-apps?tab=readme-ov-file#:~:text=a%20well-maintained%20collection%20of%20app%20installation-scripts) that includes support for MCPI-Reborn. + +The list of supported systems can be found [here](https://github.com/Botspot/pi-apps?tab=readme-ov-file#supported-systems). + +## Managing Game Data +Just like regular Minecraft stores game data at `~/.minecraft`, MCPI-Reborn uses `~/.minecraft-pi`[^1]. This is the profile directory and is where your worlds, screenshots, and game settings are stored. + +The profile directory can easily be accessed by opening MCPI-Reborn and going to `Options -> Reborn -> Profile Directory`. + +## Sound +One of MCPI-Reborn most important modifications is the addition of a sound engine. However, due to copyright limitations, Minecraft's sounds cannot be distributed with MCPI-Reborn and must be installed manually. + +Fortunately, installing the sound data is fairly simple: +1. Obtain a valid Minecraft: Pocket Edition v0.6.1[^2] APK file. +2. Extract `lib/*/libminecraftpe.so` from the APK. +3. Create the directory `/overrides` if it does not already exist. +4. Copy `libminecraftpe.so` into `/overrides`. +5. Sound should now be fully functional! + +## Custom Textures +MCPI-Reborn allows users to easily use custom textures through use of an "overrides directory." Any files placed in this directory will automatically replace their equivalent file in MCPI-Reborn. + +For instance, to override `data/images/terrain.png`, only would have to copy the replacement file to `/images/terrain.png`. + +The overrides directory is located at `/overrides`. + +[^1]: When using the Flatpak, the profile directory is located at `~/.var/app/com.thebrokenrail.MCPIReborn/.minecraft-pi`. +[^2]: This is not a hard limit, a Minecraft: Pocket Edition v0.8.1 APK would probably work, but do not rely on it. \ No newline at end of file diff --git a/docs/INSTALL.md b/docs/INSTALL.md deleted file mode 100644 index e0942e7e08..0000000000 --- a/docs/INSTALL.md +++ /dev/null @@ -1,30 +0,0 @@ -# Installation - -## AppImage -Download packages [here](https://gitea.thebrokenrail.com/minecraft-pi-reborn/minecraft-pi-reborn/releases). - -### System Requirements -* Debian Bullseye/Ubuntu 20.04 Or Higher -* FUSE 2 - * Debian/Ubuntu: `sudo apt install libfuse2` - * Arch: `sudo pacman -S fuse2` -* Client-Only Dependencies - * Graphics Drivers - * GTK+ 3 - * Debian/Ubuntu: `sudo apt install libgtk-3-0` - * Arch: `sudo pacman -S gtk3` - * OpenAL - * Debian/Ubuntu: `sudo apt install libopenal1` - * Arch: `sudo pacman -S openal` - -### Running -Follow [these](https://docs.appimage.org/introduction/quickstart.html#how-to-run-an-appimage) instructions. - -## Flatpak -Download On Flathub - -### Note -Game data is stored in `~/.var/app/com.thebrokenrail.MCPIReborn/.minecraft-pi` instead of `~/.minecraft-pi`. - -## Arch User Repository (Arch Linux Only) -The [`minecraft-pi-reborn-git`](https://aur.archlinux.org/packages/minecraft-pi-reborn-git) is available in the AUR. diff --git a/docs/OVERRIDING_ASSETS.md b/docs/OVERRIDING_ASSETS.md deleted file mode 100644 index 1433e0c3d2..0000000000 --- a/docs/OVERRIDING_ASSETS.md +++ /dev/null @@ -1,8 +0,0 @@ -# Overriding Assets -To make overriding assets easier, MCPI-Reborn provides an overrides folder. Any file located in Minecraft: Pi Edition's `data` folder can be overridden by placing a file with the same name and path in the overrides folder. The overrides folder is located at `~/.minecraft-pi/overrides`[^1]. - -## Examples -- `data/images/terrain.png` -> `~/.minecraft-pi/overrides/images/terrain.png` -- `data/lang/en_US.lang` -> `~/.minecraft-pi/overrides/lang/en_US.lang` - -[^1]: On Flatpak, the path is `~/.var/app/com.thebrokenrail.MCPIReborn/.minecraft-pi/overrides`. diff --git a/docs/README.md b/docs/README.md index 6a4152804d..49ab91d149 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,9 @@ # Documentation -* [View Installation](INSTALL.md) -* [View Overriding Assets](OVERRIDING_ASSETS.md) +* [View Getting Started](GETTING_STARTED.md) * [View Dedicated Server](DEDICATED_SERVER.md) * [View Credits](CREDITS.md) * [View Terminology](TERMINOLOGY.md) -* [View Building](BUILDING.md) -* [View Architecture](ARCHITECTURE.md) -* [View Command Line Arguments](COMMAND_LINE.md) * [View Multiplayer](MULTIPLAYER.md) -* [View Sound](SOUND.md) * [View In-Game Controls](CONTROLS.md) * [View Custom Skins](CUSTOM_SKINS.md) * [View Changelog](CHANGELOG.md) diff --git a/docs/SOUND.md b/docs/SOUND.md deleted file mode 100644 index fc0f43e897..0000000000 --- a/docs/SOUND.md +++ /dev/null @@ -1,8 +0,0 @@ -# Sound -One of MCPI-Reborn's main modifications is a sound-engine since MCPI does not include one by default[^1]. However, it can't be used out-of-box because MCPI does not contain any sound data and MCPI-Reborn can't include it because of copyright. - -MCPE's sound data can be extracted from any MCPE v0.6.1[^2] APK file, just place its `libminecraftpe.so` into `~/.minecraft-pi/overrides`[^3] and you should have sound! - -[^1]: The mute button is just leftover code from MCPE, it does not actually do anything in un-modded MCPI, however it is connected to MCPI-Reborn's sound-engine. -[^2]: This is not a hard limit, an MCPE v0.8.1 APK would probably work, but don't rely on it. -[^3]: On Flatpak, the path is `~/.var/app/com.thebrokenrail.MCPIReborn/.minecraft-pi/overrides`.