Bot Module Updates

When you publish a new version of your bot module, Lumio updates all installations while preserving every customization the user has made. This page explains the update lifecycle and the override resolution system.

Override resolution

Every configurable field follows a single rule:

resolved_value = COALESCE(user_override, extension_default)

If the user has set a custom value, that value is used. If not, the extension default is used. User overrides are never overwritten by extension updates.

What users can override

Users customize bot modules through the dashboard settings panel:

Setting	Extension provides	User can override
Command cooldown (global)	Default value	Custom value
Command cooldown (per-user)	Default value	Custom value
Command min role	Default value	Raise (not lower) the minimum role
Command enabled	true	Toggle on/off
Command alias	Name from manifest	Alternative name (e.g. punkte for points)
Keyword enabled	true	Toggle on/off per keyword
Custom keywords	None	User-added keywords
Timer interval	Default interval	Custom interval
Timer enabled	true	Toggle on/off
Config values	Defaults from config_schema	Custom values

Update flow

When you publish a new version:

Developer publishes new version
  |
  v
API marks version as "published"
  |
  v
Auto-update enabled?
  -> Yes: automatic install
  -> No: Update badge in dashboard, user clicks "Update"
  |
  v
extension_installs.version_id updated
  |
  v
Three things happen:
  1. Config migration
  2. Trigger sync
  3. Worker + bot reload

1. Config migration (non-destructive)

Change	Result
New config_schema field added	Default value inserted (user has no override yet)
config_schema field removed	User override kept as dead data, cleaned on next save
Default value changed	No effect on users with existing overrides
Default value changed	Users without overrides get the new default

2. Trigger sync (non-destructive)

Change	Result
New command added	Appears with extension defaults, no user override
Command removed	User overrides for that command are cleaned up
Command renamed	Old name removed (with override cleanup), new name appears with defaults
Cooldown/role defaults changed	No effect on users with overrides
New keyword added	Appears enabled by default
Keyword removed	User overrides cleaned up
New pattern added	Appears enabled by default
Pattern removed	Cleaned up
New timer added	Appears enabled with default interval
Timer removed	User overrides cleaned up
Timer interval changed	No effect on users with custom intervals
Handler logic changed	New code loaded, no config impact

User-added custom keywords are always preserved across updates.

3. Worker and bot reload

After the update:

• Bots reload the extension trigger lists (commands, keywords, patterns, moderation flag)
• The Worker invalidates its V8 cache, loads the new handler code, and restarts timers with current intervals

Update safety matrix

What changed	User has override?	Result
Default cooldown 5s to 3s	Yes (10s)	User keeps 10s
Default cooldown 5s to 3s	No	User gets new default 3s
New command added	N/A	Appears with extension defaults
Command removed	Yes	Override cleaned up, command gone
New config field	N/A	Default value inserted
Config field removed	Yes	Override kept (dead data, cleaned on save)
Keyword added	N/A	Enabled by default
Keyword removed	Yes (disabled)	Override cleaned up
User-added keyword	N/A	Preserved, never touched by updates
Handler logic changed	N/A	New code loaded, no config impact
Timer interval changed	Yes (custom)	User keeps custom interval
Timer interval changed	No	User gets new default
New timer added	N/A	Appears enabled with default interval

Best practices for updates

Adding new features

When adding new commands, keywords, or config fields, users get sensible defaults automatically. No migration code is needed.

{
  "triggers": {
    "commands": [
      { "name": "points", "description": "Existing command" },
      { "name": "leaderboard", "description": "New command in v1.1.0" }
    ]
  },
  "config_schema": [
    { "key": "pointsPerMessage", "type": "number", "label": "Points per message", "default_value": 1 },
    { "key": "leaderboardSize", "type": "number", "label": "Leaderboard entries", "default_value": 10 }
  ]
}

Removing features

When removing a command or config field, the user's overrides are cleaned up automatically. No manual cleanup code is needed.

Renaming commands

If you rename a command (e.g., !pts to !points), the old command is removed and the new one appears with defaults. Users who had aliases on the old command will need to reconfigure them. Consider this when renaming commands in minor versions.

Changing defaults

Changing a default cooldown or config value only affects users who have not customized that setting. Users with overrides keep their customized values. This means you can safely adjust defaults without disrupting existing users.