Entries

Entries are defined in json files placed in the /data/<mod_id>/modonomicon/books/<book_id>/entries/<category_id>/ folder.

Attributes

type (Identifier, mandatory)

The entry type.

Builtin entry types are:

• modonomicon:content for normal entries with pages
• modonomicon:category_link for entries that open another category via category_to_open
• modonomicon:entry_link for entries that open another entry via entry_to_open

id (Identifier, mandatory)

The unique id of this entry within the book.

This is the id used by links and parent references. For entries stored in entries/<category_id>/, this is typically the full path including the category folder, for example yourmod:features/my_entry.

category (Identifier, mandatory)

The Identifier of the category this entry should be placed in.

tip

The file hierarchy of the entry's json file does not actually assign the entry to the category, only this field does!

name (DescriptionId, mandatory)

The entry name, will be shown in bold when hovering over the Entry. Will not parse markdown.

description (DescriptionId, optional)

The entry description, will be shown below the name when hovering over the Entry. Will not parse markdown.

icon (Identifier, mandatory)

Either an item/block Identifier that should be used as icon. E.g.: minecraft:nether_star or minecraft:chest.
Or the Identifier to a texture. The texture must be 16x16 pixels. E.g.: modonomicon:textures/gui/some_random_icon.png.

tip

To use a texture make sure the Identifier includes the file ending .png as seen in the example above.

x (Integer, mandatory)

The x coordinate (horizontal) of the entry in the category.

y (Integer, mandatory)

The y coordinate (vertical) of the entry in the category.

sort_number (Integer, optional)

Defaults to -1.

If the category of this entry is in "index" mode, then the sort number will be used to order the entries (instead of using x/y to place the entry on the 2d node grid).
When using datagen and no sort number is provided, the CategorProvider will automatically assign a sort number based on the order the entries are added when using .add().

hide_while_locked (Boolean, optional)

Default value: false. If true, this entry will not be shown as greyed out while it is locked, instead it will be entirely hidden.

tip

Usually the default value is what you want. Regardless of this setting, locked entries will be hidden fully until the entry just before them (= the immediate parent) becomes unlocked, and only then show greyed out. true will cause the entry to stay hidden even then.

show_when_any_parent_unlocked (Boolean, optional)

Default value: false.
If true, the entry will show (locked) as soon as any one parent is unlocked. If false, the entry will only show (locked) as soon as all parents are unlocked.

tip

If you want this true or false depends on how "discoverable" you want your book to be. If true the entry will be visible to the player earlier, and the tooltip will indicate that they will need another entry to unlock it.
If false the entry will only show once all parents of it are unlocked, effectively making the player aware much later.

background (Sprite JSON Object, optional)

Defines the sprite used as the entry background.

Default value:

{
  "sprite": "modonomicon:modonomicon/themes/default/node/entry_backgrounds/square_gold",
  "width": 26,
  "height": 26
}

Attributes

• sprite (Identifier, mandatory): The sprite to use for the entry background.
• width (Integer, optional): The background width. If omitted, defaults to -1.
• height (Integer, optional): The background height. If omitted, defaults to -1.

As a shorthand, background can also be a single Identifier string instead of an object. In that case it is treated as the sprite value and width / height default to -1.

Default datagen entry backgrounds

When generating entries in code, BookEntryModel#withEntryBackground(...) accepts any GuiSprite, but the default theme also exposes convenience constants in EntryBackground for the built-in node entry backgrounds:

• EntryBackground.SQUARE_GOLD
• EntryBackground.SQUARE_GRAY
• EntryBackground.SQUARE_PURPLE
• EntryBackground.STAR_GOLD
• EntryBackground.STAR_GRAY
• EntryBackground.STAR_PURPLE
• EntryBackground.CIRCLE_GOLD
• EntryBackground.CIRCLE_GRAY
• EntryBackground.CIRCLE_PURPLE
• EntryBackground.HEXAGON_GOLD
• EntryBackground.HEXAGON_GRAY
• EntryBackground.HEXAGON_PURPLE

Example:

BookEntryModel.create(id("my_entry"), "example.book.my_entry")
    .withCategory(category)
    .withIcon(Items.BOOK)
    .withLocation(0, 0)
    .withEntryBackground(EntryBackground.HEXAGON_PURPLE);

EntryBackground.DEFAULT still points to EntryBackground.SQUARE_GOLD.

