Research Conditions

Entries and categories can be gated behind research nodes using condition types. These conditions check the player's research state.

Research Node Unlocked

Condition type: modonomicon:research_node_unlocked

This condition is met when the specified research node is fully completed (all stages finished) for the player.

Attributes

node_id (Identifier, mandatory)

The Identifier of the research node that must be fully completed.

tooltip (DescriptionId or Component JSON, optional)

The tooltip to display when hovering over the locked entry. If omitted, a tooltip is auto-generated from the node's description ID.

Example

{
  "condition": {
      "type": "modonomicon:research_node_unlocked",
      "node_id": "mymod:features/condition_root"
  }
}

Research Stage Completed

Condition type: modonomicon:research_stage_completed

This condition is met when a specific stage within a research node is completed for the player. Use this to gate entries behind partial progress in multi-stage nodes.

Attributes

node_id (Identifier, mandatory)

The Identifier of the research node containing the stage.

stage_id (Identifier, mandatory)

The Identifier of the stage that must be completed.

tooltip (DescriptionId or Component JSON, optional)

The tooltip to display when hovering over the locked entry. If omitted, a tooltip is auto-generated from the stage's description ID.

Example

{
  "condition": {
      "type": "modonomicon:research_stage_completed",
      "node_id": "mymod:features/my_node",
      "stage_id": "mymod:features/my_node/stage_1"
  }
}

Entry markers

Entries can show a small attention dot until a condition completes via marker_condition. The marker reuses all unlock condition types documented above; it is typically research-backed (research_node_unlocked or research_stage_completed). Markers never show tooltips and only render on unlocked entries.

Explicit recipe: author a hook + fact + node in your ResearchSubProvider, then point the marker at the node:

// In your ResearchSubProvider:
public static final ResearchNodeRef MARKER_DONE = node("mymod/marker_done");

@Override
protected void generateResearch() {
    var fact = this.ingress()
        .onEntryViewedOnce(this.modLoc("mymod_category/mymod_entry"))
        .declareFact("mymod/marker_done_fact");

    this.node(MARKER_DONE, fact);
}

// In your BookProvider:
entry.withMarker(MyResearch.MARKER_DONE);

There is no auto-generated advancement shorthand: advancement-backed markers use the same manual pattern (hook + fact + node, see Advancement gating). Demo: MARKER_EXPLICIT in DemoResearch.java with MarkerExplicitEntry.java for the book side.

For the common cases, auto-generated shorthands are available instead of manual research (see Research Datagen): markerUntilEntryViewed, markerUntilCrafted, markerUntilAcquired.

Datagen shortcuts

When using datagen, BookEntryModel, BookCategoryModel, and BookPageModel provide shorthand methods:

// Gate behind a completed node
entry.withCondition(researchNodeRef);

// Gate behind a specific stage
entry.withCondition(researchNodeRef, researchStageRef);

// Gate a category
category.withCondition(researchNodeRef);

Parent-to-child progression

When using datagen, BookModel.withGenerateEntryHierarchyResearch(true) automatically generates entry_viewed_once hooks and research nodes for entries that have parents. This produces the correct BookResearchNodeUnlockedCondition on each entry without manual condition work.

If you need fine-grained control, create research nodes and hooks manually in your ResearchSubProvider.