Skip to content

Latest commit

 

History

History
134 lines (106 loc) · 5.52 KB

howto.md

File metadata and controls

134 lines (106 loc) · 5.52 KB
Raw

How to use the JourneyMap API

To hook into JourneyMap from your mod, you'll write a plugin class that handles all interactions with JourneyMap via the API interfaces in this repository.

The JourneyMap API is designed so that your mod will only have a soft dependency on it:

  • You should only have a compile-time dependency via your plugin implementation.
  • You should not need a runtime dependency. As long as you don't declare a dependency on "journeymap" in your mods.toml file, your mod should load even if JourneyMap doesn't.
  • You should never include any JourneyMap API classes in your mod's jar. (No shading is needed.)

This page describes the recommended approach to writing a plugin for the JourneyMap API:

I. Add the API Dependency

To find out which API version to use, run Minecraft with JourneyMap. Open the Options manager or any other dialog in JourneyMap, and you'll see the API version in the corner of the screen. The mod info dialog also displays this information.

  1. Add Maven Central to your list of repositories
  2. Add a compile dependency on 'info.journeymap:journeymap-api:#version'
  3. Add journeymap mod in your run/mods folder or as a runtimeOnly/modRuntimeOnly dependency from cursemaven or modrinth's maven. If set as a runtime dependency, you will also need to add common-networking as a dependency.

For example:

#!gradle

// Version of JourneyMap API to use
`journeymap-api-forge:2.0.0-1.21.1-SNAPSHOT`
`journeymap-api-neoforge:2.0.0-1.21.1-SNAPSHOT`
`journeymap-api-fabric:2.0.0-1.21.1-SNAPSHOT`

// for multiloader setups, common jar
`journeymap-api-common:2.0.0-1.21.1-SNAPSHOT`

journeymap_api_version = 2.0.0-1.21.1-SNAPSHOT

// Note: None of the blocks below belong in your buildscript block. Put them below it instead.
repositories {
    // JourneyMap API releases are here
    maven {
        name = "JourneyMap (Public)"
        url = "https://jm.gserv.me/repository/maven-public/"
    }
    // Optional cursemaven
    maven {
        name = "Curse Maven"
        url "https://www.cursemaven.com"
    }
    // Optional Modrinth Maven
    maven {
        name = "Modrinth Maven"
        url = "https://api.modrinth.com/maven"
    }
}

configurations.all {
    // Check for snapshots more frequently than Gradle's default of 1 day. 0 = every build.
    resolutionStrategy.cacheChangingModulesFor 0, 'seconds'
}

// FORGE
dependencies {
    compileOnly group: 'info.journeymap', name: 'journeymap-api-forge', version: project.journeymap_api_version, changing: true
}

// NEOFORGE
dependencies {
    compileOnly group: 'info.journeymap', name: 'journeymap-api-neoforge', version: project.journeymap_api_version, changing: true
}

// FABRIC/QUILT
dependencies {
    modCompileOnlyApi group: 'info.journeymap', name: 'journeymap-api-fabric', version: project.journeymap_api_version, changing: true
}

Example forge: mods.toml entry for a soft dependency. Set mandatory=true for a hard dependency if needed.

[[dependencies.mymodId]]
modId = "journeymap"
mandatory = false
versionRange = "[1.21-6.0.0-beta.1,)"
ordering = "NONE"
side = "CLIENT"

Example neoforge: neoforge.mods.toml entry for a soft dependency. Set type = "required" for a hard dependency if needed.

[[dependencies.mymodId]]
modId = "journeymap"
type = "required"
versionRange = "[1.21-6.0.0-beta.1,)"
ordering = "NONE"
side = "CLIENT"

Note that the journeymap-api.jar is built with deobfuscated code so that it can be used at compile time and when stepping through a debugger in your development environment.

II. Look at the Example Code

  • Look in the example package for a complete example of a mod that has implemented a plugin for the JourneyMap API.

  • In intellij, you can set your run config module to journeymap-api.{modloadder}.testmod

  • to run the test mod. Be sure to add the JourneyMap jar to the {modloader}/run/client/mods folder.

III. Write your Plugin

  1. Write a class that implements the JourneyMap journeymap.client.api.v2.IClientPlugin interface (like 'ExampleJourneymapPlugin')
    • Annotate the class with @journeymap.api.v2.client.JourneyMapPlugin so that JourneyMap can find and instantiate it
    • Don't make references to this class elsewhere in your mod. You don't want it classloaded if JourneyMap isn't loaded.
  2. Write other classes as needed that use JourneyMap API classes, but only refer to them from your Plugin class.
    • Don't make references to these classes elsewhere in your mod. You don't want them classloaded if JourneyMap isn't loaded.
  3. For Forge/NeoForge: automatically detects the plugin.
  4. For Fabric: In your fabric.mod.json file add the path to your class that implements IClientPlugin to your entrypoint Example:
    "journeymap": [
      "mymod.modhooks.MyJourneymapPlugin"
    ]

IV. Test your Plugin

  1. Using the following gradle configuration above, your mod will load journeymap and the api in your development environment.
  2. Run Minecraft in your development environment. Forge will load JourneyMap and your mod, and the JourneyMap API will activate your plugin.