Member & Role Events

Relevant source files

The following files were used as context for generating this wiki page:

• src/events/memberEvents.ts
• src/util/logging/logAction.ts
• src/util/levelingSystem.ts
• config.example.json
• src/db/db.ts
• src/commands/util/user-info.ts

Member and Role events constitute the core lifecycle management system of the Poixpixel Discord Bot. This system is responsible for handling user transitions—such as joining, leaving, or updating profiles—and managing role assignments triggered by administrative actions or automated leveling progression.

These events ensure that the bot's internal database remains synchronized with the Discord server's state while providing automated onboarding features like welcome banners and initial role assignments.

Member Lifecycle Events

The bot tracks three primary member states: joining, leaving, and profile updates. These are handled via the Events.GuildMemberAdd, Events.GuildMemberRemove, and Events.GuildMemberUpdate listeners.

Member Join Logic

When a user joins the guild, the bot performs several concurrent operations to initialize the user in the system. This includes database registration, automated role assignment, and visual greeting.

The system uses a Collection to batch member data before calling setMembers to ensure the database record is created or updated upon entry.
Sources: src/events/memberEvents.ts:16-56, src/db/db.ts:602

Member Leave and Updates

• Member Leave: When a member leaves, the bot updates the database record via updateMember to set currentlyInServer to false and records the lastLeftAt timestamp.
• Member Update: This handler monitors changes in usernames, nicknames, and roles. It specifically triggers logAction for audit purposes when a nickname or username changes.
  Sources: src/events/memberEvents.ts:58-154, src/commands/util/user-info.ts:100-112

Role Management & Automation

Role events are handled both as reactive listeners (logging when roles are added/removed) and as proactive automation (assigning roles based on leveling).

Level-Based Role Assignment

The bot includes an automated system to grant roles as users reach specific XP milestones. This logic is encapsulated in the leveling system utility.

The configuration for these roles is defined in the roles.levelRoles array within the bot's configuration file.
Sources: src/util/levelingSystem.ts:251-285, config.example.json:85-91

Audit Logging for Role Changes

Role modifications (creation, deletion, and updates) are captured by logAction. The system generates a detailed comparison of permission changes and metadata updates.

Action	Description	Data Captured
roleAdd / roleRemove	Individual user role changes	User, Role, Moderator (if applicable)
roleCreate / roleDelete	Metadata changes to roles	Name, Color, Hoist status, Mentionable status
roleUpdate	Permission or position changes	Old/New Permissions, Position, Color

Sources: src/util/logging/logAction.ts:275-345

Configuration and Implementation Details

The behavior of member and role events is highly dependent on the config.json settings.

Relevant Configuration Keys

Path	Type	Description
channels.welcome	String (ID)	The channel where welcome banners and messages are sent.
roles.joinRoles	Array (IDs)	Roles automatically granted to every non-bot user upon joining.
roles.levelRoles	Array (Objects)	Mapping of level (Integer) to roleId (String).
dataRetention.deleteAfterDays	Number	How long to keep member data after they leave.

Sources: config.example.json:71-105

Implementation Snippet: Join Roles

The following logic demonstrates how roles are applied during the memberJoin event:

// src/events/memberEvents.ts:46-51
await Promise.all([
  welcomeChannel.send({ ... }),
  member.send({ ... }),
  member.roles.add(config.roles.joinRoles),
  logAction({ ... }),
]);

Sources: src/events/memberEvents.ts:46-51

Conclusion

The Member & Role event system provides a robust framework for managing user integration and server hierarchy. By combining database persistence with real-time Discord event listeners and automated leveling rewards, the bot maintains an active and organized environment. All actions are meticulously logged to the configured audit channel, ensuring administrative transparency for all membership and role-related transitions.