EventStream — FFXIV Event Bus

A read-only Dalamud plugin plus SDKs that publish a standard, versioned stream of game events (casts, hits, statuses, deaths, chat, etc.) to other plugins (IPC) and, optionally, to localhost (WebSocket) for overlays/tools—without automation, asset redistribution, or ToS issues.

🎯 Value Proposition

• Shared Event Model: Standardized, typed events so plugins don't re-implement parsing
• Fast IPC: In-process C# subscriber API for plugin-to-plugin communication
• Local WebSocket: Optional bridge for TypeScript/Python tools and overlays
• Record/Replay: Deterministic testing with .ffeb format for CI and offline development
• Privacy-First: Read-only, self-only defaults, ephemeral IDs, no uploads

🛡️ Store-Safe Profile

✅ Read-only (no inputs/memory writes)
✅ Default scope: Self only (party requires opt-in)
✅ Names off by default (ephemeral IDs: p:slot-#, e:spawn-#)
✅ WebSocket off by default (localhost only when enabled)
✅ No uploads (local recording only)
✅ No DPS parsing (raw events only)

🚀 Quick Start

Install Plugin

1. Install from Dalamud plugin installer
2. Default settings are store-safe (self-only, names off, WebSocket off)
3. Try the included example subscriber plugin

C# Plugin Development

// Install NuGet: EventStream.Sdk
var filter = new Filter(Types: new[]{ EventType.ActionHit }, PartyOnly: true);
bus.Subscribe<ActionHit>(filter, (env, data) =>
    PluginLog.Information($"[{env.Seq}] {data.Actor.Id} → {data.Target.Id} dmg={data.Result.Damage}")
);

TypeScript Overlay Development

// npm install @eventstream/ffxiv
import { connect, whereType, partyOnly } from "@eventstream/ffxiv";
const bus = await connect({ url: "ws://127.0.0.1:10814" });
bus.pipe(whereType("actionHit"), partyOnly()).onEvent(e => addToDisplay(e));

Python Analytics

# pip install eventstream-ffxiv
import asyncio
from eventstream_ffxiv import connect, where_type

async def main():
    bus = await connect()
    async for e in bus.pipe(where_type("actionHit")):
        print(f"Damage: {e.data.result.damage}")

📊 Performance Targets

• Publisher pipeline: <1ms P95 per event under raid-peak load
• Memory allocation: ≤1 Gen0 per event (pooled buffers)
• WebSocket throughput: ≥10k events/minute sustained
• Drop rate: <1% under normal gameplay

🏗️ Architecture

Game → Dalamud → EventStream → Ring Buffer
                        │              │
                      IPC (C#)    WS (localhost)
                        │              │
                subscriber plugins   overlays/tools

📚 Documentation

• Event Schema Reference
• C# SDK Documentation
• TypeScript SDK Documentation
• Python SDK Documentation
• Contributing Guide
• Security Policy

📦 Packages

• Plugin: Available through Dalamud plugin installer
• C# SDK: EventStream.Sdk on NuGet
• TypeScript SDK: @eventstream/ffxiv on npm
• Python SDK: eventstream-ffxiv on PyPI

🤝 Contributing

We welcome contributions! Please read our Contributing Guide and Code of Conduct.

📄 License

Licensed under MIT License - see LICENSE file for details.

⚖️ Legal Notice

EventStream is a read-only utility that does not automate gameplay or redistribute copyrighted assets. Users must source any game data locally. Not affiliated with Square Enix.