Skip to content
3 Death Saves

Developer API

Bondsmith exposes a public API on the uppercase global BONDSMITH. Access it from a macro or the console through BONDSMITH.api.

const api = BONDSMITH.api;
const rep = api.reputation.get('Actor.abc123', 'actor');

The lowercase bondsmith is not a global and returns undefined. The same object is also mounted at game.modules.get('bondsmith').api.

Every method that writes data returns a Promise. Await writes before reading the value back.

API

Section titled “API”

data

Section titled “data”
  • data.getData() returns the full Bondsmith data object.
  • data.getSettings() returns the resolved settings object.
  • data.getLimits() returns the configured reputation minimum and maximum.
  • data.getTierForValue(value) returns the tier that a numeric value falls into.
  • data.export() saves the full export payload to a JSON file.
  • data.import() prompts for an export file and opens the import dialog.

actors

Section titled “actors”
  • actors.getTracked() returns the array of tracked actor UUIDs.
  • actors.addTracked(uuid) adds an actor to tracking.
  • actors.removeTracked(uuid) removes an actor from tracking.
  • actors.getDisplayName(uuid) returns the stored display name.
  • actors.setDisplayName(uuid, name) sets the display name.
  • actors.getAltTitle(uuid) returns the alternate title.
  • actors.setAltTitle(uuid, title) sets the alternate title.
  • actors.getVisibleName(uuid) returns the name shown for the current user.
  • actors.getPCs() returns the tracked player characters.
  • actors.isPC(uuid) returns whether an actor is a player character.
  • actors.getImage(uuid) returns the actor image path.
  • actors.getJournal(uuid) returns the linked journal record.
  • actors.setJournal(uuid, journal) links a journal record to an actor.

factions

Section titled “factions”
  • factions.list() returns all factions.
  • factions.get(id) returns one faction by id.
  • factions.add(data) creates a faction.
  • factions.update(id, changes) updates a faction.
  • factions.remove(id) deletes a faction.
  • factions.duplicate(id, options) duplicates a faction.
  • factions.addMember(id, actorUuid) adds a member.
  • factions.removeMember(id, actorUuid) removes a member.
  • factions.addRank(id, rank) adds a rank.
  • factions.removeRank(id, rankId) removes a rank.
  • factions.setMemberRank(id, actorUuid, rankId) assigns a member to a rank.
  • factions.setJournal(id, journal) links a journal record.
  • factions.setRollTable(id, table) links a roll table document.
  • factions.generateTierTable(id) generates a tier roll table for the faction.

locations

Section titled “locations”
  • locations.list() returns all locations.
  • locations.get(id) returns one location by id.
  • locations.add(data) creates a location.
  • locations.update(id, changes) updates a location.
  • locations.remove(id) deletes a location.
  • locations.duplicate(id, options) duplicates a location.
  • locations.addFaction(locationId, factionId) adds a faction to a location.
  • locations.addActor(locationId, actorUuid) adds an actor to a location.
  • locations.setJournal(id, journal) links a journal record.

relations

Section titled “relations”
  • relations.getIndividual(fromId, toId) returns an actor-to-actor relation value.
  • relations.setIndividual(fromId, toId, value) sets an actor-to-actor relation.
  • relations.getFactionToActor(factionId, actorId) returns a faction-to-actor value.
  • relations.setFactionToActor(factionId, actorId, value) sets a faction-to-actor value.
  • relations.getActorToFaction(actorId, factionId) returns an actor-to-faction value.
  • relations.setActorToFaction(actorId, factionId, value) sets an actor-to-faction value.
  • relations.getFactionToFaction(fromId, toId) returns a faction-to-faction value.
  • relations.setFactionToFaction(fromId, toId, value) sets a faction-to-faction value.
  • relations.setFactionToFactionBidirectional(aId, bId, value) sets both directions of a faction pair.
  • relations.getFactionToLocation(factionId, locationId) returns a faction-to-location value.
  • relations.setFactionToLocation(factionId, locationId, value) sets a faction-to-location value.
  • relations.getActorToLocation(actorId, locationId) returns an actor-to-location value.
  • relations.setActorToLocation(actorId, locationId, value) sets an actor-to-location value.
  • relations.getControllersOfLocation(locationId) returns the factions and actors that control a location.
  • relations.isMirrored(fromId, toId) returns whether a faction pair is mirrored.
  • relations.setMirrored(fromId, toId, mirrored) sets the mirrored state of a faction pair.
  • relations.remove(type, fromId, toId) removes a relation.

