Metadata-Version: 2.4
Name: mc-shell
Version: 0.9.1
Summary: An interactive shell and editor for controlling Minecraft servers and creating powers.
License-File: LICENSE
Author: Jeff
Author-email: jeff@thinkae.org
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: asyncssh (>=2.22.0,<3.0.0)
Requires-Dist: beautifulsoup4
Requires-Dist: blockapily (>=0.3.1,<0.4.0)
Requires-Dist: click
Requires-Dist: flask
Requires-Dist: flask-cors
Requires-Dist: flask-socketio
Requires-Dist: ipython
Requires-Dist: mctools (>=1.4.1,<2.0.0)
Requires-Dist: miniupnpc (>=2.3.3,<3.0.0)
Requires-Dist: numpy
Requires-Dist: pexpect
Requires-Dist: pickleshare
Requires-Dist: psutil (>=7.2.2,<8.0.0)
Requires-Dist: pytest (>=9.0.2,<10.0.0)
Requires-Dist: python-socketio[client]
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: requests
Requires-Dist: rich
Requires-Dist: voxelmap (>=5.1.1,<6.0.0)
Requires-Dist: yarl (==1.20.1)
Description-Content-Type: text/markdown

# MC-Shell: A Minecraft Power Development Environment 

Welcome to `mc-shell`! This project provides an interactive environment for creating, debugging, and using "powers" in Minecraft. It combines a powerful command-line shell with a visual block-based editor and a touch-friendly control panel.

This guide will walk you through installing the software, managing your own Minecraft worlds, and using the tools to bring your creations to life.

## Quick Start

This guide will get you running in just a few minutes. Each step is linked to a more detailed section below.

1.  **[Install the Software](#installation)**:
    ```bash
    pip install --user mc-shell
    ```
2.  **[Enter the Shell](#entering-the-shell)**:
    ```bash
    mcshell start
    ```
3.  **[Create Your First World](#creating-and-listing-worlds)**:
    ```bash
    %pp_create_world my_first_world
    ```
4.  **[Start Your World](#starting-and-stopping-worlds)**:
    ```bash
    %pp_start_world my_first_world
    ```
5.  **[Use the Editor](#using-the-editor)**: Open a browser and go to `http://localhost:5001`.
6.  **[Exit Cleanly](#exiting-the-shell)**: Type `exit` or hit `Ctrl-D` in the shell to stop your world and the application server.

---

## Getting Started

### Installation

Before you begin, you will need a few things installed on your system (Linux, macOS, or Windows Subsystem for Linux):
* **Python** (version 3.10 or higher)

Once the prerequisites are met, run the following commands in your terminal to download and install the project and all its dependencies. Note the recommended  
`--user` option: this will install in `~/.local/bin` so make sure your `PATH` includes this directory! And notice the package is called `mc-shell` but the
executable program is called `mcshell`. If you choose not to install with `--user` then the executable should be in your `PATH` automatically.

```bash
pip install --user mc-shell
````

### Running and Updating

To run the application, use the following command 

```bash
mcshell start
```

If the command is not found, your must add `~/.local/bin` to your `PATH` environment variable or use the following invocation
```bash
~/.local/bin/mcshell start
```

### Entering the Shell

Running the application will drop you into `mc-shell`, an enhanced IPython terminal. From here, you can manage your Minecraft worlds and the `mc-ed` application using special "magic commands" that start with a `%` symbol.

-----

##  Managing Your Worlds (The "Atomic Multi-verse")

This section covers all the `%pp_` commands for managing your personal Paper server instances.

### Creating and Listing Worlds

To create a new, self-contained world, use the `%pp_create_world` command. This will create a new folder in your home directory (`~/mc-worlds`), download the appropriate Paper server, and set up all the necessary configuration files. The current default version (which the client must match) is `1.21.11` but you can specify any version you want with the `--version` option, for example `1.21.4`.
```ipython
%pp_create_world my_creative_build --version=1.21.4
```

You can apply any set of datapacks that appear in your `~/mc-worlds/datapacks-library` directory. `mc-shell` ships with three datapacks: `flat_world`,`void_world` and a version of *OneBlock* by [IJAMinecraft](https://ijaminecraft.com/map/oneblock/) called `oneblock`. 

To create a totally flat world, use the following command:
```ipython
%pp_create_world my_flat_creative_build --datapacks=flat_world
```
To create a *OneBlock* world, use the following command. Note we overlay the void datapack to clear the world.
```ipython
%pp_create_world my_OneBlock --datapacks=void_world,oneblock
```
You can download and apply any datapack you want by unzip it to a folder inside `~/mc-worlds/datapacks-library` and then passing the name of the folder to the `--datapacks` option as described above.

You can also add *PaperMC* plugins to your `~/mc-worlds/<world_name>/plugins` folder.

To see a list of all the worlds you have created, use the `%pp_list_worlds` command.

### Starting and Stopping Worlds

The main command to start a session is `%pp_start_world`. This launches the specified Paper server in the background and starts the `mc-ed` application server, which provides the Editor and Control Panel UIs.

This command ensures only one world is active at a time. If you start a new world, it will automatically stop your previous session.

```ipython
%pp_start_world my_creative_build
```

To manually stop the current session (both the Paper server and the app server), use `%pp_stop_world`.

### Deleting Worlds

To permanently delete a world and all its files, use the `%pp_delete_world` command. You will be asked for confirmation before any files are removed.

```ipython
%pp_delete_world my_old_world
```

### Joining Worlds

This section covers how to connect to a running server. The `%mc_login` magic configures your shell to talk to a specific server, while `%mc_invite_player` allows you to send your connection details to a friend so they can join you.

### Exiting the Shell

When you are finished, you can exit the shell by typing `exit()` or pressing `Ctrl+D`. This will automatically trigger a clean shutdown of any running world and the application server.

-----

## Using the Tools

This section focuses on the two main graphical interfaces, which are available in your browser once a world is started.

### Using the Editor

The Editor is a powerful visual environment for creating "powers." You can access it at `http://localhost:5001`.

The interface consists of two main panels: the **Power Library** on the left, which lists your saved powers, and the main **Workspace** on the right. The workspace contains the **Blockly editor** for visually composing programs and a **live Python code preview** that updates as you work.

To create a functional power, you must follow the "Debug-to-Define" workflow:

1.  Create a **function definition** block (e.g., `def BuildTower(height)`).
2.  Create a **function call** block as a "test harness" and connect blocks with the correct types to its inputs (e.g., a `math_number` block for `height`).
3.  Click the **"Execute (Debug)"** button. This runs the code in-game and "type-stamps" your power's parameters with the correct types.
4.  Click **"Save Power As..."** to save this newly defined power to your library, ready to be used by the Control Panel.

### Using the Control

The Control Panel is a touch-friendly UI for executing your saved powers in-game. Access it at `http://localhost:5001/control`.

The interface has two modes:

  * **Run Mode:** The main grid displays your power "widgets." If a power has parameters, a long press on the widget will make interactive controls like sliders or pickers appear. Simply set the parameters and click 'Load Configuration.' Then a quick press of the widget will execute that power.
  * **Edit Mode:** Click "Edit Layout" to customize your grid. You can open a library of all your saved powers, add them as new widgets to your grid, and drag-and-drop them to arrange your layout.

