---
title: Entry Unlocking
hide_meta: true
---

By default, most entries are unlocked by scanning them with a Spyglass. Bosses and certain entities are set to "Kill to Unlock" (requiring the player to kill them). You can customize how an entry is unlocked by adding an `unlock` object to its definition in a category.

> Important Note on IDs:
> Field Guide uses prefixes to categorize entries. When specifying an `id` or a `trigger_on` target, you must prefix standard registries to ensure they match:
> * Entities: `entity:namespace/path` (e.g., `entity:minecraft/cow`)
> * Items: `item:namespace/path` (e.g., `item:minecraft/beef`)
> * Blocks: `block:namespace/path` (e.g., `block:minecraft/grass_block`)

```json
{
  "type": "entry",
  "id": "entity:minecraft/cow",
  "unlock": {
    "unlocked_by_default": false,
    "prerequisites": ["entity:minecraft/pig"],
    "triggers": ["kill", "scan", "obtain"]
  }
}
```

### JSON Structure

| Field | Type | Description |
| --- | --- | --- |
| `unlocked_by_default` | Boolean | (Optional) If true, the entry is unlocked automatically as soon as its prerequisites are met. |
| `prerequisites` | Array | (Optional) A list of entry IDs that must be unlocked before this one can be. |
| `triggers` | Array | (Optional) A list of event types that can trigger the unlock. If empty or omitted, any supported event will trigger it. |
| `trigger_on` | Array / String | (Optional) A list of external resource IDs (e.g., `["entity:minecraft/warden"]`, `["item:minecraft/nether_star"]`) that trigger this entry's unlock. If omitted, the entry's own ID is used as the trigger target. **Note: This should be formatted as a JSON array `["..."]`**. |

### Available Triggers
* `kill`: Killing the entity.
* `scan`: Scanning the entity/block with a Spyglass (or taking a photograph if Exposure is installed).
* `obtain`: Obtaining the item in your inventory.
* `eat`: Eating the edible item.

**Note:** For auto-populated entries, default unlocking rules apply unless overridden:
* Root-level `unlock` on a category JSON applies to all entries and auto-populated strategies in that category.
* An `unlock` object placed directly inside an `auto_populate` block applies to all entries generated by that strategy.
* Explicit entry definitions with an `unlock` object will override category or auto-populate defaults.
* By default, entities with `fieldguide:kill_to_unlock` require a `kill`, blocks/plants require a `scan`, non-block items require an `obtain`, and food requires `eat`.
* Obtaining items can also be disabled globally in `fieldguide-server.json` via `"disableObtainUnlocks": true`.

### Special Item & Entity Tags

Field Guide uses specific tags to handle default scanning and categorization behaviors. Apply these tags to your mod's entities where appropriate:

* `fieldguide:bosses`: Entities with this tag are excluded from the `monsters` and `animals` auto-populate strategies, and are moved to a special `bosses` category.
* `fieldguide:kill_to_unlock`: Entities with this tag can't be scanned with a spyglass or the naked eye: the player must kill them to unlock their entry. (Defaults to all bosses). This can be overridden per-entry using the `unlock` object.
* `fieldguide:eat_to_unlock`: Items with this tag must be eaten to unlock their entry. (Defaults to all edible items). This can be overridden per-entry using the `unlock` object.

---

### Advanced Unlocking

You can use the `trigger_on` field to unlock an entry based on an external action. This is particularly useful for **Virtual Entries** or entries that represent concepts rather than specific objects.

**Example: Unlocking a "Combat Master" virtual entry when killing a Warden:**

```json
{
  "type": "virtual_entry",
  "id": "my_mod:combat_mastery",
  "virtual_type": "tutorial",
  "unlock": {
    "triggers": ["kill"],
    "trigger_on": ["entity:minecraft/warden"]
  }
}
```

**Example: Unlocking an entry when obtaining a specific item:**

```json
{
  "type": "virtual_entry",
  "id": "my_mod:nether_expert",
  "virtual_type": "lore",
  "unlock": {
    "triggers": ["obtain"],
    "trigger_on": ["item:minecraft/nether_star"]
  }
}
```