Field Guide

Field Guide is an exploration-focused mod that acts as an in-game encyclopedia! It encourages players to observe the world around them using a Spyglass. By looking at entities and specific blocks, you can scan them, unlocking entries in your Field Guide.

Gameplay & Usage

Using a standard Minecraft Spyglass, zoom in and look directly at a mob or specific blocks (like flora). A scanning reticle will appear over the target, and after a set duration (default 1 second), a sound will play and the entry will be unlocked.

To open the guide:

• Press 'B' (default).
• Click the book icon in the Inventory Screen or Pause Menu.

---

Configuration

The configuration file is located at .minecraft/config/fieldguide.json.

Entity Blacklist Format

You can blacklist specific entities or entire mods.

• Specific ID: minecraft:armor_stand
• Wildcard: mod_id:* (Blacklists everything from that mod)

Discovery Redirects

Sometimes you may want scanning one entity to unlock the entry for a different one. This is useful for entities that have multiple variations or distinct parts (like multi-part bosses) where scanning any part should unlock the main entry.

Format: namespace:scanned_id|namespace:unlock_id

• Example: Scanning a Vampire Biter from Enemy Expansion unlocks the Vampire entry.

enemyexpansion:vampire_biter|enemyexpansion:vampire

Loot Configuration Format

For lootRemovals and lootAdditions, strings must be formatted as: namespace:entity_id|namespace:item_id

• Example Removal: minecraft:skeleton|minecraft:bone (Hides Bones from Skeleton page)
• Example Addition: minecraft:cow|minecraft:milk_bucket (Adds Milk Bucket to Cow page)

---

Commands

Admin commands are available for debugging or map-making purposes. Requires OP.

Granting Entries

Unlock entries for a player without scanning.

• Unlock Everything: /fieldguide grant <player> everything
• Unlock Specific Category: /fieldguide grant <player> category <namespace:category_id>
• Unlock Specific Entry: /fieldguide grant <player> only <namespace:entity_or_block_id>

Revoking Entries

Lock entries again (reset progress).

• Revoke Everything: /fieldguide revoke <player> everything
• Revoke Specific Category: /fieldguide revoke <player> category <namespace:category_id>
• Revoke Specific Entry: /fieldguide revoke <player> only <namespace:entity_or_block_id>

---

Datapacks (Customizing Content)

You can add new categories, reorganize existing ones, or add modded entities to the Field Guide using standard Minecraft Datapacks.

Defining Categories

Category files are JSON files located at: data/<namespace>/fieldguide/categories/<filename>.json

The filename becomes the ID of the category (e.g., wetlands.json becomes <namespace>:wetlands).

JSON Structure

Field	Type	Description
sort_index	Integer	Determines the tab order (lower numbers are first).
replace	Boolean	(Optional) If true, clears existing entries in this category before adding new ones.
contents	Array	A list of entry objects.

Removing Default Categories

To remove a category provided by the mod (or another datapack), create a file with the same ID and use "replace": true with an empty contents list. The Field Guide automatically hides empty categories.

Example: Removing the default monsters category:

data/fieldguide/fieldguide/categories/monsters.json

{
  "replace": true,
  "contents": []
}

Content Types

1. Manual Entry: Adds a specific Entity or Block.

{
  "type": "entry",
  "id": "minecraft:pig"
}

2. Auto-Populate: Automatically adds entries based on a preset strategy.

{
  "type": "auto_populate",
  "strategy": "hostile"
}

Available Strategies:

• passive: All passive animals.
• hostile: All hostile monsters.
• flora: All vanilla-like plants.
• mod:<mod_id>: All entities from a specific mod.
• mod_flora:<mod_id>: All flora-like blocks from a specific mod.
• tag:<tag_id>: All entities with a specific tag (e.g. tag:minecraft:raiders).

Example: Custom Category

data/mypack/fieldguide/categories/swamp_life.json

{
  "sort_index": 5,
  "contents": [
    {
      "type": "entry",
      "id": "minecraft:frog"
    },
    {
      "type": "entry",
      "id": "minecraft:witch"
    },
    {
      "type": "entry",
      "id": "minecraft:lily_pad"
    }
  ]
}

---

Resource Packs (Customizing Visuals)

You can customize the appearance of categories, render settings for entities, and descriptions using Resource Packs.

Category Visuals

To customize the icon and color of a category tab, create a JSON file at: assets/fieldguide/visuals/categories/<category_name>.json

Note: The filename must match the path of the category ID.

{
  "color": "#32a852",
  "icon": "minecraft:textures/item/slime_ball.png"
}

Entry Configuration (Scaling & Offsets)

Sometimes entities or blocks render too large, too small, or off-center in the book. You can adjust this by creating a JSON file at: assets/<namespace>/fieldguide/visuals/entries/<entry_id>.json

For example: assets/minecraft/fieldguide/visuals/entries/pig.json makes adjustments to minecraft:pig.

JSON Structure

Field	Type	Description
id	String	(Optional) The ID of the entity/block to target (e.g., minecraft:cow). If omitted, the filename and path determine the ID.
scale	Float	Base scale multiplier. 1.0 is default size, 0.5 is half size, 2.0 is double.
y_offset	Float	Moves the model up/down globally.
x_offset	Float	Moves the model left/right globally.
auto_rotate	Boolean	(Optional) Overrides the global auto-rotate setting for this specific entry.
rotation_speed	Float	(Optional) Overrides the global rotation speed setting for this specific entry.
grid_scale	Float	(Optional) Overrides scale specifically for the grid view.
page_scale	Float	(Optional) Overrides scale specifically for the detailed page view.

Example: Adjusting a Creeper

assets/fieldguide/visuals/entries/creeper.json

{
  "id": "minecraft:creeper",
  "scale": 0.8,
  "y_offset": 10.0,
  "page_scale": 1.2
}

Descriptions & Localization

By default, Field Guide uses descriptions from Item Descriptions and its addon resource pack Mod Descriptions. To add names to custom categories or descriptions to entries, add lines to your en_us.json (or other language file).

Type	Key Format	Example
Category Name	category.fieldguide.<category_id>	"category.fieldguide.swamp_life": "Swamp Life"
Entry Description	fieldguide.<namespace>.<id>.description	"fieldguide.minecraft.pig.description": "A common farm animal..."

Texture Overrides (2D Sprites)

If an entity renders poorly (or if you prefer 2D illustrations), you can force the Field Guide to use a texture instead of the 3D model.

Place textures in: assets/<namespace>/textures/fieldguide/entries/

The mod looks for textures in this specific order:

1. View-Specific: <id>_page.png (Used on the details page) or <id>_grid.png (Used in the list).
2. General: <id>.png (Used for both if specifics aren't found).

Example: To override the specific rendering of a pig in minecraft, place a file at assets/minecraft/textures/fieldguide/entries/pig.png.

---

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.