====== Pet Mechanic - Code References ======

**Pet Mechanic** allows the hero to tame and command mobs as permanent companions that fight alongside them.

===== Entity Type =====
Game Mechanic (AI/Pet System)

===== Java Classes =====
**Pet Management**: [[https://github.com/NYRDS/remixed-dungeon/blob/master/RemixedDungeon/src/main/java/com/nyrds/pixeldungeon/mechanics/PetInventoryManager.java|PetInventoryManager.java]]
  * Package: `com.nyrds.pixeldungeon.mechanics`
  * Methods:
    * `hasPets(Hero hero)` - Check if hero has pets
    * `openPetInventoryFromToolbar(Hero hero)` - Open pet inventory UI
    * `giveItemToPet(Hero hero, Mob pet, Item item)` - Transfer item to pet's backpack
    * `takeItemFromPet(Hero hero, Mob pet, Item item)` - Take item from pet's backpack

**Pet Base Class**: [[https://github.com/NYRDS/remixed-dungeon/blob/master/RemixedDungeon/src/main/java/com/watabou/pixeldungeon/actors/mobs/Mob.java|Mob.java]] (pet functionality)
  * Mobs become pets via static `Mob.makePet(Mob pet, Char owner)` or instance `mob.makePet(Char owner)`
  * Pet state tracked via `setOwnerId(ownerId)` on the mob; pet fraction follows the owner's fraction

**Mob Pet Methods**: [[https://github.com/NYRDS/remixed-dungeon/blob/master/RemixedDungeon/src/main/java/com/watabou/pixeldungeon/actors/mobs/Mob.java|Mob.java]]
  * `makePet(Char owner)` / `Mob.makePet(Mob, Char)` - Convert mob to pet
  * `isPet()` - Check if mob is a pet
  * `canBePet()` - Check if mob species can be tamed

**Hero Pet List**: [[https://github.com/NYRDS/remixed-dungeon/blob/master/RemixedDungeon/src/main/java/com/watabou/pixeldungeon/actors/Char.java|Char.java]]
  * `getPets_l()` - Get list of hero's pets (Lua interface, defined on `Char`)

**AI States**: [[https://github.com/NYRDS/remixed-dungeon/blob/master/RemixedDungeon/src/main/java/com/nyrds/pixeldungeon/ai/MobAi.java|MobAi.java]]
  * `ControlledAi` - Direct player control state
  * `Hunting` - Pet follows and attacks enemies
  * `Wandering` - Idle behavior near hero
  * `Fleeing` - Low health retreat

**UI**: [[https://github.com/NYRDS/remixed-dungeon/blob/master/RemixedDungeon/src/main/java/com/watabou/pixeldungeon/ui/Toolbar.java|Toolbar.java]]
  * Pet inventory button (index 10, tinted)
  * Opens `WndPetInventory` window

**Windows**: [[https://github.com/NYRDS/remixed-dungeon/blob/master/RemixedDungeon/src/main/java/com/nyrds/pixeldungeon/windows/WndPetItem.java|WndPetItem.java]]
  * Pet inventory management UI
  * Related windows: `WndPetBag`, `WndPetSelect`, `WndPetQuantity`, `WndPetInventoryOptions`

**Actions**: [[https://github.com/NYRDS/remixed-dungeon/blob/master/RemixedDungeon/src/main/java/com/nyrds/pixeldungeon/mechanics/CommonActions.java|CommonActions.java]]
  * `AC_GIVE_TO_PET` - Give item to pet
  * `AC_TAKE_FROM_PET` - Take item from pet

===== JSON Configuration =====
**Mob Pet Property**: In `mobsDesc/<Mob>.json`
<code json>
{
  "canBePet": true,
  "name": "Rat_Name",
  ...
}
</code>

Mobs with `"canBePet": true` (e.g. Bee, DeepSnail, MazeShadow, ShamanElder):
  * Boss mobs: `false` (e.g. BeeHive)
  * Hostile NPCs: `false`

===== String Resources =====
English (values/strings_all.xml):
<code xml>
<string name="PetInventory_Title">Pet Inventory</string>
<string name="PetInventory_ViewManage">View and manage your pet's equipment</string>
<string name="PetInventory_GiveToPet">Give to Pet</string>
<string name="PetInventory_TakeFromPet">Take from Pet</string>
<string name="PetInventory_GaveItem">You gave %s to your pet</string>
<string name="PetInventory_TookItem">You took %s from your pet</string>
<string name="PetInventory_GiveN">Give %d</string>
<string name="PetInventory_TakeN">Take %d</string>
<string name="PetInventory_PetBackpackFull">Pet's backpack is full</string>
<string name="PetInventory_HeroBackpackFull">Your backpack is full</string>
<string name="PetInventory_TooFar">Pet is too far away</string>
<string name="PetInventory_CantGiveEquipped">Can't give equipped items</string>
<string name="Mob_Cannot_Be_Pet">This creature cannot be tamed</string>
<string name="PetInventory_ACTakeFromPet">Take from Pet</string>
<string name="PetInventory_ACGiveToPet">Give to Pet</string>
</code>

Russian (values-ru/strings_all.xml):
<code xml>
<string name="PetInventory_Title">Инвентарь питомца</string>
<string name="PetInventory_ViewManage">Просмотр и управление экипировкой питомца</string>
<string name="PetInventory_GiveToPet">Отдать питомцу</string>
<string name="PetInventory_TakeFromPet">Забрать у питомца</string>
<string name="PetInventory_GaveItem">Вы отдали %s питомцу</string>
<string name="PetInventory_TookItem">Вы забрали %s у питомца</string>
<string name="PetInventory_GiveN">Отдать %d</string>
<string name="PetInventory_TakeN">Забрать %d</string>
<string name="PetInventory_PetBackpackFull">Рюкзак питомца полон</string>
<string name="PetInventory_HeroBackpackFull">Ваш рюкзак полон</string>
<string name="PetInventory_TooFar">Питомец слишком далеко</string>
<string name="PetInventory_CantGiveEquipped">Нельзя отдать экипированные предметы</string>
<string name="Mob_Cannot_Be_Pet">Это существо нельзя приручить</string>
<string name="PetInventory_ACTakeFromPet">Забрать у питомца</string>
<string name="PetInventory_ACGiveToPet">Отдать питомцу</string>
</code>

===== Lua Scripts =====
  * **Pet AI**: `scripts/lib/commonClasses.lua` - `RPD.Mob:makePet(target, caster)`
  * **Possess Spell**: `scripts/spells/Possess.lua` - Temporary pet control
  * **Raise Dead**: `scripts/spells/RaiseDead.lua` - Undead pet creation
  * **Exhumation**: `scripts/spells/Exhumation.lua` - Wraith pet creation
  * **Summon Beast**: `scripts/spells/SummonBeast.lua` - Temporary summons

===== Related mr Entities =====
  * [[mr:mob|Mob System]] - Base mob class with pet support
  * [[mr:rat_mob|Rat Mob]] - Tameable
  * [[mr:snail_mob|Snail Mob]] - Tameable
  * [[mr:crab_mob|Crab Mob]] - Tameable
  * [[mr:bat_mob|Bat Mob]] - Tameable
  * [[mr:possess_spell|Possess Spell]] - Temporary control
  * [[mr:raise_dead_spell|Raise Dead Spell]] - Undead pets
  * [[mr:summon_beast_spell|Summon Beast Spell]] - Temporary summons

===== Game Mechanics =====
  * **Taming Methods**:
    * Possess Spell (temporary)
    * Summon Beast Spell (temporary)
    * Raise Dead (undead pets)
    * Exhumation (Wraith pets)
    * Certain items/artifacts (e.g. Carcass, HeartOfDarkness, ChaosStaff)
  * **Pet Capabilities**:
    * Follow hero automatically
    * Attack enemies in range
    * Have own inventory (accessible via toolbar)
    * Gain experience and level up
    * Can be healed with potions/spells
  * **Pet Rules**:
    * Only mobs with `canBePet: true` in JSON can be tamed
    * Pets persist between levels (`followOnLevelChanged` returns true for hero-owned pets)
  * **Pet Inventory**:
    * Accessible via toolbar button (pet icon)
    * Separate from hero inventory
    * Items are transferred to/from the pet's backpack

===== Code Fragments =====
Taming a mob (actual implementation in Mob.java):
<code java>
public static Mob makePet(@NotNull Mob pet, int ownerId) {
    var owner = CharsList.getById(ownerId);
    if(owner.fraction()==Fraction.HEROES) {
        pet.expForKill = 0;
    }
    if (pet.canBePet()) {
        pet.setFraction(owner.fraction());
        pet.setOwnerId(ownerId);
    }
    return pet;
}
</code>

Lua pet creation:
<code lua>
-- Possess spell
RPD.Mob:makePet(target, caster)

-- Raise Dead
local mob = RPD.MobFactory:mobByName(latestDeadMob.class)
RPD.Mob:makePet(mob, chr)
level:spawnMob(mob)
</code>

{{tag> rpd mechanics pets ai companions}}