docs(companionpets): document Pet Houses, fetch races and health recovery

projects/CompanionPets/docs/configuration.md

@@ -112,12 +112,29 @@ works with vanilla material selectors; those material/model combinations also
 accept provider-created eggs for compatibility. Explicit provider IDs take
 priority. Confirmation rechecks the held item before consuming it.
 
-## Shelters
+## Pet Houses
 
-Shelter placement stays global: `items.kennel` selects the consumed held item;
+Pet House placement stays global: `items.kennel` selects the consumed held item;
 `items.kennel-block` selects the actual vanilla block (`BARREL` for custom
-tokens). This places an ordinary shelter, not ItemsAdder furniture. Plant and
-block settings continue to use vanilla materials.
+tokens). Without `items.kennel-furniture`, this places a regular Pet House.
+
+For ItemsAdder furniture, configure the held item and the matching placed
+furniture ID. Only simple furniture is supported: complex furniture events do
+not expose the player needed to record ownership and enforce owner-only access.
+
+```yaml
+items:
+  kennel: "itemsadder:tfmc:pet_house"
+  kennel-furniture: "tfmc:pet_house"
+  kennel-block: BARREL
+```
+
+ItemsAdder handles normal placement, protection checks, consumption and drops.
+CompanionPets records the owner after successful placement. Right-clicking opens
+the owner's Pet House menu; other players cannot open it. Breaking the furniture
+removes its ownership record without deleting pets. Registered barrel Pet Houses
+remain usable, and vanilla-only configurations keep sneak and right-click
+placement. Plant and block settings continue to use vanilla materials.
 
 ## Learnable tricks per pet type
 
