Skip to content

EXTERNAL_MOD_API.md

Latest commit

 

History

History
70 lines (56 loc) · 2.82 KB

EXTERNAL_MOD_API.md

File metadata and controls

70 lines (56 loc) · 2.82 KB
Raw

Waypointer API for external client mods

This is a concise integration reference that can be copied in full into a new Codex task.

Integration rules

Do not access org.waypoints.next.*, private fields, or internal SurroundingKind values/controllers. The only public entry point is:

org.waypoints.api.WaypointerApi

The integration must always be optional and fail open:

  1. Locate WaypointerApi with Class.forName.
  2. Invoke the static isInstalled() method and continue only when it returns true.
  3. If needed, check apiVersion() (the current version is 2) and capabilities() (OBJECT_MARKS, SUBJECT_LIFECYCLE, NAVIGATION).
  4. If the API is unavailable, returns false, or an invocation fails, the external mod must continue working without Waypointer features.

Simple reflection calls

Create or update a 15-minute marker for a loaded object:

Class<?> api = Class.forName("org.waypoints.api.WaypointerApi");
boolean installed = Boolean.TRUE.equals(
        api.getMethod("isInstalled").invoke(null));
if (installed) {
    boolean marked = Boolean.TRUE.equals(api.getMethod("markObject",
            String.class, String.class, String.class, long.class,
            String.class, boolean.class).invoke(null,
            "my.mod.id",          // Stable ID of the owning mod
            "selected:" + wurmId, // Idempotency key for the marker
            "AUTO",               // AUTO | CREATURE | ITEM | CONTAINER
            wurmId,
            "ALERT",              // ALERT | TARGET | BEAM | COMPASS_ONLY
            true));                // Also start or move NAV when true
}

Report that the source object disappeared (a creature's death counts as its disappearance; the corpse is a new item and does not inherit the marker):

api.getMethod("subjectVanished", String.class, long.class)
        .invoke(null, "CREATURE", killedCreatureId);

The typed API also provides ObjectMarkRequest, MarkResult, WurmObjectRef, WurmObjectSnapshot, removeOwnedMarker(...), and setNavigation(...). For a fence, hedge, or another object outside the live catalog, provide a WurmObjectSnapshot through ObjectMarkRequest.Builder.snapshot(...). If the object is currently selected in the standard HUD, Waypointer will also try to obtain its coordinates automatically. Waypointer removes the marker when the object disappears; when the active marker is removed, NAV stops automatically.

Prompt for another task

Integrate this client mod with Waypointer only through the public org.waypoints.api.WaypointerApi, following the rules in this file. Perform the optional isInstalled() handshake first, do not introduce a hard runtime dependency, use unique ownerId and markerKey values, and report object removal or replacement through subjectVanished. The integration must fail open.