Installation ============ Introduction ------------ For the first tutorial we are going to prepare your computer for the rest of the tutorials. To do so we need to install the following software: - The Minecraft Java Client (with Minecraft account purchase) - Docker Desktop - Visual Studio Code - Python - Minecraft Interactive World Builder Python package .. warning:: The tutorials for this project are intended to be accessible for complete beginners. However, this first step of getting all of the software installed may need a little bit of knowledge of the basics of your operating system. For this Setup Tutorial, I recommend that novices get a little help from someone with computer experience. This setup tutorial need only be done once (per computer) and the remaining tutorials should not require prior knowledge. The Minecraft Java Client ------------------------- If you already have the Minecraft Java Client installed proceed to `docker`. You will need to purchase a license for Minecraft from Microsoft. Go to this site to buy your copy, if you do not already have one: https://www.minecraft.net/en-us/store/minecraft-java-bedrock-edition-pc Once you have a license, download the Java client to the computer where you will be trying out MCIWB. This is the download link for the Java client: https://www.minecraft.net/en-us/download Microsoft has now bundled the Java and Bedrock editions together. We are using the Java edition here but this project could be adapted to work for either in future. When you start Minecraft you will be asked to login with your Microsoft details, note that the 'Mojang Login' option is only for legacy users who have not yet migrated. When you have successfully launched the Minecraft Launcher, you will see a a screen like the following. Leave this screen open and move on to the rest of the tutorial. We will come back here and connect to a Minecraft server in a later tutorial. .. image:: ../images/launcher.png :alt: Minecraft Launcher :width: 700px :align: center .. _docker: Docker Desktop -------------- Docker is a tool that allows you to run your Minecraft Server in a container. This makes it easy to run and avoids having to manually install and maintain the server code. You do not need to understand too much about this since MCIWB will automatically use docker on your behalf. The easiest way to install Docker is to use Docker Desktop which is free to use for individuals. Windows: Docker Desktop requires WSL2 and a linux distribution to go with it. So you should first install WSL2 and Ubuntu 22.04 LTS from here - https://apps.microsoft.com/store/detail/ubuntu-2204-lts/9PN20MSR04DW All Platforms: Instructions for Docker Desktop installation for all platforms are here: - https://docs.docker.com/get-docker/ For mciwb to work you will need Docker Desktop to be running before you start Visual Studio Code. So start it from the start menu before moving to the next step. To make things easier next time you could go into settings (accessed via the cog icon in the title bar of the Docker Desktop main window) and tick the option ``Start Docker Desktop when you log in``. .. _vscode: Visual Studio Code ------------------ This is the tool we will use to edit our Python code. If you are already a developer then you can use your preferred IDE instead. The tutorials will use Visual Studio Code, so if you are new to programming this is a recommended install. VSCode is free, open-source software. This link provides downloads for all flavours of VSCode: https://code.visualstudio.com/download Command Line ------------ From now on we are going to start using the command line. You are free to use whatever terminal program you like, however I recommend that you use the integrated terminal inside of Visual Studio Code. Here we will set up our initial VSCode work folder and get a ``bash`` command line prompt. ``bash`` is the most popular ``shell`` for Linux, it provides a command line interface to all the utilities and services on a Linux computer. On Windows we will be using the Linux Subsystem so will also use ``bash``. On Mac we will be using ``zsh`` but this is pretty similar to ``bash``. First open VSCode from the start menu. .. note:: **Windows Users: Important** We are going to use 'Windows Subsystem for Linux 2' or WSL2. Go here first to get VSCode connected to WSL2: `wsl2` Let's create a work folder for use in further tutorials and tell VSCode To open the folder. We'll call it ``my_world`` but you are free to use your own name. First start a terminal by selecting from the menu bar ``Terminal -> New Terminal``. The bottom half of your VSCode window will display a ``bash`` prompt like this: .. image:: ../images/prompt.excalidraw.png :alt: VSCode Startup :width: 400px :align: center Type the following to make sure you are in in your home directory and then create a new folder called ``my_world``:: cd mkdir my_world Now we want to reopen VSCode with the new folder set as its work area. From the menu bar choose ``File -> Open Folder``. You will see a list of folders, select ``my_world`` and click OK. You will be asked if you trust the authors of files in this folder. You do trust them because they are you! So click ``Yes I trust the authors``. .. image:: ../images/trust.png :alt: VSCode Startup :width: 500px :align: center Now you should see a you VSCode window that looks something like this: .. image:: ../images/vscode_hello.excalidraw.png :alt: VSCode Startup :width: 700px :align: left From this point on all commands typed in the console and chosen from VSCode menus should be the same for Windows, Linux and MacOS. This is because you now have a bash shell for typing commands. .. warning:: There is one caveat here. When directed to install a software package with ``sudo apt``, this will only apply if you are using a Debian derived OS such as Ubuntu (this also covers Windows WSL2 users). Mac, CentOs, Arch based users - I'm hoping you will know the equivalent commands. I will supply an appendix for other OSes in future. Python ------ The Python Programming Language is also free and open-source. This is essential for working with MCIWB. Python 3.10 because the underlying RCON library requires it. This is the latest version of Python at the time of writing. These commands will install the necessary packages to make Python 3.10 available on your system:: sudo apt update sudo apt install -y python3.10 sudo apt install -y python3.10-venv sudo apt install -y python3-pip If you have an older version of Ubuntu it may not have Python 3.10 available. In this case you need to use the ``deadsnakes`` PPA to get the latest version as follows:: sudo apt install -y software-properties-common sudo add-apt-repository ppa:deadsnakes/ppa sudo apt install -y python3.10 sudo apt install -y python3.10-venv sudo apt install -y python3-pip Virtual Environment ------------------- We are going to create a **Virtual Environment** for our Python packages to install in. This is a way to keep the packages you install (like mciwb) separate from the packages you install for other projects. First create the Virtual Environment by typing (note the leading "." in the folder name ".venv"):: python3.10 -m venv .venv Then activate it by typing the following. This command will need to be repeated each time you restart your terminal or open a new terminal:: source .venv/bin/activate Note you can tell you have an active **Virtual Environment** because your terminal prompt will change to have a leading (.venv) like this:: (.venv) $ Minecraft Interactive World Builder library ------------------------------------------- The final component is MCIWB itself. This needs to be added to the Python environment we already made above. Again, this is free open open-source software. Before the next step, let's make sure that we are in the right folder and that we have the **Virtual Environment** activated:: cd $HOME/my_world source .venv/bin/activate The cd command stands for ``Change Directory``. This is a command that sets the current working folder (or directory). This is the default folder that your commands will work with from now. ``$HOME`` is your default HOME folder, the folder in which your user keeps their personal files. We already created the folder ``$HOME/my_world`` earlier and this is where we will store all of the work we do with MCIWB. Everything is all set up ready so the following simple command will get mciwb from the Python Package Index (PyPi) and install it into the **Virtual Environment**:: pip install mciwb Assuming all is well you should be able to verify everything is working by typing the following:: mciwb --help That's all the hard bits done and they only need to be done once. You can now proceed to the next tutorial.