Revelationary

What this mod is about

Revelationary provides a system for gradually discovering blocks and items, controlled through configuration files. Mod and modpack developers can now create progressive world exploration with step-by-step discovery of new resources as players progress through content.

Core principle of operation

Instead of overwhelming players with all available resources from the start, the system allows to hide certain blocks under the appearance of familiar ones. For example, instead of a rare ore, the player sees ordinary stone. Only after achieving a specific milestone (such as defeating the Ender Dragon) does the mystery unravel - and the player begins noticing these blocks in their natural environment.

Key advantages

• Progressive development - players aren't overwhelmed with excess unknown resources at game start
• Individual discoveries - system works independently for each player
• High performance - implementation is optimized and doesn't create additional load
• Elegant integration - hidden blocks maintain properties and drops of the masking block until discovery

Technical limitations

When selecting masks for blocks, consider that they inherit all physical properties of the original:

• Hitbox size and shape
• Light permeability
• Other technical characteristics

Optimal candidates for ore masking include stone or deepslate, which share similar parameters. You can also mask special plants as poppies - both have small hitboxes and are passable for players.

For developers

If you're a programmer, use the Revelation API to dynamically change block properties depending on their visibility. This opens possibilities like creating flowers completely hidden in air space.

Configuration via Data Pack

Configuration files are placed in the directory resources/data/<mod_id>/revelations

Example configuration file:

{
  "advancement": "spectrum:milestones/reveal_quitoxic_reeds",
  "block_states": {
    "minecraft:grass": "minecraft:beacon",
    "minecraft:tall_grass": "minecraft:obsidian", 
    "minecraft:tall_grass[half=upper]": "minecraft:netherite_block"
  },
  "items": {
    "minecraft:nether_star": "minecraft:gunpowder"
  }
}

Creating hidden elements

Developers need to implement the RevelationAware interface:

public class HiddenItem extends Item implements RevelationAware {

    Identifier advancementForDiscovery;
    Item displayAsItem;

    public HiddenItem(Settings settings, Identifier advancementForDiscovery, Item displayAsItem) {
        super(settings);
        this.advancementForDiscovery = advancementForDiscovery;
        this.displayAsItem = displayAsItem;

        registerDisguise();
    }

    @Override
    public Identifier getAdvancementNeeded() {
        return advancementForDiscovery;
    }

    @Override
    public Hashtable<BlockState, BlockState> getBlockStateDisguises() {
        return new Hashtable<>();
    }

    @Override
    public Pair<Item, Item> getItemDisguise() {
        return new Pair<>(this, displayAsItem);
    }

    @Override
    public void onHide() { }

    @Override
    public void onReveal() { }
}

Reacting to secret discoveries

You can set up code execution upon discovery of hidden content:

RevelationHolder.registerDiscoveryCallback(new RevelationHolder.RevealCallback() {
    @Override
    public void trigger(List<Identifier> advancements, List<Block> blocks, List<Item> items) {
        for(Block block : blocks) {
            if(Registry.BLOCK.getId(block).getNamespace().equals(YOUR_MOD_ID)) {
                // Place your code here
                // For example, show a popup notification
                break
            }
        }
    }
});