HUD Compass

A lightweight compass HUD mod that shows a realtime compass at the top of the screen with outside marker mod support.

The compass draws a horizontal strip across the top-center of the screen. As you turn, the strip scrolls to show N / E / S / W (plus small tick marks at the four intercardinal directions - NE, SE, SW, NW) positioned exactly where they'd be on a real compass relative to the direction you're looking. Whatever's dead ahead sits at the center of the strip; everything else slides smoothly across it as you turn, and gets cropped cleanly at the edges instead of popping in and out.

Configuration

A client config is generated on first launch (config/hudcompass-client.toml):

• enabled - toggle the compass strip on/off entirely
• barWidth / barHeight - size of the strip in pixels
• offsetX / offsetY - nudge the strip's position (default: centered, near the top)
• visibleSpanDegrees - how many degrees of the compass are visible across the strip at once, centered on wherever you're facing (default 270)
• markerIconSize - size markers from the API below are drawn at
• showMarkerLabels - toggle the small text label under each marker

Marker API (for other mod/pack developers)

HUD Compass has a simple public API other mods can use to show their own markers on the strip - an icon plus a short text label, positioned by the real-world bearing from the player to wherever the marker is.

// Once - e.g. during client setup: register a marker type (a unique id + the icon to use
// for it, a standalone PNG texture).
static final ResourceLocation DEATH_MARKER_TYPE =
        ResourceLocation.fromNamespaceAndPath("mydeathmod", "death");

CompassMarkerApi.registerMarkerType(DEATH_MARKER_TYPE,
        ResourceLocation.fromNamespaceAndPath("mydeathmod", "textures/gui/skull_marker.png"));

// Whenever you want a marker to appear: add it with a world position and dimension.
// You get a handle back for moving or removing it later.
Deque<MarkerHandle> recentDeaths = new ArrayDeque<>();

void onPlayerDeath(Vec3 deathPos, ResourceKey<Level> dimension) {
    if (recentDeaths.size() >= 10) {
        CompassMarkerApi.removeMarker(recentDeaths.removeFirst());
    }
    String label = String.valueOf(recentDeaths.size() + 1);
    recentDeaths.addLast(CompassMarkerApi.addMarker(DEATH_MARKER_TYPE, label, deathPos, dimension));
}

// Tracking something that moves (a boss, another player)? Just call this again with its
// current position whenever it changes.
CompassMarkerApi.updateMarkerPosition(handle, newPos, dimension);

// And when you're done with a marker:
CompassMarkerApi.removeMarker(handle);

Requirements

• Minecraft 1.21.1
• NeoForge 21.1.176

Disclaimer: This mod is built specifically for, and exclusively supports, the Super Duper Fuel (SDF) modpack, targeting the exact Minecraft/NeoForge versions listed above. It will not be updated for compatibility with other Minecraft versions, other mod loaders (Forge, Fabric, Quilt, etc.), or future NeoForge releases outside of what the SDF pack itself uses. There are no plans to broaden support beyond this pack. Use outside of Super Duper Fuel is possible but entirely unsupported. Please feel free to make your own versions and use this for your own modpacks!

License: MIT License