Pets

Collectible companion pets that follow or float above players, gain XP, level up and wear skins.

Privatev0.0.2Entities & models

RequiresTypeWriter0.9.0-beta-177 (BTC build)GUI (TypeWriter extension)ModelEngineoptionalUiCore (TypeWriter extension)optional

Built for the BornToCraft network. This extension is documented for reference and is not distributed.

Support

Overview

Pets adds collectible companions inspired by EcoPets. Each pet is defined once in the web panel (a Pet Definition), and each player owns copies of it. A pet is handed out as a token item: right-clicking the token adds the pet to the player's companion menu. From the menu the player activates one pet at a time, and that pet floats above their head, walks beside them or flies around them.

Pets gain experience when the owner kills mobs or when your story grants XP, and level up following a formula or a table you write. A pet can retaliate against mobs that hit its owner, and can have several skins that unlock through TypeWriter criteria.

Features

• Three display modes — HEAD floats above the player, GROUND walks beside them, FLY hovers at a set height.
• Companion menu — a GUI with a grid of owned pets, activation, hide and show, details and skins.
• Token items — pets move between players as items that keep their level, XP, mode and skin.
• XP and levels — a formula such as {level} * 100 or an explicit table, with a maximum level.
• Kill XP and story XP — XP per mob kill, plus an action to grant XP from any sequence.
• Retaliation — optional counter-attack on mobs that hurt the owner, with damage per level.
• Skins — several NPC skins per pet, each with criteria, priority and a menu icon.
• Slot permissions — lock menu slots behind permissions to sell extra companion slots.
• Placeholders — name, level, XP, status and ownership of the active pet, a slot or any pet.
• Model support — ground and flying pets use any entity definition, including ModelEngine models.

Installation

1. Install the GUI extension, which draws the menus.
2. Optional: install ModelEngine and the TypeWriter extension that exposes your models as entity definitions, if pets should use animated models.
3. Put the Pets JAR in plugins/Typewriter/extensions/ and restart the server.
4. Create a Pet Storage artifact so owned pets are saved, see Getting started.

Getting started

Create a first pet and give it to a player:

1. In the TypeWriter web panel, open a static page and add a Pet Storage artifact. Without it the extension logs "No pet_storage entry found" and nothing persists.
2. Add a Pet Definition. The entry's own name is the pet's display name and its id is the pet identifier.
3. Choose defaultMode. For HEAD, optionally paste a base64 texture for the floating head. For GROUND or FLY, set npc to an entity definition entry that will be spawned beside the player.
4. Under xp, set maxLevel, and either a formula using {level} (for example {level} * 100) or a levels list. Set killReward for XP per kill.
5. Optional: tick combat.enabled for retaliation, and customise token (the item, its name and lore, and a glow).
6. Add a Pets Open Menu action, set its storage to your Pet Storage artifact, and trigger it from an NPC, an item or a command.
7. Publish, then run /pets give <pet> 1 as a player. Right-click the token, then open the menu and click the pet to activate it.

To grant XP from your story, add a Pets Add XP action with amount. It goes to the player's active pet. To control a specific pet, use Pets State with pet and action.

How players get a pet

There is no action that unlocks a pet directly. A pet reaches a player as a token item, from /pets give or from the menu's "return to item" button. Run the command from a console command action in a quest or a shop to make it an unlockable reward.

How it works

A player owns at most one pet per definition. Only one pet is active at a time: activating another deactivates the first. Pets are saved to the Pet Storage artifact in the background, and the active pet is restored when the player joins.

Display modes.

