Creating Squadjs Plugins

Creating SquadJS Plugins

Overview

A SquadJS plugin is an ES-module class — extending BasePlugin or DiscordBasePlugin — that reacts to a fixed set of server events and acts through RCON. SquadJS gives you those events, a small set of RCON/server methods, and a fixed set of player fields. Nothing else.

Core principle: map every requirement onto a real SquadJS event, method, and field before writing code. If a requirement maps to nothing — or to something unreliable — say so and propose the closest reliable alternative. Never fabricate a capability. A dead code branch that reads a field which does not exist (death coordinates, player health) is worse than telling the user the truth, because it ships as if it worked.

When to use

• Creating or scaffolding a new SquadJS plugin, or adding a server-side feature via SquadJS.
• Answering "can SquadJS do / detect X?" — use the capability surface + hard limits below.
• Reviewing a plugin for the common traps (see Common Mistakes).

Not for: modifying the SquadJS core itself, or non-SquadJS Discord bots.

Workflow

1. Brainstorm intent first. REQUIRED SUB-SKILL: superpowers:brainstorming. Pin down the concrete behaviours the admin wants, in plain language, before any mapping.
2. Map each requirement → capability. For every behaviour, find the event that triggers it and the method that performs it in references/api-reference.md. Write the mapping down.
3. Feasibility gate. Check each mapping against references/event-reliability.md. If a requirement maps to nothing, or to an unreliable signal, STOP and tell the user before coding. The hard-limits table below lists the usual culprits.
4. Pick base class & connectors. DiscordBasePlugin if it posts to Discord, else BasePlugin. Add the sequelize connector only if state must survive restarts.
5. Scaffold from a template. Copy the matching file from templates/ — they already encode the correct lifecycle and avoid the traps below.
6. Implement. Bind every handler in the constructor; mount() and unmount() must be exactly symmetric; handlers must be idempotent (events burst and duplicate); read config from this.options.*.
7. Verify + install. references/installation.md covers the config.json block and live-server verification (load it, watch verbose output, exercise it in-game).

Before you finish — mechanical self-checks (run these on your plugin file)

Do not rely on memory or on copied code — run each check; every one must pass:

• grep -n removeEventListener <file> returns nothing. It throws TypeError at runtime and leaks the listener; use removeListener/off. This is the single most common bug, and the bundled core plugins (discord-teamkill.js, auto-tk-warn.js, …) contain it — so if you modelled your code on a core/example plugin, you almost certainly copied it. Fix it.
• Listener symmetry: every this.server.on(...) in mount() has a matching removeListener in unmount(), and every setInterval/setTimeout has a matching clearInterval/clearTimeout in unmount().
• No invented API: every event name you register, and every rcon.*/server.* call, appears in references/api-reference.md. If it's not there, it doesn't exist.

The feasibility-gate decision (where it goes wrong)

digraph feasibility {
    rankdir=LR;
    req [label="A requirement", shape=oval];
    maps [label="Maps to a real\nevent + method + field?", shape=diamond];
    reliable [label="Reliable per\nevent-reliability.md?", shape=diamond];
    build [label="Build it", shape=box];
    tell [label="Tell the user it is impossible;\npropose the closest alternative", shape=box];
    caveat [label="Tell the user the caveat;\ndesign around it (timer /\nUPDATED_PLAYER_INFORMATION diff)", shape=box];

    req -> maps;
    maps -> tell [label="no"];
    maps -> reliable [label="yes"];
    reliable -> caveat [label="no"];
    reliable -> build [label="yes"];
}

Hard limits — SquadJS CANNOT do these (verified against the core)

Quick reference

Most-used events: CHAT_COMMAND:<name>, CHAT_MESSAGE, PLAYER_WOUNDED, PLAYER_DIED, TEAMKILL, PLAYER_TEAM_CHANGE, NEW_GAME, ROUND_ENDED, UPDATED_PLAYER_INFORMATION. Act via this.server.rcon.warn(anyID, msg), .broadcast(msg), .switchTeam(anyID), .execute(rawAdminCommand). Full catalog + every payload shape: references/api-reference.md.

Three non-obvious patterns (see references/api-reference.md §3, §4, §7):

• Team by faction short name, not teamID. No faction field exists; teamID 1/2 flips each round. Resolve a short name ("USA") via the role classname prefix (USA_Rifleman_01) — a naming convention, not an API guarantee.
• Configurable / aliased command lists: loop and register CHAT_COMMAND:${cmd} per alias (normalize a string-or-array option to an array, bind once, mirror in unmount); match CHAT_MESSAGE yourself only when the trigger isn't a clean single !word (see §3).
• Double-switch to unstick a bugged player (§4): call switchTeam twice with a short delay — the player leaves and returns to their own team, re-spawning the pawn with no net side change.

Common mistakes (every one observed in baseline testing)