@@ -130,7 +147,7 @@ tricks: [follow, stay, speak, jump]
 ```
 
 Available IDs: `sit`, `follow`, `come`, `stay`, `speak`, `jump`, `lay`, `paw`,
-`beg`, plus IDs defined under `custom-tricks`. Names are case-insensitive and
+plus IDs defined under `custom-tricks`. Names are case-insensitive and
 duplicates are ignored. Omitting `tricks` enables all compatible base and custom
 tricks. `tricks: []` disables additional tricks; configured default tricks are
 always enabled. Unknown IDs are skipped with a warning. A malformed list
@@ -173,7 +190,9 @@ Come, preserving its progress; other Follow words retain their bindings.
 
 ### Legacy trick IDs
 
-`lay` replaces the former Rest trick (`sleep` ID) and uses the `sleep` animation.
+`lay` replaces the former Rest trick (`sleep` ID). The pet lies down awake, uses
+the `lie` pose and does not show the Sleeping label; only automatic sleep uses
+the sleep state and label.
 Legacy `sleep` entries in configuration and saved words or progress are accepted
 as `lay`; subsequent saves use `LAY`. Existing spoken words remain bound, and the
 highest progress is retained if both old and new IDs are present. Spin has been
@@ -232,3 +251,16 @@ and the model clips it needs in [Pet types and ModelEngine](models.md#animation-
 - `orders.hearing-radius` (default 12 blocks) limits which pets hear named orders.
 - `roaming.name-attention-seconds` (default 10 seconds) sets how long a called
   pet waits after arriving.
+- `care.health-regen-per-minute` (default 20) sets natural health recovery; see
+  the [gameplay guide](gameplay.md#care).
+
+### Relaxed care preset
+
+For a server where pets need less frequent care, the optional
+[relaxed care preset](https://github.com/TF-Minecraft/CompanionPets/blob/main/config-presets/relaxed-care.yml)
+records the values used on TF Dev. It is a partial preset: copy its values into
+the matching sections of your existing config and keep your pet types, models
+and item selectors. Set each existing food entry's `hunger` to 45, as the preset
+indicates. With these settings, a fully cared-for pet walking near its owner for
+four hours keeps about 62 hunger, 75 mood, 62 energy, 80 cleanliness and full
+health. Its belly-up chance is 25%.

projects/CompanionPets/docs/gameplay.md

@@ -6,11 +6,11 @@ CompanionPets keeps one record per pet: name, sex, personality, needs, bond,
 tricks, and a rolled favourite toy. The Minecraft entity is only the body that
 is currently in the world.
 
-## Hatching and shelters
+## Hatching and Pet Houses
 
 - Use a configured egg, name the pet in chat, and confirm. The egg is spent
   only after the name is confirmed and there is room in the outside quota.
-- Sneak and right-click with a barrel to place a shelter. Right-click it to
+- Sneak and right-click with a barrel to place a Pet House. Right-click it to
   open the list. Click a pet to open its sheet, the same one as
   sneak-right-clicking it in the world. From the sheet you bring it out, call
   it, store it, let it go, or look up the tricks it has learned.
@@ -26,15 +26,28 @@ spoken pet orders remain roleplay chat.
   it when it is fine. If the owner is far away or offline, it whines that it
   misses them.
 - Food, a brush, and medicine act immediately. Anyone nearby can feed, clean,
-  and heal. Play and tricks belong to the owner. Food past a full stomach makes
+  and heal. Playing directly with a pet and tricks belong to the owner; thrown
+  toys can attract anyone's pets. Food past a full stomach makes
   the pet feel worse. A hit makes it yelp and flinch.
 - Pets only sit through the trained Sit trick. A worn-out pet lies down on its
   own when exhausted, and the learned Lay trick puts it to rest sooner.
 
-Needs stay still in the shelter and while the owner is offline. Outside, they
+Needs stay still in the Pet House and while the owner is offline. Outside, they
 fall at the normal rate when the owner is nearby and at the away rate when the
 owner is online but far.
 
+Missing health regenerates naturally, including when the pet has no illness and
+when health is zero. Recovery needs hunger and cleanliness of at least 25, and
+energy of at least 25 or a resting pet. Low mood does not block recovery or drain
+the health of an otherwise cared-for pet. The default rate is 20 health points
+per minute (`care.health-regen-per-minute`); care in the Pet House or while the
+owner is offline stays frozen. Feeding and brushing also restore health equal to
+25% of the hunger or cleanliness points actually restored, capped at 100.
+Overfeeding still hurts, and brushing an already clean pet grants no extra
+health. Medicine gives an immediate boost (`care.medicine-health-bump`) but is
+not needed for regeneration. Sick or weakened pets resume play once fully
+recovered; healthy pets with missing health can play once health is above zero.
+
 Sitting, lying from weakness or exhaustion, and sleeping all recover energy at
 the `care.sleep-minutes-to-full` rate, without idle energy loss. Away recovery
 uses the same away rate; frozen presence pauses it. Standing still with Stay
@@ -54,10 +67,16 @@ energy; an explicit Lay order continues until another order changes it.
   words on the Tricks page. Say `follow` while looking or `<name> follow`.
   Come is a separate trick; saved Come words and progress stay with Come.
   Existing custom word bindings are never overwritten.
-- Sit, Stay (standing) and Lay (sleeping) remain in place until following is
-  resumed, and survive restarts. Lay stays asleep even at full energy. Automatic
+- Sit, Stay (standing) and Lay (lying awake) remain in place until following is
+  resumed, and survive restarts. Lay remains in place at full energy. Automatic
   exhaustion sleep can still end when recovered. Needs and illness can prevent a
-  pet from moving even after release.
+  pet from moving even after release. Sitting and lying pets can look at nearby
+  players and animals without walking.
+- In water, land pets float and seek a nearby dry bank, even when hungry,
+  weakened, sitting or sleeping, and resume their saved order on land. This does
+  not apply to aquatic bodies such as fish, axolotls, tadpoles or turtles.
+  Fetching, calls and active following keep their destinations while swimming
+  rather than turning back toward the nearest bank.
 
 Follow is continuous following. Come gets the pet up, walks to the owner's
 current position and restores its earlier Sit, Stay or Lay posture on arrival.
@@ -71,7 +90,8 @@ current position. Sit, Stay and Lay cancel the call and clear both pathfinding
 and native travel inputs immediately, preserving vertical physics. Their holds
 also apply during model animations, so a posture cannot slide along an old
 movement route. Stay uses the standing idle pose, independently of stale
-vanilla sitting flags. Native entity teleports are cancelled while a pet has a
+vanilla sitting flags. Native entity teleports are cancelled while a pet is fetching, returning from a
+lost fetch race, or has a
 hold order, including the tameable mob's built-in teleport to its owner. Follow
 and temporary Come movement remain permitted; an explicit profile Call switches
 to Follow before teleporting.
@@ -81,8 +101,8 @@ the [configuration guide](configuration.md#learnable-tricks-per-pet-type).
 
 ## Play and social behaviour
 
-- Right-click the air with a listed toy to throw it. The summoned pet fetches
-  that item and drops it in front of the owner.
+- Right-click the air with a listed toy to throw it, even if nearby pets are
+  unwell or no pets are nearby. See [Fetch races](#fetch-races).
 - Say a following pet's exact name in chat to call it close. It then waits
   quietly for `roaming.name-attention-seconds` (10 seconds), counted after
   arrival. Calling a pet that is already sitting, staying or sleeping does not
@@ -98,6 +118,24 @@ the [configuration guide](configuration.md#learnable-tricks-per-pet-type).
   vanilla species keeps its own hunting and combat behaviour. A vanilla animal
   targeting a player can also be calmed with repeated right-clicks.
 
+## Fetch races
+
+All nearby, available pets that accept a thrown toy can chase it, regardless of
+ownership. Sick, weakened, hungry, exhausted, sleeping or training pets stay out,
+and only pets with the Follow order join; pets ordered to Sit, Stay or Lay stay
+in place. Every participant navigates to the shared toy on its own. The first pet
+to reach it collects it and returns it to the player who threw it; the others run
+back to their own owners without teleporting, and their return continues after
+the winner delivers the toy.
+
+Each pet keeps the same speed for chasing and returning, including when it loses
+the race or swims. Fetch movement is 30% faster than normal movement; bond,
+cleanliness, illness and favourite-toy differences still apply between pets.
+Each later throw gives chasing pets a 35% chance to switch targets; pets already
+carrying a toy finish their return. Each throw is a separate physical toy.
+Unclaimed toys can be picked up normally, and ground toys become pickable after
+a minute if no pet can reach them.
+
 ## Belly rub moment
 
 Owner petting with an empty hand can trigger `lie_back` → `belly_up` → `get_up`
@@ -116,12 +154,12 @@ order. Damage, water, orders, illness, leaving or storage interrupt the moment.
 ## Menus
 
 Trick menus show learned tricks, then tricks in practice, then unknown tricks.
-Within each group the order is Follow, Come, Sit, Stay, Lay, Paw, Speak, Beg,
-Jump, followed by custom tricks in configuration order. Trick inventories have
+Within each group the order is Follow, Come, Sit, Stay, Lay, Paw, Speak, Jump, followed by custom tricks in configuration order. Trick inventories have
 three rows, with 18 entries per page from slot 0. All nine slots in the third
 row are reserved for navigation; the nineteenth trick starts on the next page.
 Follow is available as a learned trick rather than a separate profile button.
-The Tricks button occupies the middle of the profile's bottom row. Sex uses
+Direct pet profiles centre Call, Tricks, Store and Release across the bottom row;
+a stored pet shows an inactive storage icon in the same position. Sex uses
 white dye for both sexes, with neutral text and no sex symbols.
 
 Pet lists hold 45 entries per page and fill rows from left to right, top to
@@ -133,7 +171,7 @@ on the arrow. At either boundary it plays a private denial sound and keeps the
 same inventory. Empty slots use light grey glass.
 
 Back uses an item frame in the bottom left corner and always returns to the
-parent menu, independently of the current page. Pet lists and the shelter have
+parent menu, independently of the current page. Pet lists and the Pet House have
 no Back button. Profiles opened directly from the animal have no Back button;
-profiles reached from the shelter return there, and keep that parent when
+profiles reached from the Pet House return there, and keep that parent when
 browsing their tricks.

projects/CompanionPets/docs/models.md

@@ -82,7 +82,7 @@ mapped. Set a mapping to `""` to disable an optional clip.
 | `shake` | Begins when the native wolf shake clock starts, alongside its vanilla sound. Play once. |
 | `pet` | Normal petting reaction. Does not interrupt a belly moment or another gesture. |
 | `jump`, `fall`, `swim` | Optional air/water motions. Jump plays once and holds until landing or the fall pose; swim loops. Missing clips use normal movement/idle fallbacks. |
-| `beg`, `attack`, `hurt`, `eat`, `speak`, `spawn` | Automatically used when present for their corresponding behaviour. Missing clips do not prevent the behaviour. |
+| `attack`, `hurt`, `eat`, `speak`, `spawn` | Automatically used when present for their corresponding behaviour. Missing clips do not prevent the behaviour. |
 | `lie_back`, `belly_up`, `get_up` | The optional [belly rub moment](gameplay.md#belly-rub-moment). |
 
 No clip is required. Missing `idle`/`walk` logs a warning about a potentially
@@ -96,8 +96,7 @@ Zero-length `head_tilt` is held briefly rather than vanishing. Head tracking
 belongs to the model's head bone behaviour, not a look animation.
 
 Without `jump`/`swim`, dogs and cats use `idle` in the air and `walk` in water;
-jumping and falling remain physical movements. `beg` remains a learned command
-using its vanilla sitting/attention behaviour when no `beg` clip is present.
+jumping and falling remain physical movements.
 `pet1`, `pet2`, and `despawn` have no automatic hooks. Map `pet: pet1` to use
 an older petting clip. [Custom tricks](configuration.md#custom-tricks) may also
 refer to arbitrary model clips.
@@ -113,7 +112,9 @@ with vanilla pets and their existing visual approximations.
 
 Modelled wolves emit water splash particles throughout their native shake clock,
 alongside the `shake` animation and vanilla sound. Vanilla fallback wolves
-retain their original particles.
+retain their original particles. Fetching postpones both the native and the
+modelled shake until the pet finishes the race or returns the toy. Shaking never
+holds navigation, and movement interrupts the modelled gesture.
 
 ## TFMC models
 

projects/CompanionPets/docs/saved-data.md

@@ -4,15 +4,15 @@
 
 ## Files
 
-The plugin stores pets and shelter ownership in `plugins/CompanionPets/pets.yml`.
+The plugin stores pets and Pet House ownership in `plugins/CompanionPets/pets.yml`.
 It saves immediately after important changes, every five minutes, and when the
 plugin stops. Each save writes a temporary file and replaces the main file;
 `pets.yml.bak` holds the previous valid save. All files below are in
 `plugins/CompanionPets/`.
 
 | File | Purpose |
 | --- | --- |
-| `pets.yml` | Current pets and shelter ownership. |
+| `pets.yml` | Current pets and Pet House ownership. |
 | `pets.yml.bak` | The previous valid save. Never activated automatically. |
 | `pet-deletions.log` | Durable journal of terminal deletions. |
 | `pets-recovery-required` | Marker present while the plugin runs; removed after a successful final save. |
@@ -51,5 +51,11 @@ Pets left outside retain their last position and identity across restarts. When
 their chunk's entities have loaded, the plugin reconnects to the tagged body or
 recreates it at the saved position if it is missing. Missing or unloaded bodies
 do not delete pet records; care pauses until the body is available. Actual
-deaths still remove the pet normally. Calling an outside pet from its shelter
+deaths still remove the pet normally. Calling an outside pet from its Pet House
 also loads its saved chunk and attempts to recover its body.
+
+Restarting or reconnecting does not teleport distant pets with a saved Follow
+order to their owner. They wait at their position until the owner approaches,
+asks them to follow, or calls them from the Pet House. Pets already following
+during the current session keep their usual catch-up teleport when the owner
+moves too far away.

projects/CompanionPets/docs/staff.md

@@ -11,8 +11,8 @@ root aliases. Running `/companionpets` shows help and examples.
 | `moment <affection/bark/mischief/dig/belly>` | Trigger a moment while looking at your pet; normal care and animation conditions apply. |
 | `testpet <type> [name...]` | Spawn a normal pet with every compatible trick learned. No special marker, pause state or cleanup category. |
 | `list <player> [pet name...]` | Open that player's pets or a selected pet's read-only profile. Console gets readable names. |
-| `find <player> [pet name...]` | Show shelter, current or last-known location, and missing or duplicate bodies for that player's pets, without loading chunks. |
-| `create <player> type=<type> name=<name...> [option=value ...]` | Create a new saved replacement in the owner's shelter. |
+| `find <player> [pet name...]` | Show Pet House, current or last-known location, and missing or duplicate bodies for that player's pets, without loading chunks. |
+| `create <player> type=<type> name=<name...> [option=value ...]` | Create a new saved replacement in the owner's Pet House. |
 | `egg <type/all> [online-player] [1..64]` | Give configured eggs; omit the recipient in game to receive them yourself. |
 
 ```text
@@ -34,7 +34,7 @@ inventory: select the owner using command completion.
 
 The selected pet's staff inventory shares the normal pet profile: species,
 name, sex, age, needs, bond, personality, favourite toy and learned tricks. It
-is read-only, including its trick inventory; renaming, calling, shelter and
+is read-only, including its trick inventory; renaming, calling, Pet House and
 release actions are omitted. No UUIDs or audit snapshots are required or shown
 in command help, completion or pet cards. Menu layout and navigation are
 described in the [gameplay guide](gameplay.md#menus).
@@ -57,8 +57,8 @@ male, new age, generated personality.
 
 An explicitly supplied owner UUID is still accepted for reconstruction of an
 unknown or offline player; ordinary browsing and completion use player names.
-Creation validates options before writing and checks shelter capacity. The owner
-takes the created pet out through their shelter menu.
+Creation validates options before writing and checks Pet House capacity. The owner
+takes the created pet out through their Pet House menu.
 
 ## Test pets and moments