Roll20 Typescript Type Definition

roll20.d.ts

/// <reference path="../node_modules/@types/underscore/index.d.ts" />

/**
 * Roll20 Typescript Type Declaration file
 * @author Andrew Cousineau <andruc@gmail.com>
 * @license MIT-0
 */

// API Objects
// https://help.roll20.net/hc/en-us/articles/360037772793-API-Objects
type ObjectTypeName = 'page' | 'campaign' | 'player' | 'deck' | 'card' | 'hand' | 'jukeboxtrack' | 'custfx' | CreatableObjectType

type CreatableObjectType = 'graphic' | 'text' | 'path' | 'character' | 'ability' | 'attribute' | 'handout' | 'rollabletable' | 'tableitem' | 'macro'

type ObjectEvent = 'change' | 'add' | 'destroy'

type Roll20EventName = `${ObjectEvent}:${ObjectTypeName}`

interface Roll20Object {
	readonly id: string

	get(prop: '_id'): string
	get(prop: '_type'): string
	get(prop: string): string | boolean | number

	set(prop: string): void

	remove(): void
}

type ObjectData = {
	[key as string]: string | boolean | number
}

type FXType = 'bomb' | 'bubbling' | 'burn' | 'burst' | 'explode' | 'glow' | 'missile' | 'nova'

type FXColor = 'acid' | 'blood' | 'charm' | 'death' | 'fire' | 'frost' | 'holy' | 'magic' | 'slime' | 'smoke' | 'water'

type FX = `${FXType}-${FXColor}`

type RGBA = [number, number, number, number]

interface CustomFX {
	maxParticles: number
	size: number
	sizeRandom: number
	lifeSpan: number
	lifeSpanRandom: number
	speed: number
	speedRandom: number
	gravity: Point
	angle: number
	angleRandom: number
	emissionRate: number
	startColour: RGBA
	startColourRandom: RGBA
	endColour: RGBA
	endColourRandom: RGBA
}

interface Point {
	x: string
	y: string
}

declare var _ = UnderscoreStatic;

declare var state: any;

declare function Campaign(): Roll20Object;

declare function createObj<T>(type: CreatableObjectType, data: T): T;

declare function filterObjs(callback: (obj: Roll20Object) => boolean): Roll20Object[];

declare function findObjs(data: { [property: string]: any }, options?: { caseInsensitive: boolean }): Roll20Object[];

declare function getAllObjs(): Roll20Object[];

declare function getAttrByName(id: string, attribute: string, type?: 'current' | 'max'): string;

declare function getObj(type: ObjectTypeName): Roll20Object | undefined;

declare function log(message: any): void;

/**
 * @param callback The function that will be called when the specified event fires. The parameters passed depend on the event type:
 * -	ready events have no callback parameters.
 * -	change events have an obj parameter, which is a reference to the Roll20 object as it exists after the change,	and a prev parameter, which is a plain old JavaScript object with properties matching the Roll20 object prior	to the change event.
 * -	add events have an obj parameter, which is a reference to the new Roll20 object.
 * -	destroy events have an obj parameter, which is a reference to the no-longer existing Roll20 object.
 * -	chat events have a msg parameter, which contains the details of the message that was sent to the chat.
 */
declare function on(event: Roll20EventName, callback: (gameObject: Roll20Object) => void): void;
declare function on(event: "chat:message", callback: (message: unknown) => void): void;
declare function on(event: 'ready', callback: () => void): void;

declare function onSheetWorkerCompleted(callback: () => void): void;

declare function playerIsGM(playerId: string): boolean;

declare function playJukeboxPlaylist(playlistId: string): void;

/**
 * Rolls a die of size max
 */
declare function randomInteger(max: number): number;

declare function sendChat(speakingAs: `character|${string}` | `player|${string}` | string, message: string, callback?: (messages: string[]) => void): unknown;
declare function sendChat(speakingAs: `character|${string}` | `player|${string}` | string, message: string, callback: null, options: SendChatOptions): void;

declare function sendPing(left: number, top: number, pageId: string, playerId?: string, moveGm?: boolean): void;

declare function spawnFx(left: number, top: number, type: FX, pageId?: string): void;

declare function spawnFxBetweenPoints(start: Point, end: Point, type: FX, pageId?: string): void;

declare function spawnFxWithDefinition(left: number, top: number, definition: CustomFX, pageId?: string): void;

declare function stopJukeboxPlaylist(): void;

declare function toBack(obj: Roll20Object): void;

declare function toFront(obj: Roll20Object): void;

interface SendChatOptions { use3d?: boolean, noarchive?: boolean }