From 9d7e695e04bae29ea05f04e21821330aeda4833c Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Tue, 13 Oct 2026 01:04:51 +0000 Subject: [PATCH] Describe finding living characters by real name Document TLibs 2.5.0's Characters.findByName and how RPCharacters answers it, and update the RPCharacters TLibs pin to 2.5.0. Co-Authored-By: Claude Opus 5.5 --- projects/RPCharacters/docs/character-identity.md | 11 ++++++++--- projects/TLibs/character-identity.md | 8 ++++++-- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/projects/RPCharacters/docs/character-identity.md b/projects/RPCharacters/docs/character-identity.md index e5e7adc..e762f36 100644 --- a/projects/RPCharacters/docs/character-identity.md +++ b/projects/RPCharacters/docs/character-identity.md @@ -3,7 +3,7 @@ [RPCharacters](../README.md) ยท [TLibs API](../../TLibs/character-identity.md) RPCharacters provides TLibs' `CharacterIdentity` service through Bukkit's -`ServicesManager`. The build pins TLibs 2.4.1; install that release or a compatible +`ServicesManager`. The build pins TLibs 2.5.0; install that release or a compatible newer one before RPCharacters. Consumers use the `Characters` facade rather than reading RPCharacters files or waiting a fixed number of ticks after login. @@ -36,7 +36,12 @@ Login also compares loaded character IDs against the directory. An account whose records cannot be loaded completely is disconnected before admission or saves. `CharacterInfo.name` is the real, plain character name. `displayName(player)` uses -the current mask and temporary alias rules. The playtime field is the existing +the current mask and temporary alias rules. + +`findByName(name)` first overlays every loaded account, then scans the in-memory +directory, so it reads no files. It returns every `ALIVE` character whose real name +equals the trimmed `name`, ignoring case. Dead and missing characters, aliases, +masks and temporary aliases never match, and unavailable accounts are skipped. The playtime field is the existing `online-playtime-seconds` counter, with no visibility filtering. ## Sessions and readiness @@ -125,7 +130,7 @@ covering the whole account. Run `mvn clean verify` with Java 21 and pinned dependencies installed. The unit suite checks directory corruption and duplicates, skipped stray entries, the -legacy `lastPlayed` fallback, immutable snapshots, live updates, delayed +legacy `lastPlayed` fallback, name lookups, immutable snapshots, live updates, delayed readiness, reconnects, repeated-character switches, event order, quit and shutdown cleanup, cancelled and inactive deaths, distinct death IDs after revival, failed saves, and activation failures after a committed death or diff --git a/projects/TLibs/character-identity.md b/projects/TLibs/character-identity.md index 7339aeb..3fbcbb1 100644 --- a/projects/TLibs/character-identity.md +++ b/projects/TLibs/character-identity.md @@ -44,10 +44,14 @@ caller. | `deathId(UUID characterId)` | Most recent saved death ID, including after revival; empty when unknown. | | `characters(UUID ownerId)` | Every character on the account, as an immutable copy. Empty means the records could not be read; an empty list means the account has none. | | `lastPlayed(UUID ownerId)` | The character the account played most recently, dead or alive. | +| `findByName(String name)` | Living characters whose real name equals `name`, ignoring case, as an immutable list. Masks and aliases never match. Several characters can share a name, so callers that need one character must handle more than one match. | | `displayName(Player)` | The name other players see now, including masks and aliases. | -Without a provider, lookups return empty, `isCurrent` returns false and -`displayName` returns the account name. That fallback is acceptable for display and +`findByName` was added in TLibs 2.5.0. The interface has an empty default, so a +provider built against an older TLibs finds nobody. + +Without a provider, lookups return empty, `findByName` returns an empty list, +`isCurrent` returns false and `displayName` returns the account name. That fallback is acceptable for display and gameplay checks. Ownership and money must wait for `available()`, and must never treat an empty `characters` result as an account with no characters.