reputation

Section titled “reputation”
  • reputation.get(id, type, opts) returns a reputation value for an actor or faction. Pass opts.memberId to read a single PC’s relation instead of the aggregate.
  • reputation.set(id, type, value, opts) sets a reputation value. Pass opts.memberId to write a single PC’s relation instead of the aggregate.
  • reputation.getMode(id, type) returns the reputation mode for an entity.
  • reputation.setMode(id, type, mode) sets the reputation mode.
  • reputation.getEffectiveLimits(id, type) returns the effective minimum and maximum for an entity.
  • reputation.getEffectiveTiers(factionId) returns a faction’s roll-table tier list or null.
  • reputation.calcMemberAverageActor(actorUuid) returns the average of each party PC’s individual relation toward that actor.
  • reputation.calcMemberAverageFaction(factionId) returns the average member reputation of a faction.
  • reputation.calcPartyAverageFaction(factionId) returns the active party’s average reputation toward a faction.
await BONDSMITH.api.reputation.set('Actor.abc123', 'actor', 25);

party

Section titled “party”
  • party.getActiveId() returns the active party id.
  • party.setActive(id) sets the active party.
  • party.followSystemPrimary() syncs the active party to the system primary party when the follow setting is enabled.

visibility

Section titled “visibility”
  • visibility.isHidden(type, id) returns whether an entity is hidden from players.
  • visibility.toggleHidden(type, id) toggles entity visibility.
  • visibility.isRelationHidden(type, fromId, toId, userId) returns whether a relation is hidden.
  • visibility.toggleRelationHidden(type, fromId, toId) toggles relation visibility for the default audience.
  • visibility.getRelationVisibility(type, fromId, toId, userId) returns the relation visibility state.
  • visibility.setRelationVisibility(type, fromId, toId, target, state) sets the relation visibility state. Pass '_default' as target for the default audience or a user id for a per-user override.

presets

Section titled “presets”
  • presets.list() returns the available setting presets.
  • presets.get(id) returns one preset.
  • presets.resolve(entity, parent) resolves an entity’s preset chain to a settings object.

changelog

Section titled “changelog”
  • changelog.get(factionId) returns a faction’s changelog.
  • changelog.add(factionId, entry) adds an entry to a faction’s changelog.
  • changelog.getActor(actorUuid) returns an actor’s changelog.
  • changelog.addComment(type, id, entryId, comment) adds a comment to an entry.
  • changelog.setEntryTimestamp(type, id, entryId, timestamp) sets an entry’s timestamp.

graphs

Section titled “graphs”
  • graphs.getIndex() returns the graph index.
  • graphs.getEntry(id) returns one graph index entry.
  • graphs.create({ name, type, description }) creates a graph and returns its index entry.
  • graphs.delete(id) deletes a graph.
  • graphs.load(id) loads a graph document.
  • graphs.save(id, graph) saves a graph document. Only the GM can save.
  • graphs.builder(type) returns a GraphBuilder for the given type.
  • graphs.canUserView(graph, userId) returns whether a user can view a loaded graph.
  • graphs.canUserEdit(graph, userId) returns whether a user can edit a loaded graph.
  • graphs.setPermissions(graph, userId, perms) sets a user’s permissions on a loaded graph.
  • graphs.updateNode(graph, nodeId, changes) updates a node on a loaded graph.
  • graphs.updateLink(graph, linkId, changes) updates a link on a loaded graph.
  • graphs.addShape(graph, shape) adds a shape to a loaded graph.
  • graphs.updateShape(graph, shapeId, changes) updates a shape on a loaded graph.
  • graphs.removeShape(graph, shapeId) removes a shape from a loaded graph.

