project_vollidioten_website/MAP_SETUP_GUIDE.md

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