# minecraft-kartverket

Map markers for PVV's minecraft server

## What is this?

This project is mainly a collection of markers for PVV's minecraft server.
It is meant to let PVV members contribute map data for PVV's minecraft server, like coordinates for bases, cities, and other points of interest.
These markers are written in python so that we can do things like generating points in a loop, calculating distances, and other types of automation.

The codebase includes a CLI tool that we use to export this data into the formats of several minecraft map implementations.

Grab the latest exports here:

- Bluemap:
  - https://pages.pvv.ntnu.no/Projects/minecraft-kartverket/main/bluemap/overworld.hocon
  - https://pages.pvv.ntnu.no/Projects/minecraft-kartverket/main/bluemap/nether.hocon
  - https://pages.pvv.ntnu.no/Projects/minecraft-kartverket/main/bluemap/the-end.hocon
- Mapcrafter:
  - https://pages.pvv.ntnu.no/Projects/minecraft-kartverket/main/mapcrafter/markers.js

## Marker sets

Here is an overview of the different marker sets, and a short description of what goes where:

### Overworld

| Directory      | Description |
|----------------|-------------|
| Area Names     | Large named areas or biomes |
| Buildings      | Important buildings and world wonders |
| Cities         | An area that consist of several bases and/or public infrastructure |
| Homes          | Single bases consisting of 1-3 people |
| Huts           | Small huts, meant for visitors and travelers |
| Infrastructure | Public infrastructure, like bridges, sea ports, tunnels, etc. |
| Mines          | Public mines |
| Nature         | Similar to `Area Names`, but meant for mostly untouched nature reserves or national parks. |
| Other          | Anything that doesn't fit into the other categories |
| Railways       | Railways, train tracks for transportation |
| Roads          | Roads and paths, for walking |
| Tunnels        | Underground passages, usually for transportation |
| Villages       | Villages generated by minecraft (player made cities go in `Cities`) |

### Nether

| Directory  | Description |
|------------|-------------|
| Ice Tracks | Ice tracks meant for highspeed travel with boats |
| Other      | Anything that doesn't fit into the other categories |
| Portals    | Nether portals that lead back to the overworld |
| Railways   | Railways, train tracks for transportation |

### The End

| Directory  | Description |
|------------|-------------|
| Other      | Anything that doesn't fit into the other categories |
| Portals    | End portals that send you back to the center of the map |

## How to run the python code

> [!NOTE]
> There should be no external dependencies required to run the code.
> Please keep it that way.

You can either use `uv`, `nix` or the bundled `Makefile` with a bare python installation to run the project.

### Using uv

If you have [uv](https://docs.astral.sh/uv/) installed, running the code is as easy as executing

```bash
uv run mckart <args>
```

### Using the Makefile

The makefile will validate the map data, and generate both types of map exports in a directory named `out`

You can invoke it with:

```bash
make
ls out
```

### Using nix

```bash
# Run the cli tool
nix run .# <args>

# Build the exports
nix build .#bluemap-export
nix build .#mapcrafter-export

# Get a python environment with development tooling
nix develop
```

> [!NOTE]
> In the following sections of the readme,
> we will assume that you are using `uv`.
> But the other methods can also be adapted to the instructions.

## How to add a point marker

1. Find the correct marker set file in `src/marker_sets/<world>`.
2. Add the marker to the list in the file. You can look at neighbouring markers for inspiration.
3. Run the cli tool to verify that the marker has been added correctly.

```bash
uv run mckart verify
uv run mckart print
```

4. Open a pull request at https://git.pvv.ntnu.no/Projects/minecraft-kartverket/pulls

## How to add a railway / road

This is very similar to adding a point marker, but the content of the marker is different.

You can follow the previous guide, but for step 3, use this template or look at other markers for inspiration.

```python
from lib_marker import Track

MARKERS = [
    ...,
    Track(
        name="Nordbanen",
        points = [
            (848, 70, 1583),
            (920, 70, 1583),
            (920, 70, 1200),
            ...
        ],
    ),
    ...,
]
```

## How to add a new marker set

To add a new marker set, you need to:

1. Create a new  file the other marker sets in `src/marker_sets/<world>`.
2. Create a marker set in this file, using this template:

```python
from lib_marker.marker_set import MarkerSet

MARKER_SET = MarkerSet(
    name="My Marker Set",
    markers=[
    ],
)
```

3. Add the marker set to the `MARKER_SETS` list in `src/marker_sets/<world>/__init__.py`.

```python
from .<marker_set_name> import MARKER_SET as <marker_set_name>_marker_set

MARKER_SETS = [
    ...
    portals_marker_set,
]
```

See the other marker sets for inspiration.

4. Add the marker set with a description to this README file.

## See also

- [BlueMap documentation for markers](https://bluemap.bluecolored.de/wiki/customization/Markers.html)
- [Mapcrafter documentation for markers](https://mapcrafter.readthedocs.io/en/latest/markers.html)