Graph mutators change the loaded graph object in memory. Persist the result with graphs.save(id, graph).

canvas

Section titled “canvas”
  • canvas.refreshBadges() redraws all token reputation badges.
  • canvas.refreshConnections() redraws all scene connection lines.

undo

Section titled “undo”
  • undo.undo() reverts the last tracked change.
  • undo.clear() clears the undo stack.
  • undo.size() returns the number of stored snapshots.

viewer

Section titled “viewer”
  • viewer.setPerspective(type, id) sets the open viewer’s perspective and returns whether it applied.
  • viewer.getPerspective() returns the open viewer’s current perspective or null.

ui

Section titled “ui”
  • ui.open() opens the main viewer.
  • ui.openSettings() opens the settings window.
  • ui.openCreator(entityType, parentId) opens the entity creator.
  • ui.openPicker(pickType, callback, options) opens the entity picker.
  • ui.openGraphs() opens the graph dashboard.

top-level helpers

Section titled “top-level helpers”
  • search(query) returns matching actors, factions, and locations grouped by type.
  • duplicate(type, sourceId, options) duplicates a faction or location.
  • enterLocation(actorId, locationId, repDelta) adds an actor to a location and optionally shifts reputation toward the controlling faction.
  • batchSetRep(changes) sets reputation for a list of { id, type, value } entries.
  • adjustRep(id, type, delta) applies a relative reputation change through a serialized queue.
await BONDSMITH.api.adjustRep('Actor.abc123', 'actor', -5);

constants and models

Section titled “constants and models”
  • constants holds MODULE_ID, HOOKS, REP_MODES, RELATION_TYPES, and GRAPH_TYPES.
  • models.GraphBuilder is the graph builder class.

Hooks

Section titled “Hooks”

Bondsmith fires hooks through Hooks.callAll. Listen with Hooks.on('bondsmith.repChanged', callback). Hook automation rules can also subscribe to bondsmith.repChanged. See Automation and Triggers.

HookFires whenPayload
bondsmith.readyThe API is mounted during Foundry’s ready phase.none
bondsmith.repChangedA reputation value changes.{ id, type, oldValue, value, memberId }
bondsmith.relationChangedA relation value changes.{ type, fromId, toId, oldValue, newValue }
bondsmith.settingsChangedSettings are saved.{ settings }
bondsmith.factionDuplicatedA top-level faction is duplicated.{ sourceId, newId, options }
bondsmith.locationDuplicatedA top-level location is duplicated.{ sourceId, newId, options }
bondsmith.journalLinkedA journal is linked to an actor, faction, or location.{ type, id, journal, previous }
bondsmith.journalUnlinkedA journal link is removed.{ type, id, previous }
bondsmith.dataResetModule data is reset.{ scope }
bondsmith.ruleFiredAn automation rule applies a change.{ ruleId, hookName, target, delta, payload, isTestFire }

On bondsmith.repChanged, memberId is the UUID of the party PC whose relation changed. Setting an aggregate value fires a per-member event for each affected relation, then a final roll-up event carrying only { id, type, value } (no memberId or oldValue).

Hooks.on('bondsmith.repChanged', ({ id, type, value }) => {
  console.log(`${type} ${id} is now at ${value}`);
});

Constants

Section titled “Constants”

BONDSMITH.api.constants exposes the module constants.

  • MODULE_ID is 'bondsmith'.
  • HOOKS maps each hook key to its bondsmith.* event name.
  • RELATION_TYPES holds the relation type values: individual, faction, actorFaction, factionToFaction, factionToLocation, and actorToLocation.
  • GRAPH_TYPES holds the graph type values: force, genealogy, map, and timeline.
  • REP_MODES holds the reputation mode values.