Events

Plugins subscribe to proxy and game events via ctx.events. Handlers receive a typed payload depending on the event name.

Subscribing

ctx.events.on('game:start', (payload) => {
  // payload is GameStartPayload: { timestamp, mode, map?, gametype, server }
  ctx.client.sendChat(`§a${payload.mode} on ${payload.map ?? '?'}`);
});

// Fire once, then auto-unsubscribe
ctx.events.once('opponent:detected', (payload) => {
  ctx.client.sendChat(`§eOpponent: ${payload.username}`);
});

// Unsubscribe (same function reference as on())
const handler = (p: GameEndPayload) => { /* ... */ };
ctx.events.on('game:end', handler);
ctx.events.off('game:end', handler);

Event list

Event	When it fires	Payload
`proxy:ready`	Proxy has started	`BaseEventPayload` (timestamp)
`client:connected`	Player connected to proxy	`ClientConnectedPayload` (username, uuid)
`client:disconnected`	Player disconnected	`ClientDisconnectedPayload` (username, reason?)
`game:start`	Game has started (mode/map known)	`GameStartPayload` (mode, map?, gametype, server)
`game:end`	Game ended (any result)	`GameEndPayload` (mode, map, result, duration, opponents?)
`game:victory`	Player won	`GameEndPayload`
`game:defeat`	Player lost	`GameEndPayload`
`game:join`	Player joined a game	`GameJoinPayload` (mode, map?, gametype, server)
`game:leave`	Player left a game	`GameLeavePayload` (mode, result?, duration?)
`lobby:join`	Player joined a lobby	`LobbyJoinPayload` (gametype, lobbyname, server)
`lobby:leave`	Player left a lobby	`BaseEventPayload`
`locraw:update`	/locraw data updated	`LocrawUpdatePayload` (data, previous?)
`server:change`	Server changed	`LocrawUpdatePayload`
`mode:change`	Game mode changed	`ModeChangePayload` (newMode, previousMode)
`opponent:detected`	Opponent detected in game	`OpponentDetectedPayload` (username, uuid?, mode)
`opponent:stats`	Opponent stats fetched	`OpponentStatsPayload` (username, uuid, mode, stats)

All payloads extend BaseEventPayload and include timestamp: number.

TypeScript types

Import payload types from @duelsplus/plugin-api for type-safe handlers:

import type { GameStartPayload, OpponentDetectedPayload } from '@duelsplus/plugin-api';

ctx.events.on('game:start', (payload: GameStartPayload) => {
  // payload.mode, payload.map, payload.gametype, payload.server
});

The package uses PluginEventName and PluginEventPayloadMap so on() and once() infer the payload type from the event name.