Xaero Progressive Radar

Minecraft 版本： 1.20.1

平台： forge

标签： game-mechanics library

Xaero Progressive Radar

Xaero Progressive Radar is a Forge 1.20.1 addon that hides selected entity types from Xaero's entity radar until each player completes the configured advancements.

The progression model is intentionally similar to Revelationary: datapack rules describe what an advancement reveals, advancement progress is the source of player state, and the client recalculates visibility when it receives Minecraft advancement updates.

Behavior

• An entity type referenced by no radar rule is left untouched and remains subject only to Xaero's own settings.
• A referenced entity type is hidden until the player completes at least one advancement mapped to it.
• Revoking the completed advancement hides the entity again, unless another completed rule also maps to it.
• Rules are per player because advancement progress is per player.
• Xaero's own radar categories, ranges, icons, and master enable switches still apply after this addon allows an entity through.

In set notation, the client calculates:

hidden = all entity types named by rules
         - entity types named by completed advancement rules

This has two useful consequences. Unconfigured entities never disappear accidentally, and overlapping rules use intuitive OR semantics.

Requirements and installation

• Minecraft 1.20.1
• Forge 47.x
• Xaero's Minimap 23.6.1 or newer on every client
• This addon on the server and every client
• Xaero's World Map is optional

Place the built jar in the server and client mods directories. Put radar progression rules in a normal datapack under the world's datapacks directory, then run /reload or restart the server.

The server config is generated at:

world/serverconfig/xaeroprogressiveradar-server.toml

It contains only the permission level for /progressiveradar. Radar visibility itself is data-driven.

Datapack rule format

Rules are JSON files at:

data/<namespace>/xaero_progressive_radar/<path>.json

Example data/modpack/xaero_progressive_radar/undead.json:

{
  "advancement": "modpack:progression/discovered_undead",
  "entity_types": [
    "minecraft:zombie",
    "minecraft:skeleton"
  ],
  "entity_type_tags": [
    "modpack:radar/tier_1"
  ]
}

Fields:

At least one of entity_types or entity_type_tags must be present and non-empty. Both may be used in one rule. Unknown entity IDs simply expand to nothing, which allows rules to mention entities from optional mods. A malformed rule is skipped and logged with its resource ID.

Entity type tags

Tags are convenient for tiers shared by several rules. Create, for example, data/modpack/tags/entity_types/radar/tier_1.json:

{
  "replace": false,
  "values": [
    "minecraft:zombie",
    "minecraft:skeleton",
    "minecraft:spider"
  ]
}

Reference it as "modpack:radar/tier_1" in entity_type_tags. Tags are expanded on the server after datapack loading, then concrete entity IDs are sent to clients. Clients therefore do not need a duplicate copy of the server datapack.

Multiple and overlapping rules

Multiple files may reference the same advancement; their entity selections are merged. Multiple advancements may also reference the same entity. In the latter case, any one completed advancement reveals that entity:

rule A: advancement modpack:first  -> zombie, skeleton
rule B: advancement modpack:second -> zombie

neither completed -> zombie and skeleton hidden
only second done  -> zombie visible, skeleton hidden
either rule done for zombie -> zombie visible

If strict sequential tiers are required, express that dependency in the advancement definitions themselves. Advancement definitions own all tier dependencies.

Commands

Commands require permission level 2 by default. They modify the criteria of the mapped advancements, following Revelationary's command utility behavior. They never write a radar-specific unlock value.

Entity-oriented commands

Entity selectors are resolved back to every advancement whose loaded radar rule selects them:

progressiveradar set @a minecraft:creeper true
progressiveradar grant @p minecraft:zombie
progressiveradar revoke @p minecraft:zombie
progressiveradar grant @s #modpack:radar/tier_1

grant/true awards every criterion of the mapped advancements; revoke/false revokes every criterion. Because the command changes the advancement itself, all other entities mapped to the same advancement change with it. The command fails when no loaded rule maps the entity selection.

Advancement-oriented commands

