FirstLogin
A lightweight, friendly first-join plugin for Spigot/Paper. Welcomes new players with clean MiniMessage formatting, a configurable Welcome GUI, optional reopen‑until‑accepted rules.
File Details
firstlogin-1.8.0.jar
- R
- Feb 2, 2026
- 1.10 MB
- 223
- 1.21+6
File Name
firstlogin-1.8.0.jar
Supported Versions
- 1.21
- 1.20.3-Snapshot
- 1.20.5-Snapshot
- 1.20.6
- 1.20.5
- 1.20.4
- 1.20.3
# FirstLogin – Changelog
## 1.8.0 (February 3, 2026)
### Performance & Thread Safety
- **Improve**: Thread-safe GUI action tracking using `ConcurrentHashMap` to prevent race conditions
- **Improve**: Cached rules accepted/pending counts with async refresh (60s TTL) to avoid expensive iteration
- **Improve**: Warm up rules counts cache on startup alongside players-to-date cache
### Code Quality
- **Refactor**: Centralized `versionedFlagName()` and `getRulesVersion()` methods in `FirstLogin` class
- **Refactor**: Removed duplicate code across `WelcomeGui`, `FirstLoginCommand`, and `PlayersStore`
- **Refactor**: Replaced reflection hack in `PlayersStore` with direct method call
### Commands & Permissions
- **Add**: Permission `firstlogin.gui.open` (default: true) for `/welcome` command access
- **Add**: Permission `firstlogin.autoaccept` (default: false) for auto-accepting rules on join
- **Improve**: `/welcome` command now works for regular players with page number support (`/welcome [page]`)
- **Improve**: Better error message for console users attempting player-only commands
### Resource Cleanup
- **Add**: Player quit listener to clean up bossbars and guides when players leave
- **Add**: `cleanupPlayerResources()` method for proper resource management
### New PlaceholderAPI Placeholders
- **Add**: `%firstlogin_has_guide%` - true if player has an active animated guide
- **Add**: `%firstlogin_bossbar_active%` - true if bossbar feature is enabled
- **Add**: `%firstlogin_version%` - plugin version string
- **Add**: `%firstlogin_item_clicks_total%` - total item clicks today across all items
### New Commands
- **Add**: `/firstlogin version` - shows plugin version (works from console too)
- **Add**: `/firstlogin debug [gui|inventory|saves|telemetry|all] [on|off]` - toggle debug modes at runtime
- **Add**: `/firstlogin info <player>` - detailed player information (timestamps, flags, cooldowns, once claims)
- **Add**: `/firstlogin validate` - on-demand configuration validation with warnings
- **Add**: `/firstlogin stats` - server-wide statistics (players, telemetry, config status)
- **Improve**: Console users now get helpful message instead of silent failure
### Configuration Validation
- **Add**: Startup validation of config.yml with warnings for:
- Invalid materials in GUI items
- Out-of-bounds slot numbers
- Invalid sound names
- Missing/invalid world name
- Invalid bossbar color/overlay values
### GUI Sounds
- **Add**: Configurable sounds for GUI events:
- `welcomeGui.sounds.open` - played when GUI opens
- `welcomeGui.sounds.close` - played when GUI closes
- `welcomeGui.sounds.rulesAccepted` - played when rules are accepted (enabled by default)
### Action Bar Welcome
- **Add**: New `ActionBarManager` for action bar welcome messages
- **Add**: Configurable action bar settings:
- `actionbar.enabled` - enable/disable feature
- `actionbar.text` - MiniMessage formatted text with `{player}` placeholder
- `actionbar.durationSeconds` - how long to show the message
- `actionbar.refreshTicks` - refresh rate for the action bar
### Help System
- **Add**: `/firstlogin help` - comprehensive help command showing all available commands
- **Add**: `/firstlogin` with no args now shows help instead of doing nothing
### Completed Previously Unfinished Features
- **Fix**: `firstJoinVisuals.title` - now actually sends welcome title on first join
- **Fix**: `firstJoinVisuals.actionbar` - now actually sends action bar message on first join
- **Fix**: `firstJoinVisuals.sound` - now actually plays sound on first join
- **Fix**: `msgFor()` now supports locale-aware messages (checks `messages_<locale>.yml` first)
- **Fix**: `message` config - now sends personal welcome message to first-time players
- **Fix**: `messageGlobal` config - now broadcasts to all players when someone joins for the first time
- **Fix**: `messageBack` config - now sends welcome back message to returning players
- **Fix**: `returningGate.minDaysOffline` - now properly gates messageBack based on days offline
- **Fix**: Join extras (particles, guide, bossbar, title, sound) now only trigger for first-time joins
### Config Documentation
- **Add**: Missing config options now documented in `config.yml`:
- `welcomeGui.reopenOnJoinUntilAccepted` - reopen GUI on every join until rules accepted
- `welcomeGui.bypassClosePermission` - allow bypass with permission
- `welcomeGui.sounds.*` - GUI open/close/rulesAccepted sounds
- `welcomeGui.filler.*` - empty slot filler configuration
- `coordination.*` - join-message coordination to avoid multi-plugin spam
- `bossbar.*` - BossBar welcome message configuration
- `actionbar.*` - Action bar welcome message configuration
- `particles.*` - Particle effects on first join (experimental)
- `animatedGuide.*` - Animated NPC guide (experimental)
### Missing Commands & Permissions
- **Add**: `/firstlogin set <player> <flag|cooldown|locale|timestamp> <key> [value]` - set player data directly
- **Add**: `firstlogin.admin.forceopen` permission (was missing from plugin.yml)
- **Fix**: `/firsthelp` command updated to show modern commands and be more helpful
- **Fix**: `formatting.useMiniMessage` config option now actually controls MiniMessage parsing
- **Fix**: `formatting.usePlaceholders` config option now actually controls built-in placeholder replacement
- **Fix**: Added missing `{online}` and `{owner}` placeholders to placeholder system
- **Add**: `welcomeGui.denySound` config option now documented (sound when action is denied)
- **Add**: `disabledVariant` example added to config.yml (show different item when locked)
- **Add**: `permission` and `hideIfNoPermission` example added to config.yml (permission-gated items)
- **Add**: `runAs` and `cooldownBypassPermission` now documented in config.yml
- **Add**: `delayTicks` and `urlLabel` now documented in config.yml
- **Add**: `requiresAll` and `requiresAny` now documented in config.yml (composite requirements)
- **Add**: `page` option now documented in config.yml (multi-page GUI support)
- **Add**: `pagination` config section now documented (prev/next navigation for multi-page GUIs)
- **Add**: `actions` (multiple actions) now documented in config.yml
- **Add**: All action types now documented (message, command, url, flag:set, flag:clear, page, openRules, acceptRules, back)
- **Add**: All requirement types now documented (flag, perm)
### Enhanced GUI Action System
- **Add**: `sound:<name>:<vol>:<pitch>` action - play sounds on item click
- **Add**: `teleport:<world>:<x>:<y>:<z>:<yaw>:<pitch>` action - teleport players
- **Add**: `give:<material>:<amount>` action - give items directly from GUI
- **Add**: `title:<text>|<subtitle>:<fadeIn>:<stay>:<fadeOut>` action - show titles
- **Add**: `actionbar:<text>` action - show action bar messages
- **Add**: `effect:<type>:<seconds>:<amplifier>` action - apply potion effects
- **Add**: `broadcast:<message>` action - broadcast to all online players
- **Add**: `console:<command>` action - run command as console (ignores runAs)
- **Add**: `player:<command>` action - run command as player (ignores runAs)
- **Add**: `chat:<message>` action - make player send chat message
- **Add**: `xp:<amount>` or `xp:levels:<amount>` action - give XP points or levels
- **Add**: `close` action - close GUI without other actions
### Enhanced Requirement System
- **Add**: `!flag:<name>` - negated flag check (true if flag NOT set)
- **Add**: `!perm:<permission>` - negated permission check
- **Add**: `level:>=10` - check player XP level with comparison operators
- **Add**: `health:>=10` - check player health
- **Add**: `food:>=10` - check player food level
- **Add**: `gamemode:SURVIVAL` - check player gamemode
- **Add**: `world:<name>` - check world name
- **Add**: `online:>=10` - check online player count
- **Add**: `time:day` or `time:night` - check world time
- **Add**: `weather:clear` - check weather (clear, rain, storm)
- **Add**: `cooldown:key:60` - check if cooldown expired
- **Add**: `played:>=3600` - check total playtime in seconds
### Enhanced Item Display Options
- **Add**: `amount` - set item stack size (1-64)
- **Add**: `glow: true` - add enchantment glow without visible enchantment
- **Add**: `customModelData` - support for resource pack custom models
- **Add**: `hideAttributes: true` - hide item attributes for cleaner tooltip
- **Add**: `hideFlags: true` - hide all item flags (enchants, attributes, etc.)
- **Add**: `skullOwner` - set player head texture (supports {player} placeholder)
- **Add**: `color` - set leather armor color (#RRGGBB or color name)
### Advanced Action Types
- **Add**: `heal:<amount>` or `heal:full` - heal player
- **Add**: `feed:<amount>` or `feed:full` - feed player
- **Add**: `gamemode:<mode>` - set player gamemode
- **Add**: `fly:on/off/toggle` - toggle flight ability
- **Add**: `random:action1|action2|...` - pick random action from list
- **Add**: `delay:<ticks>:<action>` - execute action after delay
- **Add**: `if:<requirement>:<action>:<elseAction>` - conditional action execution
- **Add**: `repeat:<count>:<action>` - repeat action N times (max 100)
- **Add**: `chance:<percent>:<action>` - execute with X% chance
### Enhanced Placeholder System
- **Add**: `{health}` and `{max_health}` - player health values
- **Add**: `{food}` - player food level
- **Add**: `{level}` and `{xp}` - player XP level and percentage
- **Add**: `{world}`, `{x}`, `{y}`, `{z}` - player location
- **Add**: `{gamemode}` - player gamemode (survival, creative, etc.)
- **Add**: `{time}` - world time (day/night)
- **Add**: `{weather}` - world weather (clear/rain/storm)
- **Add**: `{playtime}` and `{playtime_hours}` - total playtime
- **Add**: `{ping}` - player ping in ms
- **Add**: `{uuid}` and `{uuid_short}` - player UUID
- **Add**: `{bar_health}`, `{bar_food}`, `{bar_xp}` - visual progress bars (10 chars)
- **Add**: `{progress:current:max:width:filledColor:emptyColor}` - custom progress bar generator
### Visual Effects & Item Enhancements
- **Add**: `firework:<color>:<type>:<power>` action - launch fireworks at player
- **Add**: `particle:<type>:<count>` action - spawn particles at player
- **Add**: `enchantments` item option - add enchantments to GUI items
- **Add**: `potionColor` item option - set custom potion color
- **Add**: `potionEffects` item option - add potion effects to potion items
### Player Control Actions
- **Add**: `bossbar:<text>:<color>:<seconds>` action - show temporary boss bar
- **Add**: `cleareffects` action - clear all potion effects from player
- **Add**: `cleareffect:<type>` action - clear specific potion effect
- **Add**: `velocity:up:<power>` or `velocity:x:y:z` action - apply velocity to player
- **Add**: `sudo:<command>` action - make player run command
- **Add**: `op:<command>` action - run command with temporary OP
### Join Tracking & Events
- **Add**: Login streak tracking (consecutive days played)
- **Add**: Max login streak tracking
- **Add**: Total logins counter
- **Add**: Anniversary detection and celebration messages
- **Add**: `FirstJoinEvent` custom event for other plugins to hook into
- **Add**: `ReturningPlayerEvent` custom event with streak and anniversary info
- **Add**: Streak milestone messages (7, 14, 30, 60, 90, 100, 365 days)
- **Add**: Referral system (track who invited new players)
- **Add**: Player notes system for admins
### Discord/Slack Webhooks
- **Add**: Webhook notifications for first-time joins
- **Add**: Webhook notifications for returning players
- **Add**: Customizable webhook messages with placeholders
- **Add**: Anniversary notifications in webhooks
### Dependencies
- **Update**: Adventure API to 4.17.0 (from 4.14.0)
- **Update**: Adventure Platform Bukkit to 4.3.4 (from 4.3.1)
- **Update**: bStats to 3.0.3 (from 3.0.2)
---