threeoh6000/minecraft-pi-reborn
1
0
Fork 0
forked from minecraft-pi-reborn/minecraft-pi-reborn
Code Issues Pull Requests Projects Releases Wiki Activity

Update Documentation

Browse Source
This commit is contained in:
TheBrokenRail 2024-05-22 01:32:52 -04:00
parent 0e44bb5f06
commit db45df1e52
9 changed files with 76 additions and 235 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -2,6 +2,12 @@
<img alt="Start Screen" src="images/start.png">
</p>
<p align="center">
<a href="https://gitea.thebrokenrail.com/minecraft-pi-reborn/minecraft-pi-reborn/releases/latest"><img height="80" alt="Download as an AppImage" src="https://docs.appimage.org/_images/download-appimage-banner.svg" /></a>
<a href="https://flathub.org/apps/details/com.thebrokenrail.MCPIReborn"><img height="80" alt="Download on Flathub" src="https://flathub.org/assets/badges/flathub-badge-en.svg" /></a>
<a href="https://github.com/Botspot/pi-apps"><img height="80" alt="Get it from Pi-Apps" src="https://github.com/Botspot/pi-apps/blob/master/icons/badge.png?raw=true" /></a>
</p>
# Minecraft: Pi Edition: Reborn
Minecraft: Pi Edition Modding Project

106
docs/ARCHITECTURE.md
View File

@ -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)

13
docs/BUILDING.md
View File

@ -1,13 +0,0 @@
# Building
## Dependencies
### Debian/Ubuntu
```sh
./scripts/install-dependencies.sh
```
## Instructions
```sh
./scripts/build.mjs <none|appimage|flatpak> <client|server> <armhf|arm64|amd64|host> [--clean] [--install] [-Dvar=value...]
```

64
docs/COMMAND_LINE.md
View File

@ -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.

69
docs/GETTING_STARTED.md Normal file
View File

@ -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).
<details>
<summary><b>Additional System Requirements</b></summary>
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
```
</details>
### 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 `<Profile Directory>/overrides` if it does not already exist.
4. Copy `libminecraftpe.so` into `<Profile Directory>/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 `<Overrides Folder>/images/terrain.png`.
The overrides directory is located at `<Profile Directory>/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.

30
docs/INSTALL.md
View File

@ -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
<a href="https://flathub.org/apps/details/com.thebrokenrail.MCPIReborn"><img width="240" alt="Download On Flathub" src="https://flathub.org/assets/badges/flathub-badge-en.svg" /></a>
### 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.

8
docs/OVERRIDING_ASSETS.md
View File

@ -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`.

7
docs/README.md
View File

@ -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)

8
docs/SOUND.md
View File

@ -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`.