YapYap API

YapYap API is a library mod that lets you give any entity a full conversation. You build a branching dialog tree, attach it to an NPC, and the player talks to that NPC in a custom in-game screen with a portrait, typewriter text, and clickable response options.

It is meant to be used by other mods and by datapacks. On its own it adds an admin command and a couple of example conversations, nothing else.

Requires: NeoForge 21.1.190 or newer, Minecraft 1.21.1, Java 21. Side: needs to be installed on both the client and the server. License: MIT.

What it does

• Branching dialog trees. Each tree is a set of named nodes. A node has one or more pages of text and a list of responses. Responses can be hidden or shown based on conditions, and can run actions when chosen.
• Two ways to write dialogs, one runtime. Pack makers write JSON files in a datapack. Mod developers use a fluent Java builder or register JSON at runtime. Both produce the same thing.
• Server authoritative. The client only sends "I picked option number 3". The server re-checks every condition on every step, so a modded client cannot skip a locked option.
• Datapack friendly. Dialog files live in a datapack and reload with the /reload command. Actions can run vanilla commands and functions, so a pure datapack can drive quests without any Java.
• Extensible. The list of condition and action keywords is open. A mod can register its own and datapacks can then use them by name.
• Custom conversation screen. Non-pausing, drawn over the world. It works with zero textures out of the box. If you want to skin it, every texture is optional and swapped in per file.
• Portrait options. Show a painted image, the live 3D model of the NPC, a model of any entity type, or a simple drawn placeholder. It falls back automatically in that order.
• NPC behaviour. While talking, the NPC stops moving and turns to face the player. Taking or dealing damage ends the conversation. Walking too far away ends it.
• Saved progress. Each player has named flags and a record of which nodes they have visited. This is stored on the player and survives death.
• Events. Mods can listen for conversation start, node change, response chosen, and conversation end. Start and choice events can be cancelled.

Built-in content

Conditions: check a flag, whether a node was visited before, an advancement, a scoreboard score, permission level, held items, a random chance, sneaking state, the current dimension, and the logic combiners all of, any of, and not.

Actions: run a command, run a function, set or add a flag, give or take items, grant an advancement, play a sound, send a chat or action bar message, open another dialog, open the NPC trade screen, jump to another node, and end the conversation.

Text placeholders such as the player name, the NPC name, and the villager profession are filled in when the line is shown.

For pack makers

Put dialog files at data/<namespace>/yapyap/dialogs/<name>.json. Bind a dialog to a mob with the in-game command, then right-click the mob. Dialogs reload with /reload. A full working example is included in the mod jar.

For mod developers

Add the mod as a dependency and use the YapYapAPI class. You can register dialogs, register your own condition and action types, open and close conversations, bind dialogs to entities, and read or write player flags. A DialogBuilder gives you a readable way to define trees in code.

Commands

All /yapyap subcommands need permission level 2.

• talk starts a conversation for one or more players.
• assign and unassign bind or unbind a dialog on an entity.
• stop force-closes conversations.
• reset clears a player's visited history.
• flag reads or edits player flags.
• list shows every loaded dialog id.
• demo gives you a villager spawn egg for a quick test. The placed villager gets a random profession and an example dialog with a trade option and a small quest.
• villager_on turns on a generic greeting for all un-bound adult villagers.

The last one is off by default and is also editable in the config file.

Configuration

The config file config/yapyap-common.toml controls right-click behaviour, the auto-close distance, whether command actions are allowed, and the auto-dialog toggles. The file config/yapyap-client.toml controls typewriter speed and background dimming. Both files are plain text and safe to edit by hand.

Documentation

Full documentation is available as a wiki. It covers the complete JSON format, every condition and action with its fields, the Java API, the event list, all commands, all config keys, and the texture spec.

Open the YapYap Wiki