🗡 ffxiv-overlay-api 🛡

Build your own modern FFXIV overlay with npm & TypeScript support.

This library needs to be used along with ngld/OverlayPlugin.

Table of Contents

• Installation
• Usage
• Options
• API
• Development
• Contributon
• Annotations

Browsers Support

Supports major browser versions released at 2020 or ES2020.

• Chrome: >=87
• Firefox: >=78
• Safari: >=14

Installation

You can install it from npm registry:

npm install ffxiv-overlay-api --save

Or import the library from CDNs:

<script src="https://cdnjs.cloudflare.com/ajax/libs/ffxiv-overlay-api/4.8.0/overlay.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/lib/overlay.min.js"></script>
<script src="https://unpkg.com/[email protected]/lib/overlay.min.js"></script>
<script>
  const overlay = new OverlayAPI();
</script>

Usage

After installation, you can import the library:

import { OverlayAPI } from 'ffxiv-overlay-api';
const overlay = new OverlayAPI();

// use static tool functions directly
OverlayAPI.isCEFSharp();
// import tool functions
import { isCEFSharp } from 'ffxiv-overlay-api';
isCEFSharp();

Then you can add bunch of different listeners.

overlay.addListener('CombatData', (data) => {
  console.log('listener of `CombatData`', data);
});
overlay.addListener('ChangeZone', (data) => {
  console.log('listener of `ChangeZone`', data);
});

Call this function once you’re done adding all of your listeners:

overlay.startEvent();

Once this function has been called, OverlayPlugin will start sending events. Some events will be raised immediately with current state information like ChangeZone or ChangePrimaryPlayer.

After that, put the URL of your overlay into OverlayPlugin, or use the WebSocket URL when enabled. Checkout the index.html for example usage, you can download this file and load it from the OverlayPlugin. Enable WebSocked in your plugin and add ?OVERLAY_WS=ws://127.0.0.1:[port]/ws or ?HOST_PORT=ws://127.0.0.1:[port] after you overlay URL to access the WebSocket server.

Checkout Development section for more details and my new overlay Skyline Overlay for example.

API

You can find all events available in https://ngld.github.io/OverlayPlugin/devs/event_types.

addListener

addListener(event: EventType, cb: EventCallback): void;

add an event listener

removeListener

removeListener(event: EventType, cb: EventCallback): void;

remove a listener

removeAllListener

removeAllListener(event: EventType): void;

remove all listener of one event type

getAllListener

getAllListener(event: EventType): EventCallback[];

get all listeners of a event

startEvent

startEvent(): void;

start listening event

endEncounter

endEncounter(): Promise<void>;

ends current encounter and save it, not working in websocket mode

callHandler

callHandler(msg: any): Promise<any>;

This function allows you to call an overlay handler, these handlers are declared by Event Sources, either built into OverlayPlugin or loaded through addons like Cactbot.

simulateData

simulateData(data: EventData): void;

simulate triggering event once

mergeCombatant (direct export)

mergeCombatant(...args: CombatantData[]): CombatantData | null;

static function for merging combatant like pets into first player arg

class2job (direct export)

class2job(baseClass: string): string;

convert base class to job or return input base class if not found

job2class (direct export)

job2class(job: string): string;

convert job to base class or return input job if not found

isCEFSharp (direct export)

isCEFSharp(): boolean;

check if in overlay plugin emblemed cef

Development

Clone this repo, then:

npm install
npm start

You can access the test overlay at http://localhost:5000/test/, http://localhost:5000/test/?OVERLAY_WS=ws://127.0.0.1:[port]/ws or http://localhost:5000/test/?HOST_PORT=ws://127.0.0.1:[port].

Remember to run npm run build before release commit.

Contributon

Please use the .prettierrc at the root of the project along with Prettier default settings to format your code.

Annotations

• ngld/OverlayPlugin - MIT License
• hibiyasleep/OverlayPlugin - MIT License
• RainbowMage/OverlayPlugin - MIT License

Copyright © 2020-present DSRKafuU (https://dsrkafuu.net)