Minecraft Mod Documentation

Everything about the MattCraft custom mod

Login

📦 About the MattCraft Mod

The MattCraft mod is a custom Fabric mod built for Minecraft 1.21.1 that integrates with the companion web app and BlueMap to provide enhanced server features and tracking.

🎯 Core Features

🗺️ BlueMap Sign Marker Detection

Automatically detects when players place signs in the game world and creates persistent markers on the BlueMap. These markers are stored in the database and survive server restarts.

  • Automatically scans for new signs every 5 seconds
  • Creates POI markers on BlueMap at sign locations
  • Uses the first line of the sign as the marker title
  • Markers are stored in the database for persistence
  • On server restart, all markers are recreated from database

🏆 Showcase Auto-Generation

When a sign marker is created, the mod automatically generates a showcase entry in the companion app. This links map markers to the showcase system.

  • Creates placeholder showcase with sign text as title
  • Marked as "auto-generated" in the database
  • Players can upload photos and descriptions later
  • Linked to season objectives for tracking progress

🔄 HTTP API Integration

The mod communicates with the companion app via HTTP REST API to save marker data and create showcases.

  • API Base URL: http://172.17.0.1:3000/api
  • POST to /api/markers to save marker data
  • POST to /api/showcases/from-marker to create showcase
  • GET from /api/markers on server startup to restore markers

🏗️ Technical Architecture

Minecraft Mod

  • Minecraft Version: 1.21.1
  • Mod Loader: Fabric
  • Language: Java 21
  • Build Tool: Gradle 8.10.2

Dependencies

  • Fabric API
  • BlueMap API (for marker management)
  • Java HttpURLConnection (for HTTP requests)

Companion App

  • Framework: Next.js 14
  • Database: SQLite (better-sqlite3)
  • API: REST endpoints
  • Authentication: Session-based with device pairing

Deployment

  • Server: Docker container
  • Companion App: Runs outside Docker on host
  • Database: Shared SQLite file at /opt/docker/mattcraft_dev/companion-app/data/mattcraft.db
  • Docker Gateway: 172.17.0.1 (for mod → app communication)

📁 Project Structure

mattcraft_dev/
├── src/main/java/com/mattcraft/
│   └── SignMarkerManager.java       # Main marker detection logic
├── build.gradle                     # Gradle build configuration
├── gradle.properties                # Mod metadata
├── server/                          # Minecraft server files
│   ├── mods/                        # Deployed mod JAR
│   └── config/bluemap/              # BlueMap configuration
├── companion-app/                   # Next.js web app
│   ├── app/api/                     # REST API endpoints
│   ├── app/showcase/                # Showcase page
│   ├── app/season/                  # Season objectives tracker
│   ├── lib/db.ts                    # Database schema
│   └── data/mattcraft.db            # SQLite database
└── scripts/
    ├── build-mod.sh                 # Build the mod JAR
    └── deploy-mod.sh                # Deploy to server

🔧 Development Workflow

Building the Mod

# Using Docker for consistent build environment
./scripts/build-mod.sh

# Or manually with Gradle
./gradlew build

Deploying to Server

# Build and deploy in one step
./scripts/deploy-mod.sh

# Or manually copy the JAR
cp build/libs/mattcraft-mod-1.0.0.jar server/mods/

Testing Changes

# Start the companion app
cd companion-app
npm run dev

# Start the Minecraft server
docker compose up -d

# Watch server logs
./scripts/server-logs.sh

🐛 Debugging

Common Issues

Markers not persisting across restarts

  • Check if mod is deployed: ls -la server/mods/
  • Verify API URL is correct: should be 172.17.0.1:3000
  • Check companion app logs for API errors
  • Verify middleware allows /api/markers and /api/showcases

HTTP connection failed

  • Ensure companion app is running on port 3000
  • Test from inside Docker: docker exec -it mattcraft-server curl http://172.17.0.1:3000/api/markers
  • Check Docker network gateway: docker network inspect bridge | grep Gateway

Showcases not appearing

  • Check database: sqlite3 companion-app/data/mattcraft.db "SELECT * FROM showcases;"
  • Verify uploaded_by can be NULL (for auto-generated)
  • Check is_auto_generated column exists
  • Clear Next.js cache: rm -rf companion-app/.next

📊 Database Schema

markers

  • id - Primary key
  • marker_id - Unique BlueMap marker ID
  • block_x, block_y, block_z - Sign coordinates
  • world - Minecraft world name
  • sign_text - First line of sign
  • showcase_id - Foreign key to showcases
  • created_at - Unix timestamp

showcases

  • id - Primary key
  • title - Showcase title (from sign or user)
  • description - Optional description
  • image_url - Path to image (placeholder or uploaded)
  • uploaded_by - User ID (nullable for auto-generated)
  • is_auto_generated - 1 if created by mod, 0 if user-created
  • marker_id - Link to BlueMap marker
  • coordinates - Optional coordinate string
  • created_at, updated_at - Timestamps

objectives

  • id - Primary key
  • category - Category name (Farms, Utility, etc.)
  • name - Objective name
  • completed - 0 or 1
  • showcase_id - Foreign key to showcases
  • marker_id - Link to BlueMap marker
  • completed_by - User who completed it
  • completed_at - Completion timestamp
  • points, description, display_order - Metadata

🚀 Future Enhancements

  • Real-time marker updates (WebSocket integration)
  • Multiple photos per showcase
  • Comments and reactions on showcases
  • Marker categories and filtering
  • Notification system for new markers
  • Achievement system linked to objectives