marker (Sprite JSON Object, optional)

Overrides the marker indicator sprite shown on this entry while its marker_condition is unfulfilled. If omitted, the theme default is used (see marker_indicator in Theme).

Uses the same sprite structure as background above: a sprite Identifier plus optional width / height, or a single Identifier string as shorthand.

Datagen: BookEntryModel#withMarker(...).

name_style (JSON Object, optional)

Controls the permanently rendered entry name on node-based category screens, styled like the vanilla advancement title box: a nine-sliced bar tucked behind (or, for left/right, passing through) the entry badge. If omitted, the name only shows in the hover tooltip.

Attributes

• render_name (String, optional): Default value: "none". Where to render the name: left, right, top, bottom, or none (tooltip only).
• show_name_before_unlock (Boolean, optional): Default value: false. If true, a locked entry's name renders under the same grey overlay as the badge. Otherwise names only show once unlocked.
• name_background_color (Integer, optional): Default value: -1 (white = theme default tint). ARGB tint of the name background, multiplied with the theme default tint. Hex strings like "#ffff5555" are also accepted.
• name_background (Sprite JSON Object, optional): Background sprite override. If omitted, the theme default is used. Uses the same sprite structure as background above.
• name_text_color (Integer, optional): Default value: -1 (white = theme default text color). ARGB color of the name text, multiplied with the theme default text color.

Example:

"name_style": {
  "render_name": "right",
  "name_background_color": "#ffff5555"
}

Datagen: BookEntryModel#withRenderName(...), #withShowNameBeforeUnlock(...), #withNameBackgroundColor(...), #withNameBackground(...), #withNameTextColor(...).

condition (Condition, optional)

Entries, like Categories, can be hidden until an Unlock Condition is fulfilled. Conditions are JSON objects.
See Unlock Conditions for details.

marker_condition (Condition, optional)

If set, a small attention dot (marker) is shown on this entry on the node map and in all entry lists (category index, search, bookmarks, recently unlocked) while the entry is unlocked and the marker condition is not yet fulfilled. Once the condition is met the marker disappears without needing to reopen the book.

• The marker only shows on unlocked entries; never on locked or hidden entries.
• Markers never show tooltips.
• Any unlock condition type can be used (see Research Conditions); typically a research-backed condition such as research_node_unlocked or research_stage_completed.
• The marker sprite can be customized per entry with marker (see above); otherwise the theme default is used.

{
  "marker_condition": {
      "type": "modonomicon:research_node_unlocked",
      "node_id": "mymod:features/my_milestone"
  }
}

Datagen: BookEntryModel#withMarkerCondition(...), #withMarker(nodeRef), #withMarker(nodeRef, stageRef), plus the auto-generated shorthands #markerUntilEntryViewed(...), #markerUntilCrafted(...) and #markerUntilAcquired(...) (see Research Datagen).

parents (Parent[], optional)

Entry Parents are JSON Objects that define Entries this Entry should be connected to. See Parents for details. A parent connection does not imply an unlock condition or any logical dependency, by default it is just a visual connection. When using datagen, BookModel.withGenerateEntryHierarchyResearch(true) automatically generates research nodes and hooks for parent→child entry progression.

pages (Page[], optional)

Pages are JSON Objects that define the actual book content. This is used by modonomicon:content entries. See Page Types for the available types of pages.

Pages as Files

By default, pages are generated as separate JSON files instead of being inline in the entry JSON. This makes it easier to manage large entries with many pages.

File structure:

The entry JSON lives alongside a pages/ subdirectory that shares the entry's name:

data/<mod_id>/modonomicon/books/<book_id>/entries/
  <category_id>/
    <entry_name>.json          ← entry definition (no inline pages)
    <entry_name>/
      pages/
        <page_id>.json         ← individual page files

For example, the entry data/modonomicon/modonomicon/books/demo/entries/features/custom_icon.json has its pages in data/modonomicon/modonomicon/books/demo/entries/features/custom_icon/pages/.

Each page file contains a single page JSON object:

{
  "id": "intro",
  "type": "modonomicon:text",
  "title": "book.modonomicon.demo.features.custom_icon.intro.title",
  "text": "book.modonomicon.demo.features.custom_icon.intro.text"
}

The id attribute is mandatory. It uniquely identifies the page within the entry and is used for page-file loading, page replacement/merging, and entry links that target a specific page. There is no separate page anchor property anymore; the @... part of an entry link resolves against the page id.

