Developer API

Timeline exposes public API helpers under org.z2six.rpgtimeline.api.RPGTimelineApi.

TLDR

Use the API to:

read/format current calendar dates
add server/personal notes
record native advancements
record external advancement-like events

Date Helpers

import org.z2six.rpgtimeline.api.RPGTimelineApi;

long gameTime = serverLevel.getDayTime();
String dateText = RPGTimelineApi.buildDateStringFromGameTime(gameTime);
long dayIndex = RPGTimelineApi.getDayIndexForGameTime(gameTime);

Useful methods:

getCalendarDefinition()
getCalendarDayOffsetDays()
fromGameTime(long gameTime)
formatDate(long gameTime)
buildDateMessage(long dayIndex)

Add Notes Programmatically

import org.z2six.rpgtimeline.api.RPGTimelineApi;

RPGTimelineApi.addServerNote(player, "Server Arc Begins", "The kingdom enters a new age.");
RPGTimelineApi.addPersonalNote(player, "My Journal", "Reached the obsidian gate.");

// Explicit day index version
RPGTimelineApi.addServerNote(player, "Coronation", "The crown was claimed.", 512L);

Record Advancements

Native advancement object

RPGTimelineApi.recordAdvancement(player, advancementHolder);

External advancement-like event

import net.minecraft.network.chat.Component;

RPGTimelineApi.recordExternalAdvancement(
    player,
    "mymod:slay_lich",
    Component.literal("Lich Vanquisher"),
    Component.literal("Defeated the Lich beneath the catacombs."),
    "minecraft:nether_star"
);

DEEP DIVE: world-first identity

sourceId is the identity used for world-first tracking. Keep it stable and unique per achievement concept.

Error Model

API calls are defensive:

null inputs are ignored safely where possible
internal failures are logged and swallowed to avoid crashing caller mods

Server-side usage

Chronicle-writing helpers should be called from server-side contexts (ServerPlayer).