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

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() returns the full export payload.
• data.import(payload) applies an import payload.

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 UUID.
• actors.setJournal(uuid, journalUuid) links a journal to an actor.

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, journalUuid) links a journal.
• factions.setRollTable(id, tableUuid) links a roll table.
• factions.generateTierTable(id) generates a tier roll table for the faction.

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, journalUuid) links a journal.

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 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

• reputation.get(id, type) returns a reputation value for an actor or faction.
• reputation.set(id, type, value) sets a reputation value.
• reputation.getMode(id) returns the reputation mode for an entity.
• reputation.setMode(id, mode) sets the reputation mode.
• reputation.getEffectiveLimits(id) returns the effective minimum and maximum for an entity.
• reputation.getEffectiveTiers(id) returns the effective tier list for an entity.
• reputation.calcMemberAverageActor(actorUuid) returns the average reputation across an actor’s faction memberships.
• 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

• 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.

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) returns whether a relation is hidden.
• visibility.toggleRelationHidden(type, fromId, toId) toggles relation visibility.
• visibility.getRelationVisibility(type, fromId, toId) returns the relation visibility state.
• visibility.setRelationVisibility(type, fromId, toId, state) sets the relation visibility state.

presets

• presets.list() returns the available setting presets.
• presets.get(id) returns one preset.
• presets.resolve(settings) resolves a settings object against its preset.

changelog

• changelog.get() returns the global changelog.
• changelog.add(entry) adds a changelog entry.
• changelog.getActor(actorUuid) returns an actor’s changelog.
• changelog.addComment(entryId, comment) adds a comment to an entry.
• changelog.setEntryTimestamp(entryId, timestamp) sets an entry’s timestamp.

graphs

• graphs.getIndex() returns the graph index.
• graphs.getEntry(id) returns one graph index entry.
• graphs.create(type) creates a graph.
• graphs.delete(id) deletes a graph.
• graphs.load(id) loads a graph document.
• graphs.save(id, graph) saves a graph document.
• graphs.builder(type) returns a GraphBuilder for the given type.
• graphs.canUserView(id, user) returns whether a user can view a graph.
• graphs.canUserEdit(id, user) returns whether a user can edit a graph.
• graphs.setPermissions(id, permissions) sets graph permissions.
• graphs.updateNode(id, nodeId, changes) updates a node.
• graphs.updateLink(id, linkId, changes) updates a link.
• graphs.addShape(id, shape) adds a shape.
• graphs.updateShape(id, shapeId, changes) updates a shape.
• graphs.removeShape(id, shapeId) removes a shape.

canvas

• canvas.refreshBadges() redraws all token reputation badges.
• canvas.refreshConnections() redraws all scene connection lines.

undo

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

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

• 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

• search(query) returns matching entities across actors, factions, and locations.
• 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

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

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.

Hook	Fires when	Payload
bondsmith.ready	The API is mounted during Foundry’s ready phase.	BONDSMITH.api
bondsmith.repChanged	A reputation value changes.	{ id, type, oldValue, value, userId }
bondsmith.relationChanged	A relation value changes.	{ type, fromId, toId, oldValue, newValue }
bondsmith.settingsChanged	Settings are saved.	{ settings }
bondsmith.factionDuplicated	A top-level faction is duplicated.	{ sourceId, newId, options }
bondsmith.locationDuplicated	A top-level location is duplicated.	{ sourceId, newId, options }
bondsmith.journalLinked	A journal is linked to an actor, faction, or location.	{ type, id, journal, previous }
bondsmith.journalUnlinked	A journal link is removed.	{ type, id, previous }
bondsmith.dataReset	Module data is reset.	{ scope }
bondsmith.ruleFired	An automation rule applies a change.	{ ruleId, hookName, target, delta, payload, isTestFire }

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

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 keys: individual, faction, actorFaction, factionToFaction, factionToLocation, and actorToLocation.
• GRAPH_TYPES holds the graph type keys: force, genealogy, map, and timeline.
• REP_MODES holds the reputation mode keys.