In-World Time for Games & Simulations

Define your world calendar once

A custom calendar is a small JSON document you POST to /v1/calendars. It's scoped to your API key, so each game or world can have its own calendar. Once registered, reference it on any /v1/spiral call with ?calendar=custom:<id>.

# Define your world's calendar once — scoped to your API key.
# 300-day year · 10 months · 6-day week · two eras · a leap cycle.

curl -s -X POST "https://api.temporalblock.com/api/v1/calendars" \
  -H "X-API-Key: tblk_live_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "eldoria",
    "yearDays": 300,
    "monthCount": 10,
    "monthNames": [
      "Frostwane","Seedfall","Greentide","Highsun","Embermonth",
      "Goldharvest","Mistreach","Duskfall","Longnight","Yearturn"
    ],
    "weekDays": 6,
    "weekNames": ["Sunday","Moonday","Forgeday","Tideday","Vineday","Restday"],
    "eraNames": ["Before Founding","After Founding"],
    "epochUtcMs": 0,
    "leapCycleDays": 1501
  }'

Every spiral call returns in-world labels

Pass calendar=custom:<id> and the response meta.calendar block comes back in your system — including display, year, era, monthName, dayOfMonth, dayOfYear, and weekdayName. The phase math is unchanged — only the label changes.

# Every /v1/spiral response can be labelled in your world calendar.
# The phase math doesn't change — only the human-readable label does.

curl -s "https://api.temporalblock.com/api/v1/spiral?calendar=custom:eldoria&atUtcMs=1750000000000" \
  -H "X-API-Key: tblk_live_yourkeyhere"

# meta.calendar in the response:
# {
#   "display": "Highsun 12, Year 56 After Founding",
#   "year": 56, "era": "After Founding",
#   "month": 4, "monthName": "Highsun",
#   "dayOfMonth": 12, "dayOfYear": 102,
#   "weekday": 3, "weekdayName": "Tideday"
# }

The label math is fully deterministic: the same game-clock millisecond always projects to the same year / era / month / day / weekday. Replays and lock-step multiplayer stay reproducible.

NPC AI time-aware dialogue

Feed the in-world calendar label directly to your NPC model's system prompt. The model reasons from the correct in-world date — no hallucinated years, no modern Gregorian references leaking into a fantasy setting.

// Drive an NPC's time-aware dialogue directly from the calendar response.

const { meta } = await fetch(
  `https://api.temporalblock.com/api/v1/spiral?calendar=custom:eldoria&atUtcMs=${gameClockMs}`,
  { headers: { "X-API-Key": process.env.TBLK_API_KEY } }
).then((r) => r.json());

const { display, monthName, weekdayName, era } = meta.calendar;
// display → "Highsun 12, Year 56 After Founding"

// Feed to your NPC model so it reasons in the correct in-world time.
const systemPrompt =
  `Today in Eldoria is ${display} (${weekdayName}).` +
  ` The current era is ${era}.` +
  " Respond in character, using the in-world date when asked.";

Related