The type attribute determines how the page renders (e.g., modonomicon:text, modonomicon:spotlight).

Page files can also include an optional sort_number integer. If present, pages without a matching inline page id are inserted at that position during merge; otherwise they are appended.

Datagen: Pages-as-files is the default behavior. Use BookEntryModel#withGeneratePagesAsFiles(false) to generate pages inline in the entry JSON instead.

category_to_open (Identifier, optional)

The resource location to the category that should be opened when this entry is clicked. If this is set, the entry will never show it's pages, but instead open the category directly.

Use this on entries with "type": "modonomicon:category_link".

tip

This allows to create "sub-category" that does not show up in the category navigation menu, if combined with "show_category_button" : false setting for the target category. See also Categories.

command_to_run_on_first_read (Identifier, optional)

The resource location to the command that should be opened when this entry is read/opened for the first time. See Commands on how to create the command.

tip

This can be used to e.g. give rewards to players for reaching a certain part of the book.

entry_to_open (Identifier, optional)

The resource location to the entry that should be opened when this entry is clicked. This allows to place one entry in multiple categories by referring to it multiple times. If this is set, the entry will never show it's pages, but instead open the target entry.

Use this on entries with "type": "modonomicon:entry_link".

associated_items ((ItemStackTemplate | Ingredient)[], optional)

Links this entry to one or more items. When the player hovers such an item (in inventories, creative menus or recipe viewers such as JEI/EMI), the tooltip shows the entry's icon with a small book badge, the entry name in white and a hold-to-open hint. Holding the open key (default: Left Alt, rebindable under Controls → Modonomicon → Open Associated Book Page) while hovering opens the book directly at this entry.

Each entry is either an item stack template with an id and optional components, or an ingredient (like spotlight pages support), e.g.:

"associated_items": [
  { "id": "minecraft:beacon" },
  {
    "id": "minecraft:leather_helmet",
    "components": {
      "minecraft:dyed_color": 1481884
    }
  },
  "minecraft:diamond",
  ["minecraft:diamond", "minecraft:emerald"],
  "#minecraft:logs"
]

Matching: an item stack template matches when the hovered stack is the same item and every component defined in the template is present on the stack with an equal value. Additional components on the hovered stack are allowed (subset matching); count is ignored. An ingredient matches any stack it contains (single items, item lists and #tags).

Page-level associated_items (see Page Types) take precedence over entry-level ones: hovering an item linked to a specific page opens that page instead of the entry start.

If the entry is still locked for the player, the tooltip shows a locked hint instead and holding the key does nothing.

The small book badge shown next to the icon defaults to the book's own item stack and can be overridden per book with associated_item_badge in book.json.

Datagen: BookEntryModel#withAssociatedItem(...) / #withAssociatedItems(...) (there are overloads for Item, ItemStackTemplate and Ingredient).

The hold duration is a client-side setting (associatedItemsHoldDurationMs, default 750 ms).

Parents

Entry Parents define which entry comes visually before this entry in the book, as in, which entry points an arrow at this entry.

Attributes

entry (Identifier, mandatory)

The Identifier of the parent entry. This is the main attribute.

draw_arrow (Boolean, optional)

Default value: true. If false, the line connecting parent and this entry will not have an arrow at the end.

line_enabled (Boolean, optional)

Default value: true. If false, there will be no connecting line. This is useful if you want to use the parent connection to define an automatic unlock condition via datagen, but don't want to show the line.

line_reversed (Boolean, optional)

Default value: false.
If true, the line will be drawn in reverse, which means the curve is mirrored. This allows you to determine if the curve goes left or right / up or down to get nice symmetrical graphs. This has no effect on straight lines.
This does not affect the direction of the arrow.

Usage Examples

{
  "type": "modonomicon:content",
  "id": "modonomicon:test_category/multiblock",
  "name": "multiblock",
  "description": "modonomicon.test.entries.test_category.multiblock.description",
  "icon": "minecraft:chest",
  "x": 6,
  "y": 2,
  "category": "modonomicon:test_category",
  "pages": [
    {
      "type": "modonomicon:text",
      ...
    },
    {
      "type": "modonomicon:multiblock",
      ...
    }
  ],
  "parents": [
    {
      "entry": "modonomicon:test_category/test_entry"
    }
  ]
}