# FirstLogin (v1.8.0)

A lightweight, friendly first-join experience for Spigot/Paper. Show polished welcome messages, optional visuals (titles/action bar/sounds), and a configurable Welcome GUI that can gate “rules accepted” with an optional confirm dialog. Includes async player data saving and PlaceholderAPI placeholders for timestamps, telemetry, and join order.

## Features

- Global + private welcome messages

- Adventure MiniMessage support (with seamless legacy `&` fallback)

- Optional visuals: Title, Action Bar, Sound

- Returning player gate: greet again only if offline for X days

- Welcome GUI: per-item permissions and gating (once/cooldown/closeOnClick/clickSound)

- Reopen-on-join until current rules are accepted (configurable)

- Optional confirmation dialog before accept

- Asynchronous players.yml saving (non-blocking)

- Telemetry counters (today): GUI opens, rules accepted, per-item clicks

- PlaceholderAPI support (timestamps, telemetry, join order)

- bStats metrics (opt-out)

### Experimental (opt-in)

- Particle effects on first join (`particles.enabled`) — disabled by default

- Animated NPC guide (`animatedGuide.enabled`) — disabled by default

- Toggle in `config.yml` and apply at runtime with `/firstlogin reload`

## Requirements

- Spigot or Paper 1.20+

- Java 17

- Optional: PlaceholderAPI (to use `%firstlogin_*%` placeholders)

- Toggle the FirstLogin expansion via `placeholderapi.enabled`. Use `/firstlogin reload` to dynamically register/unregister the expansion at runtime.

## Installation

1) Drop `firstlogin-1.8.0.jar` into your `plugins/` folder.

2) Start the server once to generate:

- `plugins/FirstLogIn/config.yml`

- `plugins/FirstLogIn/messages.yml`

- `plugins/FirstLogIn/players.yml`

3) Configure messages and visuals to your liking.

4) Restart the server (recommended over `/reload`).

## Commands

- `/listp` — number of players who have joined to date

- `/pnames` — list of names who have joined to date

- `/owner` — prints server owner from config

- `/onlinep` — online/total summary

- `/firsthelp` — quick help

- `/firstlogin` — admin utilities (tab-complete)

- `reload` — reload config/messages

- `gui <open [player]|accept [player]|trigger <key> [player]>`

- `clearcooldown <player> <key|all>`

- `clearflag <player> <flag|all>`

- `seen <player>` / `reset <player|all>` / `status [player]`

- `set <key> <value>` — runtime toggles

- `metrics [reset|when|now]` — view telemetry (last/next reset with pretty durations), reset today, or reset immediately

## PlaceholderAPI Placeholders

Timestamps and status:

- `%firstlogin_first_join_date%` — formatted first join time (uses `formatting.datePattern`, default `yyyy-MM-dd HH:mm:ss`)

- `%firstlogin_rules_accepted_date%` — formatted rules accepted time

- `%firstlogin_days_since_first_join%` — whole days since first join

- `%firstlogin_first_join_ts%` — epoch millis of first join (0 if unknown)

- `%firstlogin_rules_accepted_ts%` — epoch millis of rules acceptance (0 if unknown)

- `%firstlogin_days_since_rules_accepted%` — whole days since rules acceptance (0 if unknown)

- `%firstlogin_rules_version_accepted%` — highest rules version accepted (0 if none)

- `%firstlogin_rules_pending%` — true if player has NOT accepted current rules version

Telemetry and join order (new in 1.7.2):

- `%firstlogin_gui_opens_today%`

- `%firstlogin_rules_accepted_today%`

- `%firstlogin_item_clicks_today_<key>%` — per-GUI-item click counter using your item key

- `%firstlogin_join_order%` — 1-based join order (alias: `%firstlogin_join_number%`)

Telemetry reset (new in 1.7.3):

- `%firstlogin_metrics_reset_date%` — formatted date/time of the last telemetry reset

- `%firstlogin_metrics_last_reset_ts%` — epoch millis of the last telemetry reset (0 if never)

- `%firstlogin_metrics_next_reset_date%` — formatted date/time of the next scheduled telemetry reset

