The Research System is a fully data-driven progression framework that allows mods and datapacks to gate recipes, items, equipment and other content behind customizable research projects.

Each research project can require materials, NPC progression, previous discoveries and random events, allowing authors to create complete research trees without writing additional code.

Overview

Each research entry represents a discovery that players can complete by providing required materials and waiting for the research process to finish.

The Research System supports:

• Categories.
• Rarity.
• Repeatable research projects.
• Custom ingredients.
• Research duration.
• Rank requirements.
• Progress messages.
• Multiple reward types.
• Research prerequisite.
• Random research events.

Chronicler Interface

Research projects are managed through the Chronicler, who serves as the player's researcher throughout the progression system.

The interface displays:

• The Chronicler's current rank.
• Experience towards the next rank.
• Current research status.
• Research progress.
• Required materials.
• The active research project.

File Location

Research files are stored inside:

• data/namespace/research/your_research_file.json

Example:

• data/mythsandlegends/research/tenebrite_refinement_research.json

Research File Structure

A research file follows this format:

    {
      "id": "namespace:research_id",
      "name": "Research Name",
      "category":"combat",
      "rarity": "rare",
      "repeatable": false,
      "ingredients": [],
      "research_time": 12000,
      "required_rank": 1,
      "messages": {},
      "rewards": [],
      "required_research":[],
      "random_events":[]
    }

Research ID

The id property uniquely identifies a research project.

This identifier is also used by required_research when creating research dependencies. Format:

• namespace:research_name

Example:

"id": "mythsandlegends:tenebrite_refinement"

Each research must have a unique ID.

Name:

• Defines the display name of the research.

Example:

"name": "Refined Tenebrite Research Notes"

Category

The category property classifies a research project into a specific group, similar to how Minecraft categorizes recipes and advancements.

Categories may be used by the interface or other systems to organize research projects. Example:

    "category": "combat"

• Building Blocks
• Decorations
• Redstone
• Transportation
• Tools
• Combat
• Food
• Brewing
• Misc

Rarity

The rarity property uses Minecraft's built-in rarity system to determine the visual rarity of a research project.

Supported values are the vanilla rarities:

• Common
• Uncommon
• Rare
• Epic

Example:

    "rarity": "epic"

Repeatable

Research projects may optionally be repeatable.

• When enabled, the research can be completed multiple times.
• When disabled, the research becomes permanently completed after being claimed.

Example:

    "repeatable": true

Ingredients

The ingredients property defines the materials required to begin the research.

Example:

    "ingredients": [
        {
            "item": "mythsandlegends:tenebrite_shard",
            "count": 2
        }
    ]

This requires:

• 2x Tenebrite Shards

Multiple ingredients can be added:

    "ingredients": [
        {
            "item": "minecraft:diamond",
            "count": 3
        },
        {
            "item": "minecraft:gold_ingot",
            "count": 5
        }
    ]

Research Time

The research_time property controls how long the research takes.

The value is measured in Minecraft ticks.

20 ticks = 1 second

Example:

"research_time": 12000

Results in:

• 10 minutes.

Required Rank

The required_rank property defines the minimum NPC rank required for this research to become available.

The Research NPC is only responsible for providing available research projects. Once a player starts or completes a research, the progress is stored individually for that player.

Example:

"required_rank": 1

The Research NPC must have the required skill at rank number or higher.

If the NPC is removed or dies, player research progress is preserved.

Ranks can be used to create progression tiers:

Player Progress

Research progress is stored per player, similar to Minecraft advancements and recipe unlocks.

Each player has independent research data:

Player A:

• Refined Tenebrite -> Completed ✓

Player B:

• Refined Tenebrite -> Not researched ✗

Research completion is not tied to the Research NPC.

Messages

Messages allow custom notifications during the research process.

All messages use Minecraft translation keys.

Example:

"messages": {
    "start": "research.example.start",
    "ready": "research.example.ready",
    "completed": "research.example.completed"
}

Start Message:

• Displayed when the research begins.

Example:

"start": "research.mythsandlegends.tenebrite_refinement.start"

Progress Messages

• Progress messages are displayed at specific completion percentages.

Example:

"progress": [
    {
        "at": 0.25,
        "dialogue": "research.mythsandlegends.tenebrite_refinement.progress1"
    },
    {
        "at": 0.50,
        "dialogue": "research.mythsandlegends.tenebrite_refinement.progress2"
    },
    {
        "at": 0.75,
        "dialogue": "research.mythsandlegends.tenebrite_refinement.progress3"
    }
]

Available values:

Ready Message:

• Displayed when the research timer finishes.

Example:

"ready": "research.mythsandlegends.tenebrite_refinement.ready"

At this point the player can claim the reward.

Completed Message

Displayed after the reward has been claimed.

