Archaeology Compass

Spend less time searching for suspicious blocks and more time uncovering their loot.

Archaeology Compass adds a craftable copper compass that points toward the nearest suspicious sand or suspicious gravel with archaeology loot still inside. Keep it in your inventory while exploring, and let the needle guide you to nearby finds.

This is a nearby block finder—not a long-range structure locator. You still need to explore the world and get close to an archaeological site.

Features

• Find nearby archaeology loot. Locate suspicious sand and suspicious gravel that still have loot to uncover.
• Works from your inventory. You do not need to keep the compass in your hand.
• Updates as you explore. The compass searches again when its next scan detects that a target has been brushed out, broken, or moved outside the search range.
• Spins without a usable target. The needle keeps rotating when no valid synchronized target is available. Hold Shift to distinguish waiting for a result from a scan that found nothing.
• Shift for details. Hold Shift over the item to see search rules, the server's scan range, and the current search status.
• Loaded chunks only. Searching does not force distant chunks to load or generate.
• Configurable on the server. Adjust the horizontal radius, vertical radius, and scan interval.
• Original artwork. A 32×32, 32-frame copper compass with the balanced V2 shell: a subtle two-row copper side wall, a dark bottom edge, a pale-gold needle, and a green tail.
• English and Simplified Chinese item text.

How to use

1. Craft an Archaeology Compass and keep it in your player inventory.
2. Explore areas containing suspicious sand or suspicious gravel.
3. Follow the pale-gold end of the needle toward the nearest valid target.
4. Brush the target to uncover its loot. The compass selects another target on a later scan if one is available.

By default, the compass searches within a 64-block horizontal radius and 32 blocks above and below you. It updates every 20 game ticks, roughly once per second at normal server speed. Vertical distance does not reduce the horizontal search radius.

A newly acquired compass may need to wait until the next scan before receiving a result. The compass does not reveal the contents of the loot or display target coordinates.

Crafting

Use 2 brushes, 2 copper ingots, and 1 compass in a crafting table:

Produces 1 Archaeology Compass. The recipe is configured to unlock in the recipe book after obtaining a brush or a compass.

JEI is not required. The mod uses a standard shaped crafting recipe; its display in JEI has not yet been verified in-game for this prerelease.

Requirements and installation

• Minecraft: 1.21.1
• Mod loader: NeoForge
• NeoForge dependency minimum: 21.1.235. Any newer version must also be compatible with Minecraft 1.21.1; newer loader versions have not been separately verified.
• Java: 21

Install the mod file into your instance's mods folder. For single-player, install it on the client. For multiplayer, both the server and every joining client need the mod.

This build targets NeoForge only. Forge, Fabric, and other Minecraft versions are not supported by this file.

Server configuration

The server controls these settings, including the integrated server in single-player. Larger scan ranges and shorter intervals increase scanning work; performance in large multiplayer environments has not yet been benchmarked.

Prerelease status and limitations

Version 0.1.2 is an early prerelease focused on artwork. It was validated in a development client on a newly created world: crafting, the needle pointing at a nearby target, the Shift tooltip including its "target found" state, and the V2 artwork in game were all confirmed.

The following have not been verified for this release, and no claim is made about them: installation from the release JAR in a clean instance, dedicated-server multiplayer, JEI display, and performance under large scan ranges or high player counts. Expect possible issues and please report them.

• Only loaded chunks within the configured range are searched.
• Block changes and ordinary inventory changes are reflected on the next scan, not instantly.
• Adding a third-party block to archaeologycompass:archaeology_targets is not enough by itself. Its block entity must be a Minecraft BrushableBlockEntity or a subclass and pass the mod's loot-state checks. Arbitrary custom archaeology implementations are not supported.

Modpacks, license, and support

You may include this mod in modpacks under its applicable license terms.

• Code and non-artwork project content: MIT License.
• Compass textures and the specified artwork previews: Creative Commons Attribution 4.0 International, with scope and attribution details in the artwork license notice.

These licenses apply to different parts of the project, not as a choice of license for every file. Keep the required notices, credit the artwork where applicable, and indicate artwork modifications when distributing them.

Artwork credit: Archaeology Compass artwork by luanma114, licensed under CC BY 4.0.

Found a problem? Please open an issue with your Minecraft, NeoForge, and mod versions, whether you are playing single-player or multiplayer, and steps to reproduce it. Include relevant logs if available, and remove private information before sharing them.

Source code

3. 中文说明

中文介绍：考古罗盘

考古罗盘新增一枚可合成的铜制罗盘，帮助寻找附近仍有考古战利品的可疑沙子和可疑沙砾。

它寻找的是附近的考古方块，不是远距离遗迹建筑。你仍需先探索并接近考古地点。

• 放在玩家物品栏里即可生效，不必一直拿在手中。
• 浅金色长针指向最近目标，绿色短尾用于区分方向。
• 默认水平搜索半径为 64 格，上下各 32 格，每 20 Tick 更新一次。
• 目标刷空、被挖掉或离开范围后，在下一扫描周期重新寻找；没有目标时指针持续旋转。
• 按住 Shift 查看扫描规则、服务器范围和搜索状态。
• 只搜索已加载区块，不会为了定位加载远处区域。
• 合成需要 两把刷子、两个铜锭和一个指南针：上下放刷子，左右放铜锭，中央放指南针。

版本要求：Minecraft 1.21.1、NeoForge 21.1.235 或更新的 1.21.1 兼容版本、Java 21。 更新的 NeoForge 版本未逐一验证。多人游戏需要客户端和服务器都安装；此文件不支持 Forge、Fabric 或其他 Minecraft 版本。

代码及非美术内容采用 MIT，指定美术资源采用 CC BY 4.0；两者按内容分别适用。整合包可以在遵守相应许可条款的前提下收录。问题反馈请提交 Issue。