- `%firstlogin_metrics_next_reset_ts%` — epoch millis of the next scheduled telemetry reset (0 if disabled)

Additional timing/pretty placeholders (new in 1.7.3):

- `%firstlogin_metrics_next_reset_in_seconds%`

- `%firstlogin_metrics_next_reset_in_minutes%`

- `%firstlogin_metrics_next_reset_in_hours%`

- `%firstlogin_metrics_next_reset_pretty%` — e.g., "3h 14m 5s"

- `%firstlogin_metrics_last_reset_pretty%` — e.g., "1d 2h 3m 4s ago"

Examples:

```

/papi parse me %firstlogin_player%

/papi parse me %firstlogin_first_join_date%

/papi parse me %firstlogin_gui_opens_today%

/papi parse me %firstlogin_item_clicks_today_confirm_accept%

/papi parse me %firstlogin_join_order%

/papi parse me %firstlogin_metrics_reset_date%

/papi parse me %firstlogin_metrics_next_reset_date%

```

## Configuration Highlights

- `formatting`: toggle MiniMessage, built-ins, and PlaceholderAPI resolution

- `returningGate.minDaysOffline`: greet returning players only if away X days

- `welcomeGui`: define items, permissions, gating, once/cooldown, click actions/sounds

- Runtime toggles via `/firstlogin set <key> <value>` (no file edits needed)

- Debug toggles for GUI/inventory logging

- Telemetry reset scheduling: `telemetry.reset.enabled` (bool), `telemetry.reset.time` (HH:mm; reschedules immediately on change)

## Permissions (examples)

- `firstlogin.admin` — use `/firstlogin` admin commands

- `firstlogin.command.listp` — `/listp`

- `firstlogin.command.pnames` — `/pnames`

- `firstlogin.command.owner` — `/owner`

- `firstlogin.command.onlinep` — `/onlinep`

- `firstlogin.command.firsthelp` — `/firsthelp`

## bStats

Anonymous usage statistics help guide development and can be disabled:

- Globally via `plugins/bStats/config.yml`

- Or per-plugin in `plugins/FirstLogIn/config.yml` (if exposed)

## What's New in 1.8.0

### Enhanced GUI System

- **29 Action Types**: message, command, url, sound, give, teleport, effect, title, actionbar, broadcast, heal, feed, gamemode, fly, firework, particle, bossbar, velocity, cleareffects, sudo, op, random, delay, if, chance, repeat

- **13 Requirement Types**: flag, !flag, perm, !perm, level, health, food, gamemode, world, online, time, weather, cooldown, played

- **10 Item Display Options**: amount, glow, customModelData, hideAttributes, hideFlags, skullOwner, color, enchantments, potionColor, potionEffects

- **15+ New Placeholders**: {health}, {food}, {level}, {xp}, {world}, {x}, {y}, {z}, {gamemode}, {time}, {weather}, {playtime}, {ping}, {uuid_short}

- **Progress Bars**: {bar_health}, {bar_food}, {bar_xp}, custom {progress:current:max:width:filledColor:emptyColor}

### Join Tracking & Events

- Login streak tracking (consecutive days played, max streak)

- Anniversary detection and celebration messages

- `FirstJoinEvent` and `ReturningPlayerEvent` custom events for other plugins

- Streak milestone messages (7, 14, 30, 60, 90, 100, 365 days)

- Referral system and player notes for admins

### Discord/Slack Webhooks

- Webhook notifications for first-time joins and returning players

- Customizable messages with placeholders

- Anniversary notifications in webhooks

## What’s New in 1.7.2

- Asynchronous `players.yml` saving for Welcome GUI state (non-blocking)

- Persisted timestamps: `timestamps.<uuid>.first_join`, `timestamps.<uuid>.rules_accepted`

- PlaceholderAPI: first join + rules date/epoch, days-since; telemetry counters; join order

- `/firstlogin metrics` to view/reset today’s counts

- GUI improvements: reopen-on-join until accepted, optional confirm dialog

---

Thanks for checking out FirstLogin! Feedback and suggestions are welcome.