Home

Welcome to the wiki for CICADA!

Setup

Adding CICADA to your project is as easy as adding the following to the corresponding blocks in your build.gradle:

repositories {
    maven { url = "https://maven.enjarai.nl/releases" }
}

dependencies {
    include modImplementation("nl.enjarai:cicada-lib:[VERSION]") {
        exclude group: "net.fabricmc.fabric-api"
    }
}

Make sure to set [VERSION] to the latest version on the maven. You'll probably want to use include to JiJ this lib, as it isn't available for download outside of github and maven.

Alternatively, you can choose not to JiJ, and rely on the entrypoint to stay independent. This is fully supported, but your conversations of course wouldn't play until another mod loads CICADA via JiJ in your stead.

CICADA is does (for the most part) not depend on a specific Minecraft version, but you might have trouble using it below 1.13.

Concepts

To properly use CICADA, you'll want to understand how it assembles conversations.

Every mod can define specific conversation ids it wants to take part in, these should usually be prefixed with the modid of the mod that says the opening line, e.g. "cicada:greetings". Mods will then define a list of lines they want to add to the conversation, every line having an order number and text.

When the game boots, CICADA will collect all the lines from available mods, and merge them into their appropriate conversations. The lines will then be sorted per conversation by the order number, ascending.

A conversation can also be given a priority by any mod. Usually the mod that says the opening line should define the priority, but this can be overwritten by other mods incrementing the override number. (This will probably make more sense once you look at JSON format)

The priority of a conversation is the weight of that conversation in the general pool. Once all conversations are loaded, CICADA will pick a random one based on these weights to play at startup.

Both conversations and lines can be given conditions, see the Conditions page for more info.

Basic usage

The two supported ways of adding to and creating conversations are to either create objects and register them using Java code, or via JSON. I'll be explaining the JSON format here as its the preferred and most versatile method. (see [JSON Format](JSON Format) for detailed documentation of available options)

Lets say we want to hook into the default "cicada:greetings" conversation, and greet the other mods. The basic layout for this would be as follows:

{
  "conversations": {
    "cicada:greetings": {
      "lines": [
        {
          "order": 50,
          "text": "Hi there!"
        }
      ]
    }
  }
}

If you've read the above paragraph about concepts used, this should make sense to you. Inside the "conversations" object, we create an entry for "cicada:greetings". We then define lines for it in a list format, which will be inserted into the conversation using their "order".

It is recommended that you put this file somewhere in your jar resources. This means it can be loaded from the web if your project is on github, but is also accessible on the classpath when no internet is available. Loading conversation definitions from the game assets is not really possible, since the conversations are played before asset loading is completed.

Once you've created this file, you'll want to register it with CICADA. This is done by implementing CicadaEntrypoint somewhere in your mod. The following example assumes that you put your conversations JSON at src/main/resources/cicada/example-mod/conversations.json, and your mod is on github under your/example-mod:

public class ExampleModCicadaCompat implements CicadaEntrypoint {
    public static final Logger LOGGER = ProperLogger.getLogger(MODID);

    @Override
    public void registerConversations(ConversationManager conversationManager) {
        conversationManager.registerSource(
                JsonSource.fromUrl("https://raw.githubusercontent.com/your/example-mod/master/fabric/src/main/resources/cicada/example-mod/conversations.json")
                        .or(JsonSource.fromResource("cicada/example-mod/conversations.json")),
                LOGGER::info
        );
    }
}

As you can see, we first get a logger using ProperLogger, which is a wrapper provided by CICADA around a normal slf4j Logger. This is due to normal Loggers not showing your modid in a production environment, ProperLogger works around this by simply prefixing your message.

After that, we can implement registerConversations to receive a ConversationManager to register our conversation JSON with. The registerSource method here requires a JsonSource and Consumer<String>. The first can be obtained using some default static methods, or can be manually implemented. (See the included javadocs for more details) And for the second you can use a reference to your Logger's info method.

Once you've done this, the only thing left to do is adding your CicadaEntrypoint to your fabric.mod.json as follows:

{
  "entrypoints": {
    "cicada": [
      "com.example.examplemod.ExampleModCicadaCompat"
    ]
  }
}

Thats all! When you boot up the game, and this particular conversation is chosen to be played, your entry will show up as well.