• HEAD shows the pet above the player's head with headOffset applied. If npc is set, that entity is used. Otherwise an invisible armor stand wears a player head with texture.
• GROUND spawns the npc (or the selected skin's NPC) a few blocks behind the player and makes it follow. swimMode decides whether it swims in liquids: AUTO follows the entity's capabilities, ALWAYS and NEVER force it.
• FLY is the same as GROUND but the pet hovers flightHeight blocks above the player.

If a GROUND or FLY pet has no NPC (or none of its skins match), it is not shown and a warning is logged. A name label with the level is shown above every active pet. The mode comes from defaultMode when the token is first created and stays with that pet instance.

XP and levels. A pet starts at level 1. Each entry of levels gives the total XP a pet must have reached for a level, for example level 2 at 100 XP, level 3 at 250 XP. Explicit entries win over the formula. The formula is evaluated with {level} replaced by the level to reach, and supports + - * /, parentheses and decimals. A pet without any requirement for the next level does not level up.

Retaliation. With combat.enabled, an active and visible pet strikes back any non-player mob that damages the owner, after a short delay and with a 1.5 second cooldown per attacker. The damage is the damage of the highest levels entry at or below the pet's level. Without one, it is 1.5 plus 0.5 per level above 1.

Skins. Each skins entry points to an NPC definition, a priority and criteria. The pet uses the skin the player picked if its criteria still match, otherwise the highest-priority skin whose criteria match. The npc field of the definition is the fallback skin. A skin entry needs an npc, otherwise it is ignored.

Menus

The Pets Open Menu action opens the built-in companion menu, titled "Compagnons". Each owned pet is a player-head icon showing level, XP progress and state. Left click activates or deactivates the pet, right click opens its detail screen. The detail screen shows the stats, lets the player activate, choose a skin (when the pet has more than one), return the pet to an item, or go back. A button in the bottom-left corner shows or hides the active pet.

Menu settings are fields of the menu object of the action:

• slots — inventory slot numbers where pets are shown. The default is 21 slots in three rows.
• lockedSlots — pairs of slot and permission. A slot whose permission the player lacks shows a locked marker, and no pet can be placed in it.
• maxSlots — maximum number of slots used (default 21, minimum 1): only the first maxSlots entries of slots are laid out and can receive a new pet. It limits the layout and how many pets a player can obtain, not what they already own.
• rows — menu height, 1 to 6.
• storage — the Pet Storage artifact to use.

The slot layout of the last opened menu is saved with the player data and decides which slots a token can fill. A pet the player already owns in a slot beyond maxSlots (or outside the menu height) is not hidden: it is shown in a free cell of the menu, never on the show/hide button, and its clicks still act on its own slot. If there are more such pets than free cells, the extra ones stay owned and appear in the Pets page of the shared Social menu, which lists every owned pet; a warning is logged once per player.

Use in your own menu. The extension registers the pets_button: button prefix for any GUI menu. Set an item's buttonPrefix to pets_button: and its buttonType to one of:

buttonType	Shows
PET_ENTRY	The pet at that position in the player's list. Left click toggles it, right click selects it for the detail items.
PET_DETAIL_INFO	Level, XP and mode of the selected pet.
PET_LEVEL_ENTRY	One level of the selected pet with its XP requirement and state.
PET_DETAIL_REMOVE	A button that returns the selected pet to an item.
PET_LIST_NAV, PET_DETAIL_NAV	Page arrows for the pet list and the level list.

Slots can also run the pet_menu commands pet_menu activate <slot>, pet_menu deactivate <slot>, pet_menu toggle_visibility, pet_menu details <slot>, pet_menu skins <slot>, pet_menu select_skin <pet> <skin> and pet_menu remove <slot>.

If UiCore is installed it can read the player's companions to draw a HUD or a menu page.

Language

Menu texts, token lore and the label above a pet are in French by default (for example "Niveau", "Compagnons"). Edit the token name, lore and noSlotMessage per pet. Other menu texts are fixed in the code.

Commands

The permission typewriter.pets is required for every subcommand, together with the permission shown. Most subcommands accept an optional player selector [target] after their arguments to act on someone else; without it they act on the sender.

Command	Permission	Description
/pets open [target]	typewriter.pets.open	Open the companion menu.
/pets activate <pet> [target]	typewriter.pets.activate	Activate an owned pet.
/pets deactivate [target]	typewriter.pets.deactivate	Send the active pet away.
/pets show [target]	typewriter.pets.show	Show the active pet again.
/pets hide [target]	typewriter.pets.hide	Hide the active pet.
/pets remove <pet> [target]	typewriter.pets.remove	Delete a pet from the player's menu. No item is returned.
/pets give <pet> <amount> [target]	typewriter.pets.give	Give 1 to 64 token items.

<pet> is the id or the name of a Pet Definition entry. The bare command /pets does nothing in this version: use /pets open.

Permissions

None is registered with a default, so only operators have them unless you grant them with a permissions plugin.

Permission	Grants
typewriter.pets	The /pets command tree.
typewriter.pets.open	/pets open.
typewriter.pets.activate	/pets activate.
typewriter.pets.deactivate	/pets deactivate.
typewriter.pets.show	/pets show.
typewriter.pets.hide	/pets hide.
typewriter.pets.remove	/pets remove.
typewriter.pets.give	/pets give.
Permissions from lockedSlots	Unlock the matching menu slot. You choose the names.

Placeholders

Pets exposes one TypeWriter placeholder entry, Pets Placeholder. Create it once. The tag is <typewriter_ENTRY:...>, where ENTRY is the lowercase name or id of that entry, for example <typewriter_pets_placeholder:active:name> when the entry is named pets_placeholder.

Argument path	Returns
active	Name of the active pet, empty when none.
active:name, active:id	Name and id of the active pet.
active:level, active:xp, active:max_level	Level, XP and maximum level.
active:next_xp	XP required for the next level, Max at the top.
active:damage	Retaliation damage at the current level.
active:status	active or inactive.
active:visibility	hidden or visible.
active:mode	head, ground or fly.
slot:<index>:name, id, level, xp, next_xp, max_level, damage, visibility, mode	The same fields for the pet in that menu slot.
slot:<index>:status	active, inactive or empty.
pet:<id>:name, description, max_level, xp_per_kill, default_mode, combat, texture	Fields of a Pet Definition.
pet:<id>:owned	true or false for the player.
pet:<id>:level, xp, next_xp, visibility, mode, damage	The player's copy of that pet, empty when not owned.
pet:<id>:status	active, inactive or unowned.

Entries

6 entries, generated from the extension source.

Actions3

• Pets Add XPGrant experience to a pet
• Pets Open MenuOpen the pet selection menu
• Pets StateChange the state of a pet

Placeholders1

• Pets PlaceholderExpose companion placeholders

Artifacts1

• Pet StoragePersist companion data

Manifests1

• Pet DefinitionConfigure a companion pet

Troubleshooting

Pets are lost after a restart. No Pet Storage artifact exists, or the menu action has no storage. The log shows "No pet_storage entry found. Companion data will not persist until one is created."

The token says the menu is full. Every slot of the menu is taken or locked for that player. Add slots in slots, or grant the permission of a locked slot. The message is the token's noSlotMessage.

"Ce familier est déjà présent dans ton menu." A player can own one copy of each pet. They cannot use a second token for the same definition.

A GROUND or FLY pet never appears. The log says "Unable to summon ground pet". Set npc on the definition, or give at least one skin an npc whose criteria match the player. Check that the entity definition entry exists.

The pet does not level up. The pet needs a requirement for the next level, either a levels entry or a formula. A formula that cannot be evaluated is treated as no requirement. Check it only uses numbers, {level}, + - * / and parentheses.

/pets prints nothing. Use /pets open. All subcommands need typewriter.pets plus their own permission, and these permissions are not granted by default.

A skin shows as locked ("???"). Its criteria do not match yet. Test the facts or quests it depends on.

Related extensions

• GUI — menu engine behind the companion menu and the pets_button: items.
• UiCore — can read the player's companions for HUD and menu pages.