Configuration

The mod-level configuration file lives at config/showdown_actions/config.conf. It controls global behavior — whether actions are evaluated at all, which battle types they apply to, and whether the verbose debug log is on. Per-action settings live in the action files themselves.

`config.conf`

The defaults:

enabled = true        # master switch
applyInPvp = true     # fire in PvP battles
applyInPve = true     # fire in PvE battles (vs wild / NPC)
applyInNpcOnly = false # fire in NPC vs NPC (no player actor)
debug = false         # verbose match/apply trace logging

Field reference

Field	Type	Default	Effect
`enabled`	Boolean	`true`	Master switch. When `false`, ShowdownActions still loads the `.conf` files, but the battle-start hook is a no-op — nothing matches, nothing applies.
`applyInPvp`	Boolean	`true`	Whether actions evaluate in player-vs-player battles.
`applyInPve`	Boolean	`true`	Whether actions evaluate in player-vs-wild and player-vs-NPC battles.
`applyInNpcOnly`	Boolean	`false`	Whether actions evaluate in NPC-vs-NPC battles (no player actor on either side). Off by default because most servers have no use for it.
`debug`	Boolean	`false`	Enables verbose `[ShowdownActions]` logs at runtime. See Debug Logging.

The “battle type” is determined by counting player actors in the battle. Zero player actors is NPC-only; one is PvE; two or more is PvP.

Hot Reload

/showdownactions reload

Re-parses config.conf and every .conf in actions/. Both happen in sequence:

config.conf is reloaded; the debug flag takes effect immediately.
The actions/ directory is re-scanned. New files are loaded, removed files are dropped, edited files replace their previous version. The new ruleset takes effect at once — battles that are mid-evaluation never see a half-loaded state.
Each action’s Showdown condition is re-registered, including in format-specific dexes (singles, doubles, etc.) so they all see the updated rules.
Battles already in progress keep the conditions they were registered with at start. New battles pick up the new rules.

A reload that fails on one file doesn’t bring down everything else — the offending file is logged with its parse error, the previous version of that action stays live (if there was one), and the rest reloads normally.

Debug Logging

The single biggest tool for figuring out why an action isn’t firing is debug = true. Toggle it via the config file (then /showdownactions reload), or at runtime without persisting:

/showdownactions debug on
/showdownactions debug off

When debug is on, every (action, pokemon) pair gets a trace line as it’s evaluated — the compiled Molang predicate, whether the result was match or miss, and which gate (permission, chance roll, mutex group) ate the action if it got that far. Every Cobblemon-side effect (forced aspect, console command) is logged when it fires. Showdown hook fires and errors are logged through the auto-applied hook wrapper.

A typical “why didn’t this match” debug session reads like:

[hook] BATTLE_STARTED_PRE id=… actors=2 candidates=8
[matcher] action='rainy_swift_swim' species=pikachu molang='q.world.is_raining && q.pokemon.level >= 30' → miss
[matcher] action='lycanroc_dusk' rejected by property check on pikachu
[hook] queued 'friendship_aura' (matched on pikachu) → condition='showdownactionsfriendshipaura' side=p1 slot=0
[hook] registered 1 volatile(s) across 1 side(s) for battle …
[ShowdownActions][showdownactionsfriendshipaura] onStart fired

Read top-to-bottom: every candidate is tested, you see exactly why it was rejected, and you see the hook fire on the Showdown side at switch-in. See the Showdown Research page for the full grammar of these lines.

What Lives Where

File	What it controls
`config/showdown_actions/config.conf`	Mod-level settings (this page).
`config/showdown_actions/actions/*.conf`	One file per action. See Action Files.

Per-action settings — enabled, priority, chance, permission, mutexGroup, etc. — live inside the individual .conf files, not here. There is intentionally no global “default boost amount” or “default target” knob: each action declares its own behavior end-to-end so you can read one file and know what it does.

Next Steps

Action Files — the structure of a single .conf and the three authoring tiers.
Match Clause — every gate field and when it re-evaluates.
Apply Clause — every effect field and what it compiles to.