@ursamu/sw5e-plugin

Star Wars 5E TTRPG system for UrsaMU -- chargen, combat, Force/Tech powers, AI GM bridge.

Data sourced from sw5eapi (eager bulk-pull on init, cached in DBO).

Status

V1 vertical slice -- chargen wizard end-to-end, plus thin combat (HP, conditions, dice). Encounter tracker, power-points-per-rest, and multiclass deferred.

Commands

All commands below require the connected lock unless noted.

Command	Description
+chargen[/<step>] [<arg>]	Hybrid wizard (see steps below)
+species [<name>]	List species, or set on draft
+class [<name>[/<archetype>]]	List classes, or set class+arch
+background [<name>]	List backgrounds, or set
+abilities <S,D,C,I,W,Ch>	Assign ability scores
+skills <list>	Pick proficiencies
+equipment <pkg>	Pick starter package
+powers <list>	Pick Force/Tech powers
+sheet [<player>]	View own sheet (admins: any)
+lookup/<resource> <name>	Reference lookup (see below)
+roll <kind> [adv|dis] [dc=<n>]	d20 roll, returns success/fail
+hp <±n>|set=<n>|max=<n>	Modify HP (canEdit for others)
+condition/<op> <name>	Manage 5e conditions
+rest/<short|long> [dice=<n>]	Short/long rest — refill pools
+power/cast <name>	Spend FP/TP to invoke a known power
+combat[/start|end|status|add]	GM encounter tracker
+init [<n>|auto]	Join active encounter, roll initiative
+next	Advance to next combatant's turn
+sw5e-cache/<status|refresh>	Admin: inspect / re-pull cache

Chargen steps: start, species, class, archetype, background, abilities, skills, equipment, powers, review, submit, cancel, back.

Lookup resources: species, class, archetype, background, power, equipment, feat, condition, monster, lightsaberform, skill.

Roll kinds: skill, save, or attack. Rolls d20 plus ability mod plus proficiency.

Condition ops: add, remove, list.

Sibling plugin integration

Plugin	How sw5e plugs in
@ursamu/help-plugin	See below
@ursamu/jobs-plugin	See below
bbs (@ursamu/bbs-plugin)	See below
Channels (core u.chan)	Not consumed in V1

• help-plugin: call registerHelpDir(./help, "sw5e") in init(). One .md per command.
• jobs-plugin: call registerJobBuckets(["SW5E-CGEN", "SW5E-BUGS"]). Chargen +chargen/submit files a job in SW5E-CGEN; jobHooks.on("job:resolved", ...) finalizes the sheet.
• bbs-plugin: no public registration API. To create an SW5E board, run seedBoards(["SW5E"]) in your game's bootstrap. Not auto-run by this plugin.
• Channels: channel-routed dice shortcuts deferred to V2.

Storage

Collection	Purpose
sw5e.cache.*	Cached reference data (see below)
sw5e.chargen	In-progress sessions, keyed by playerId
Player IDBObj data.sw5e	Active sheet (written on approval)

sw5e.cache.* holds species, class, power, and other SW5E reference data. Refresh via +sw5e-cache/refresh.

REST routes (Bearer JWT)

Method	Path	Description
GET	/api/v1/sw5e/sheet/:playerId	Self; admin any
GET	/api/v1/sw5e/reference/:resource[/:name]	Cache read
POST	/api/v1/sw5e/roll	Server-side roll for caller

Install

Drop the plugin folder into src/plugins/sw5e/ of your UrsaMU install (or deno add jsr:@ursamu/sw5e-plugin). Auto-discovered on next restart.

Requires --allow-net=sw5eapi.azurewebsites.net for the initial cache pull.

Voice

All player-facing output is themed Star Wars (holo-transmissions, kessel rolls, the Archive, comm-chatter). Internal logs and JSDoc remain plain English.

License

MIT.