For unambiguous pack scripts, address the mapped advancement directly:

progressiveradar advancement grant @p modpack:progression/discovered_undead
progressiveradar advancement revoke @p modpack:progression/discovered_undead

Only advancements referenced by loaded radar rules are accepted. Tab completion suggests those IDs.

Granting all criteria completes the real advancement and can run its rewards, reward functions, announcements, or dependent criteria. This is deliberate. Use a dedicated hidden advancement with no rewards when a pack needs a radar-only milestone.

Bulk and inspection commands

progressiveradar all @p true
progressiveradar all @p false
progressiveradar query PlayerName minecraft:skeleton
progressiveradar query PlayerName #modpack:radar/tier_1

all grants or revokes every advancement referenced by a loaded radar rule. query separates unmanaged types from progression-managed types, then reports how many managed types are unlocked or still hidden. "Unmanaged" means this addon does not filter the type; Xaero's own settings still decide whether it is rendered.

The ordinary Minecraft command remains valid as well:

advancement grant @p only modpack:progression/discovered_undead
advancement revoke @p only modpack:progression/discovered_undead

Any mechanism that changes the mapped advancement progress produces the same radar result.

Synchronization design

The synchronization path is modeled after Revelationary:

1. The server reload listener parses radar JSON rules.
2. Entity type tags are expanded against the live server registry.
3. On login and datapack reload, the server sends only the advancement -> concrete entity IDs mapping.
4. The client listens to Minecraft advancement update packets and keeps the completed advancement ID set.
5. The client derives the hidden entity set from the rule mapping and completed set.
6. Xaero's radar entity iterable is filtered against that immutable snapshot.

Packet order is not significant. If the initial Minecraft advancement packet arrives first, its completed IDs are retained until the rule mapping arrives. If rules arrive first, managed entities remain hidden until the initial progress packet is processed. Logging out clears both client sets.

Advancement persistence, commands, syncing, and datapack reload behavior remain authoritative.

Xaero Minimap and World Map compatibility

The addon supports both Xaero Minimap radar implementations used by the legacy 23.x line and newer releases. Xaero does not currently expose a public per-entity radar filter callback, so the integration uses two optional, narrowly scoped mixins. Each wraps only the Iterable<Entity> consumed by Xaero's radar updater.

Xaero's World Map does have entity radar rendering, but it does not collect an independent entity list. During full-screen radar rendering it asks Xaero's Minimap to update the shared radar state through its compatibility layer. Filtering the Minimap radar input therefore covers both:

• the minimap entity radar;
• the full-screen Xaero World Map entity radar.

The addon does not alter ClientLevel entity storage, entity tracking packets, Minecraft rendering, spawning, AI, hitboxes, commands, or another mod's entity queries. Other entity displays are unaffected unless they intentionally consume Xaero's own shared radar state.

Datapack development workflow

1. Create or choose the advancement that owns the unlock.
2. Add one or more radar rule files under xaero_progressive_radar.
3. Run /reload.
4. Check the server log for Loaded <n> progressive radar advancement rule(s).
5. Use /progressiveradar query before and after granting the advancement.
6. Test both grant and revoke; revoke behavior catches stale client-state mistakes.
7. When using tags, test with every optional mod combination represented by the pack.

A complete example is available at examples/xaero-progressive-radar-example.

Troubleshooting

• An entity is always visible: verify its exact registry ID is selected by a loaded rule and that Xaero's entity radar itself is enabled.
• An entity is always hidden: verify the advancement ID exists and is actually complete with /advancement test or /progressiveradar query.
• A command changes more entities than expected: those entities share the same mapped advancement. Split them across dedicated advancements if they must unlock independently.
• A tag selects nothing: verify the file is under tags/entity_types, not tags/entities, and omit # inside the radar JSON.
• Rules did not update: inspect the reload error in the server log. Invalid JSON rules are skipped rather than partially applied.
• World Map shows no icons even after unlock: Xaero Minimap's own radar settings and World Map radar option still need to allow those icons.