# Map Setup Guide

This guide explains how to set up the world map feature with Xaero's World Map PNG files.

## Prerequisites

1. **Xaero's World Map Mod**: Install the Xaero's World Map mod on your Minecraft server
2. **Map Generation**: Generate the world map by exploring your Minecraft world
3. **PNG Export**: Export the map as PNG files using Xaero's World Map

## Step 1: Generate Map in Minecraft

1. Install Xaero's World Map mod on your Minecraft server
2. Have players explore the world to generate map data
3. The mod will automatically create PNG files in the server's data directory

## Step 2: Locate PNG Files

The PNG files are typically located in:
```
<server_directory>/world/XaeroWaypoints/dim0/
```

Look for files named like:
- `xaero_map_0_0.png`
- `xaero_map_1_0.png`
- `xaero_map_0_1.png`
- etc.

## Step 3: Upload Files to Backend Container

The map tiles should be uploaded to the backend container's `uploads/map/` directory:

1. **For Docker Setup**: Upload PNG files to the `uploads/map/` directory inside the backend container
2. **For Direct Upload**: Use the file upload functionality in your admin panel to upload PNG files to `uploads/map/`
3. **File Naming**: Ensure files follow the pattern `xaero_map_x_y.png` (e.g., `xaero_map_0_0.png`, `xaero_map_1_0.png`)

**Note**: The map assembly process automatically looks for tiles in the backend's `uploads/map/` directory.

## Step 4: Run Map Assembly

1. Go to `/admin/map-management` in your admin panel
2. Click "Karten-Zusammenstellung starten"
3. The system will automatically process all PNG files and create the web map

## Troubleshooting

### No Tiles Found
- Ensure PNG files are in the correct directory
- Check that files follow the naming pattern `xaero_map_x_y.png`
- Verify file permissions allow the server to read the files

### Assembly Fails
- Check server logs for error messages
- Ensure sufficient disk space for processing
- Verify PNG files are not corrupted

### Map Not Displaying
- Check that the assembly completed successfully
- Verify the `map-metadata.json` file was created
- Ensure the frontend can access the generated map tiles

## Example Directory Structure

```
projekt_vollidion_website/
├── map-tiles/
│   ├── xaero_map_0_0.png
│   ├── xaero_map_1_0.png
│   ├── xaero_map_0_1.png
│   ├── xaero_map_1_1.png
│   └── ...
├── backend/
├── frontend/
└── ...
```

## Performance Notes

- Large maps (100+ tiles) may take several minutes to process
- The assembly process is memory-intensive for very large maps
- Consider using a powerful server for initial map generation

## Support

If you encounter issues:
1. Check the browser console for JavaScript errors
2. Review the server logs for backend errors
3. Verify all PNG files are valid and accessible
4. Ensure the map-tiles directory exists and is writable