Passport Overview

Passport Overview

Concept Phase

Passport is the canonical profile layer for a Matcha! network. It should be useful even on a single server, but it becomes especially valuable when players move between nodes, events, seasons, web surfaces, and Discord.

---

Core Philosophy

Passport should make player identity feel earned and curated, not scraped. The mod can collect achievements from many systems, but the player decides what to show unless staff policy says otherwise.

Player-Owned Presentation

Players choose active titles, pinned badges, showcase slots, and profile visibility.

Server-Owned Truth

Badges, sanctions, link state, and grant history remain authoritative and auditable.

Cross-Surface Consistency

In-game profile cards, web pages, and Discord embeds should all render from the same Passport record.

---

System Design

flowchart LR
    Minecraft[Minecraft Account] --> Identity[Passport Identity]
    Discord[Discord Account] --> Identity
    Web[Web Session] --> Identity
    Mods[Matcha Mods] --> Badges[Badge Mints]
    Badges --> Identity
    Identity --> Card[Trainer Card]
    Identity --> Profile[Web Profile]
    Identity --> Embeds[Discord Embeds]

Identity Record

{
  "player_uuid": "uuid",
  "display_name": "Amo",
  "active_title": "Verdant Champion",
  "visibility": "public",
  "links": {
    "discord_id": "1234567890",
    "web_user_id": "user_abc"
  },
  "showcases": {
    "pokemon": "pokemon_ref",
    "relic": "relic_item_ref",
    "badge_1": "jubilee:verdant_completion"
  }
}

Badge Registry

Badges should have structured metadata:

Field	Purpose
id	Stable badge identifier, e.g. jubilee:verdant_skies_tier_100
name	Display name
source	Minting mod or admin source
rarity	Cosmetic rarity or display tier
issued_at	Audit timestamp
revocable	Whether staff or source mod can remove it

Privacy Model

• Public: profile appears in web directory and can be linked in Discord.
• Server-only: visible in game but hidden from public web pages.
• Friends/group-only: optional future scope if a social graph exists.
• Private: only player and authorized staff can inspect full details.

Moderation fields should be separate from public cosmetic fields.

---

Gameplay Design

Player Loop

1. Earn a badge, title, or showcase item from another mod.
2. Receive a Passport toast or Courier mail summarizing the unlock.
3. Open /passport to equip it.
4. View the trainer card in game or on the web.
5. Share it in Discord or let others inspect it in game.

Long-Term Goals

• Complete badge families from multiple seasons.
• Collect titles from Frontier ranks, Journey questlines, Reverie contests, and Festival attendance.
• Build a prestige profile that survives resets.
• Curate a public identity for guilds, teams, or server communities.

---

Cross-Mod Hooks

Mod	Passport Role
Jubilee	Season completion badges, chapter stamps, recap cards, active seasonal titles
Festival	Event attendance stamps, limited-time titles, photo/card frames
Treasury	Entitlement history for cosmetic profile unlocks
Courier	Sends profile unlock notifications and link-code messages
Relic	Showcases favorite Relic, level, inscriptions, and lore history
Frontier	Ranked badges, peak rating titles, team affiliation
Reverie	Contest ribbons, tournament trophies, coordinator titles
Bazaar	Market reputation badges if enabled by server policy

---

Non-Goals

• Passport should not replace LuckPerms.
• Passport should not decide reward eligibility; Treasury and source mods own that.
• Passport should not expose private account links publicly.
• Passport should not make profile cosmetics mandatory for gameplay power.