Example:

"completed": "research.mythsandlegends.tenebrite_refinement.completed"

Rewards

The rewards property defines what the player receives after completing the research.

Recipe rewards are delivered through Research Notes. Research Notes permanently store every unlocked recipe. Players must use the notes to permanently learn the contained recipes.

Item rewards are granted immediately when the research is claimed.

Reward Types:

The Research System currently supports the following reward types:

Recipe Example:

{
    "type": "recipe",
    "id": "minecraft:enchanting_table"
}

Item Example:

{
    "type": "item",
    "id": "minecraft:enchanting_table"
}

Enchanted Book Example:

{
  "type": "enchanted_book",
  "enchantment": "minecraft:sharpness",
  "level": 3,
  "count": 1
}

Properties:

Potion Reward (Vanilla Potion):

Creates one or more vanilla potions.

Container Types:

• potion
• splash_potion
• lingering_potion

Potion Example:

{
  "type": "potion",
  "potion": "minecraft:health_boost",
  "container": "splash_potion",
  "count": 2
}

Potion Reward (Custom Effects)

Potion rewards can also define their own effects instead of referencing an existing vanilla potion. Custom Potion Example:

{
  "type": "potion",
  "container": "lingering_potion",
  "count": 1,
  "effects": [
    {
      "effect": "minecraft:regeneration",
      "duration": 600,
      "amplifier": 1
    },
    {
      "effect": "minecraft:absorption",
      "duration": 200,
      "amplifier": 0
    }
  ]
}

Each effect supports:

Rewards can be freely combined. A single research may grant multiple rewards of different types, such as recipes, items, enchanted books and potions.

Required Research

The required_research property defines one or more prerequisite research projects that must be completed before the current project becomes available.

Each entry references the research ID of another research project. Example:

"required_research": [
    "mythsandlegends:refined_tenebrite"
]

Example Progression:

• Tenebrite Shard -> Refined Tenebrite -> Noctifer Tenebris

Multiple prerequisite research projects are also supported.

"required_research": [
    "mythsandlegends:research_a",
    "mythsandlegends:research_b "
]

All listed prerequisite research projects must be completed before this research becomes available.

Complete Example:

{
  "id": "mythsandlegends:refined_tenebrite",
  "name": "Tenebrite Refinement Research Notes",
  "repeatable": false,
  "category": "material",
  "rarity": "uncommon",
  "ingredients": [
    {
      "item": "mythsandlegends:tenebrite_shard",
      "count": 8
    },
    {
      "item": "mythsandlegends:cursed_core",
      "count": 1
    }
  ],
  "research_time": 12000,
  "required_rank": 1,
  "messages": {
    "start": "research.mythsandlegends.refined_tenebrite.start",
    "progress": [
      {
        "at": 0.25,
        "dialogue": "research.mythsandlegends.refined_tenebrite.progress1"
      },
      {
        "at": 0.50,
        "dialogue": "research.mythsandlegends.refined_tenebrite.progress2"
      },
      {
        "at": 0.75,
        "dialogue": "research.mythsandlegends.refined_tenebrite.progress3"
      }
    ],
    "ready": "research.mythsandlegends.refined_tenebrite.ready",
    "completed": "research.mythsandlegends.refined_tenebrite.completed"
  },
  "rewards": [
    {
      "type": "recipe",
      "id": "mythsandlegends:refined_tenebrite"
    },
    {
      "type": "item",
      "id": "minecraft:experience_bottle",
      "count": 4
    }
  ],
  "required_research": [],
  "random_events": [
    {
      "type": "distraction",
      "chance": 0.02
    },
    {
      "type": "focused",
      "chance": 0.02
    }
  ]
}

Random Events

Research projects may define random events that can occur while the Chronicler is researching.

Example:

"random_events": [
    {
        "type": "breakthrough",
        "chance": 0.04
    },
    {
        "type": "mistake",
        "chance": 0.03
    }
]

Supported event types:

Every second while researching, the Chronicler has a chance to trigger one of the configured events.

Translation File

Research messages must be added inside the mod/datapack language file.

Location:

• assets/namespace/lang/en_us.json

Example:

{
  "research.mythsandlegends.refined_tenebrite.start":
  "The Tenebrite Shards are unstable. I must discover how to refine their umbral essence.",

  "research.mythsandlegends.refined_tenebrite.ready":
  "I have already mastered the refinement of Tenebrite."
}

Developer Notes:

• Research files are completely data-driven.
• Modpacks can add custom research project without modifying code.
• Multiple research projects can unlock the same type of content.
• Translation keys should always be used instead of hardcoded messages.
• Research projects support prerequisite chains.
• Research projects support random research events.
• Research Notes permanently unlock recipe rewards.
• Research projects may be repeatable.