MPassports — Plugin Documentation
Version: 1.6
Minecraft: 1.20.x – 1.21.x
API: Paper, Spigot, Bukkit
Installation
- Drop MPassports.jar into your server's /plugins/ folder
- Restart the server
- Plugin generates: config.yml, lang.yml, gui.yml, passports.yml, fines.yml
- Edit the files to your liking and run /passport reload
Soft Dependencies
These plugins are optional. MPassports works without them but gains extra features when present.
| Plugin | Feature unlocked |
|---|---|
| PlaceholderAPI | Passport placeholders available in other plugins |
| Vault | Fine payment system (economy) |
| LuckPerms | Job and position lines shown in passport display |
| MJob | Job/position integration via service API |
Commands
All commands start with /passport. Aliases: none.
Player Commands
| Command | Description |
|---|---|
| /passport create | Create your passport |
| /passport gui | Open the passport GUI menu |
| /passport show [player] | Display your own or another player's passport in chat |
| /passport get | Receive a written book copy of your passport |
| /passport set <field> <value> | Edit a field on your own passport |
| /passport setbirth <DD> <MM> <YYYY> | Set your birth date |
| /passport ask <firstname> <lastname> | Request to view another player's passport |
| /passport accept | Accept a pending passport view request |
| /passport deny | Deny a pending passport view request |
| /passport history | View your own passport change history |
Editable Fields (/passport set)
| Field | Description | Validation |
|---|---|---|
| firstname | First name | Any text |
| lastname | Last name | Any text |
| age | Age | Number 0–99 |
| gender | Gender | Male or Female only |
| dc | Discord ID | Any text |
| city | City of residence | Any text |
| marriage | Partner name | Any text, or clear to remove |
Birth date is set separately:
/passport setbirth <DD> <MM> <YYYY>
Example: /passport setbirth 15 06 1998
Admin Commands
| Command | Description |
|---|---|
| /passport set <player> <firstname> <lastname> <age> <gender> | Set all main fields for another player at once |
| /passport list | List all players who have a passport |
| /passport reload | Reload config, lang, GUI, passports and fines from disk |
| /passport revoke <player> | Delete a player's passport entirely |
| /passport history <player> | View another player's change history |
| /passport expiry set <player> <DD.MM.YYYY> | Set an expiry date for a player's passport |
| /passport expiry clear <player> | Remove the expiry date from a player's passport |
| /passport expiry check <player> | Check when a player's passport expires |
Fine Commands
| Command | Permission | Description |
|---|---|---|
| /passport fine give <player> <rule> <amount> | passport.fine | Issue a fine to a player |
| /passport fine info <player> | passport.fine | View all fines for a player |
Permissions
| Permission | Description | Default |
|---|---|---|
| passport.admin | Access to all admin commands (list, reload, revoke, expiry, history of others, set other player) | OP |
| passport.fine | Issue fines and view fine records | OP |
| passport.ask | Send passport view requests to other players | true (everyone) |
| passport.list | View the full passport list | OP |
PlaceholderAPI Placeholders
Requires PlaceholderAPI to be installed.
| Placeholder | Returns |
|---|---|
| %passport_firstname% | Player's first name |
| %passport_lastname% | Player's last name |
| %passport_age% | Player's age |
| %passport_gender% | Player's gender (Male / Female) |
| %passport_id% | Unique passport ID (e.g. A1B2C3D4) |
| %passport_birthdate% | Birth date in DD.MM.YYYY format |
| %passport_dc% | Player's Discord ID |
| %passport_city% | Player's city |
| %passport_partner% | Player's marriage partner |
| %passport_expiry% | Passport expiry date (DD.MM.YYYY) or empty if not set |
| %passport_expired% | true if passport is expired, false otherwise |
If a value is not set, the placeholder returns the value of passport-unknow from lang.yml (default: Unknown).
Configuration
config.yml
passport:# Days until a newly created passport expires.
# Set to 0 to disable automatic expiry.
valid-days: 0
# Date format used for birth date display
date-format: "dd.MM.yyyy"
lang.yml
All messages sent to players are defined in lang.yml. Color codes supported: legacy (&a, &c, &l, etc.) and HEX (&#RRGGBB).
gui.yml
Controls the appearance of the passport GUI: item materials, slot positions, display names, lore, filler item, and inventory title/size.
GUI Overview
Open with /passport gui.
When you have no passport:
- One button in the center to create your passport
When you have a passport:
| Button | Slot | Action |
|---|---|---|
| Player name | 10 | Display only |
| Passport ID | 11 | Display only |
| First Name | 12 | Click to edit via chat |
| Last Name | 13 | Click to edit via chat |
| Age | 14 | Click to edit via chat |
| Gender | 15 | Click to edit via chat |
| Birth Date | 16 | Click to edit via chat |
| City | 29 | Click to edit via chat |
| Discord ID | 30 | Click to edit via chat |
| Partner | 31 | Click to edit via chat |
| View Passport | 47 | Type a player's name to view their passport |
| Fines | 49 | Opens the fines menu (green = no unpaid, red = unpaid) |
| Ask Passport | 51 | Type a player's nickname to send a view request |
Type cancel in chat at any prompt to abort without saving.
Fine System
Police officers (players with passport.fine) can issue fines to players.
Issue a fine:
/passport fine give <player> <rule> <amount>
Example: /passport fine give Steve 1.1 500
View fines:
/passport fine info <player>
Pay a fine (requires Vault economy): Open /passport gui → click the Fines button → click any unpaid fine (red) to pay it.
Fine statuses: PAID (green) / UNPAID (red).
Passport Expiry
Passports can have an optional expiry date.
Auto-expiry on creation: set passport.valid-days in config.yml to any positive number. New passports will automatically expire after that many days. Set to 0 to disable.
Manual control (admin only):
/passport expiry set <player> <DD.MM.YYYY>
/passport expiry clear <player>
/passport expiry check <player>
When a passport is expired it is clearly marked in /passport show output and in the passport book.
Passport History
Every time a passport field is changed, the change is recorded with:
- Date and time
- Who made the change (player name)
- Which field changed
- Old value → New value
Up to the last 50 changes are stored per passport.
View your own history:
/passport history
View another player's history (admin):
/passport history <player>
Data Storage
All data is stored in YAML files inside the plugin folder (plugins/MPassports/).
| File | Contents |
|---|---|
| passports.yml | All passport data including history and expiry dates |
| fines.yml | All issued fines and their payment status |
| config.yml | Plugin settings |
| lang.yml | All player-facing messages |
| gui.yml | GUI layout and appearance settings |
Data is saved automatically when changes are made and on server shutdown.
