Profiles
Overview
Profiles gives each player several independent characters on the same account. Switching profile swaps the player's inventory, ender chest, experience, health and food, and also their TypeWriter facts, so quest progress, unlocks and counters are separate for each character. Other BTC extensions, such as BTC Sky, attach their own data to the active profile.
Profiles are created and chosen from a menu you design in the web panel. A server can force players to choose a profile before they can move, build, fight or chat. The data is stored in a database when the MySQL bridge is enabled, which makes profiles available on every server of a network, and in files otherwise.
The system is tied to the game mode of the server (mysql.game-mode.current): a player has a separate list of profiles in each game mode.
Features
- Separate characters — inventory, armor, off-hand, ender chest, level, experience, health, food and saturation per profile.
- Separate story state — TypeWriter facts are saved on switch and restored for the profile.
- Profile menu — a GUI with one slot per profile, templates for active, inactive, free and locked slots.
- Forced selection — until a profile is active, the player cannot move, interact, break, place, drop, fight or chat.
- Solo and coop — a profile is created as solo or coop (BTC Sky shared island), and a game mode without coop skips the question.
- Limits — a default maximum and higher limits per permission.
- Switch protection — a cooldown between switches and an event other extensions can cancel.
- Entries — actions to open the menu, create, switch, rename, delete and save, facts about the profile state, and events.
- Cross-server — profiles and their data are shared through the MySQL bridge.
- Placeholders — name, id, count, limits and per-profile details for menus and HUDs.
Installation
- Install the GUI extension, which draws the menu. The Basic extension is declared as a dependency.
- Recommended: install the MySQL extension and enable it (
mysql.enabled: true). Without it, profiles are stored in files and are not shared between servers. - Put the Profiles JAR in
plugins/Typewriter/extensions/and restart the server. - Edit the
profilessection ofplugins/Typewriter/mysql/config.yml, see Configuration. Profiles reads its settings from the MySQL extension's configuration file even when you do not use a database. - Create the menu entries described in Getting started.
Getting started
Set up a profile selection that new players must complete:
- In the TypeWriter web panel, open a page and add a Profile Menu Config entry.
/profileopens the first one found, and does nothing when none exists. - Set
inventoryTitle,inventoryRowsandguiType. Build the layout inlayoutPooland setmainLayoutId. See the GUI guides. - Place items with
buttonPrefixprofile_button:andbuttonTypePROFILE_SLOTwhere profiles must appear. Each marker shows one profile, read left to right then top to bottom. Slots below the player's limit that hold no profile showcreateProfileTemplate, slots beyond the limit showmaxProfilesTemplate. - Set
defaultMaxProfilesand, if needed,permissionLimits. - Create the two GUI pages used for creation, as Open GUI entries with the ids
profile_create_chooser(a Solo or Coop choice) and, for game modes without coop,profile_create_solo. A button on these pages runsprofile create soloorprofile create coop, and for solo-only modesprofile createalone. - In
plugins/Typewriter/mysql/config.yml, checkprofiles.force-profile-selection(defaulttrue) andprofiles.coop-supported. - Publish, join the server, and pick or create a profile.
Use Switch Profile Action or Open Profile Menu Action from NPCs and items. React to switches made by the switch action or by typed commands with the Profile Switched Event.
Use the Profile Count Fact and Is Profile Active Fact facts in criteria. For example, show a "create a profile" button only while Can Create Profile Fact is 1.
How it works
On a switch, the extension checks the cooldown, then fires a cancellable pre-switch event so a game mode can refuse (for example during a war or a minigame). It then captures the player's current state, writes it to the repository, clears the player's TypeWriter facts and inventory, and restores the target profile's data. The state of the active profile is also saved when the player quits.
What is saved depends on the configuration: inventory and ender chest (save-inventory, save-ender-chest) and Minecraft statistics (save-statistics, off by default because of its size). Level, experience, health, food and TypeWriter facts are always saved.
Because facts are swapped, anything stored in a fact belongs to the profile. Data of other extensions follows their own profile-mode in the MySQL configuration: per-profile data is kept separately for each profile, shared data is common to all profiles.
Configuration
Profiles has no configuration file of its own. Its settings are in the profiles section of plugins/Typewriter/mysql/config.yml, created by the MySQL extension.
| Key | Default in the shipped file | Meaning |
|---|---|---|
profiles.enabled | true | Turns the profile system on. |
profiles.max-profiles | 2 | Maximum profiles per player when no Profile Menu Config entry exists. The entry's defaultMaxProfiles replaces it. |
profiles.default-profile-name | Principal | Name of the automatic profile. |
profiles.save-statistics | true | Save Minecraft statistics per profile. Uses a lot of storage. |
profiles.save-inventory | true | Swap the inventory per profile. |
profiles.save-ender-chest | true | Swap the ender chest per profile. |
profiles.require-permission | false | Require typewriter.profiles.create to create a profile. |
profiles.auto-create-default | true | Create a default profile on first join. Only works when coop-supported is false. |
profiles.force-profile-selection | true | Block the player until a profile is active. |
profiles.switch-cooldown-seconds | 60 | Minimum delay between two switches of a player. 0 disables it. |
profiles.coop-supported | true | Whether this game mode has coop profiles. When false, the Solo or Coop question is skipped and every profile is solo. |
profiles.creation-menu-entry-id | empty | Id of the GUI page opened to create a profile. Empty means profile_create_chooser when coop is supported and profile_create_solo otherwise. |
The values above are those of the shipped file. The built-in fallbacks differ when a key is missing (max-profiles 5, save-statistics true, auto-create-default false), so keep the keys in your file.
Storage. With mysql.enabled: true and profiles.enabled: true, profiles are stored in the table typewriter_profiles. Otherwise they are stored as assets in profiles/<game mode>/<player uuid>.json. Profiles saved in the old Profile Storage Artifact artifact are copied to the new storage automatically at start.
Menus
The Profile Menu Config entry describes the menu. A click on a profile switches to it, Shift + left click deletes it (after a confirmation screen unless deleteConfirmation is off), and a click on a free slot opens the creation page. Creating a profile asks its name in an anvil. {profile_name}, {profile_id}, {created_date}, {last_used}, {level}, {exp}, {health}, {food}, {profile_count} and {max_profiles} can be used in titles, names and lore.
Button items with buttonPrefix profile_button: support PROFILE_SLOT (one profile), and the markers INFO and CLOSE, which run profile info and gui:close.
Slots can run profile open, profile select <id>, profile create solo|coop and profile delete <id>, as the clicking player.
Default texts of the menu, messages and the cooldown message are in French. Change them in the menu entry.
Commands
All commands need profiles.use. Aliases: /profil, /profiles.
| Command | Description |
|---|---|
/profile | Open the profile menu. |
/profile menu | Open the profile menu. |
/profile select <id> | Switch to a profile. |
/profile create solo or coop | Create and activate a profile; the name is asked in an anvil. Without a mode, only for game modes without coop. |
/profile delete <id> [confirm] | Delete a profile that is not active. Opens the confirmation screen first when deleteConfirmation is on, unless confirm is given. |
/profile admin list <player> | List the profiles of an online player (requires profiles.admin). |
/profile admin create <player> <name> | Create a solo profile for a player. |
/profile admin delete <player> <id> | Delete a profile of a player. |
/profile admin switch <player> <id> | Switch a player to a profile. |
/profile admin rename <player> <id> <name> | Rename a profile. |
/profile headless list, select <id>, create <name> | Manage your own profiles without a menu (requires profiles.headless). |
A menu listener handles /profile typed by a player before the command tree: it supports select, create, delete and opening the menu, and ignores the others. /profile admin ... and /profile headless ... therefore work reliably from the console, or through the /profil and /profiles aliases.
Permissions
| Permission | Default | Grants |
|---|---|---|
profiles.use | Everyone | The /profile commands. |
profiles.admin | Operators | /profile admin. |
profiles.headless | Nobody | /profile headless, for clients without a screen such as test bots. |
profiles.switch.bypasscooldown | Nobody | Switch with no cooldown. |
typewriter.profiles.create | Nobody | Create profiles when profiles.require-permission is true. |
Permissions of permissionLimits | You choose | Raise the profile limit. The highest limit wins. |
Placeholders
MiniPlaceholders tags for MiniMessage text. A reference is a position in the list (digits, from 0) or a profile id.
| Placeholder | Returns |
|---|---|
<profile_active_id>, <profile_active_name> | Id and name of the active profile. |
<profile_active> | 1 when a profile is active. With a reference, <profile_active:0> tells whether that profile is the active one. |
<profile_count> | Number of profiles. |
<profile_max> | Maximum number of profiles for the player. |
<profile_can_create> | 1 when the player can create another profile. |
<profile_remaining> | Number of profiles still available. |
<profile_friend_count> | Number of friends, 0 without the Friend extension. |
<profile_enabled> | 1 when the system is on. |
<profile_name:ref>, <profile_id:ref> | Name and id of a profile. |
<profile_created:ref>, <profile_last_used:ref> | Dates as dd/MM/yyyy HH:mm. |
<profile_created_timestamp:ref>, <profile_last_used_timestamp:ref> | Epoch milliseconds. |
<profile_level:ref>, <profile_exp:ref> | Level, and experience progress as a percentage. |
<profile_health:ref>, <profile_food:ref> | Saved health and food level. |
Entries
20 entries, generated from the extension source.
Actions6
- Create Profile ActionCreates a new profile for the player
- Delete Profile ActionDeletes a specific profile
- Open Profile Menu ActionOpens the profile selection menu for the player
- Rename Profile ActionRenames a specific profile
- Save Profile ActionSaves the current profile state
- Switch Profile ActionSwitches the player to a specific profile
Events5
- Profile Created EventTriggered when a player creates a new profile
- Profile Deleted EventTriggered when a player deletes a profile
- Profile Loaded EventTriggered when a player's profile is loaded on join
- Profile Saved EventTriggered when a player's profile is saved
- Profile Switched EventTriggered when a player switches profiles
Facts7
- Can Create Profile FactReturns 1 if player can create more profiles, 0 otherwise
- Has Active Profile FactReturns 1 if player has an active profile, 0 otherwise
- Is Profile Active FactReturns 1 if the specified profile is active, 0 otherwise
- Max Profiles FactReturns the maximum number of profiles allowed per player
- Profile Coop Enabled FactReturns 1 if the active profile was created as a coop profile
- Profile Count FactReturns the number of profiles a player has
- Profiles Enabled FactReturns 1 if the profile system is enabled, 0 otherwise
Artifacts1
- Profile Storage ArtifactStores player profiles with separate inventories and data
Manifests1
- Profile Menu ConfigConfiguration for the profile selection menu
Troubleshooting
/profile does nothing. There is no Profile Menu Config entry. Create and publish one.
New players are frozen and cannot chat. profiles.force-profile-selection is true and no profile is active. The player is sent to the creation page after joining; make sure the GUI entry profile_create_chooser (or profile_create_solo, or your creation-menu-entry-id) exists. Set the option to false to disable the lock.
"Choisissez d'abord Solo ou Coop dans le menu des profils." The player tried a command while forced. Only /profile ... and the creation page command are allowed until a profile is active.
"Vous devez attendre N s avant de changer à nouveau de profil." The switch cooldown is running. Lower profiles.switch-cooldown-seconds or grant profiles.switch.bypasscooldown.
No default profile is created at first join. auto-create-default only works when coop-supported is false. With coop, a player must choose Solo or Coop, and the log says "No implicit profile was created; disable the setting."
Profiles differ between servers. The MySQL extension must be enabled (mysql.enabled: true) on every server with the same database and game mode. Without it, profiles are in local files. If MySQL is enabled but the data source is missing, the log says "MySQL enabled for profiles but DataSource not found. Falling back to JSON."
Players lose items after a switch. Check save-inventory and save-ender-chest. When they are false, the inventory is not swapped and is not cleared either, so items are shared between profiles.
A switch is refused with a message. Another extension cancelled it through the pre-switch event, for example during a fight or a minigame. The message comes from that extension.