Skip to content

Companion System (Pets)

The Companion system provides floating cosmetic pets that follow players around.

Overview

  • Main file: companions-rework.sk (798 lines)
  • Technology: Armor stands with custom heads
  • Features: Multiple pets, customization, levels

How It Works

Companions are invisible armor stands with custom player heads that: 1. Float beside the player 2. Follow player movement 3. Display custom names (optional)

graph LR
    Player --> Apply[Apply Pet]
    Apply --> Spawn[Spawn Armor Stand]
    Spawn --> Loop[Follow Loop]
    Loop -->|every tick| Position[Update Position]
    Position --> Loop

Commands

/pet              # Open pet menu
/pets             # Open pet menu (alias)
/companion        # Open pet menu (alias)

Pet Data Storage

YAML Configuration

Pet definitions in plugins/Companions/companions.yml: 

companions:
  cat:
    displayName: "Cat"
    headTexture: "<base64>"
    chestplate: LEATHER_CHESTPLATE
    leatherColor:
      red: 255
      green: 200
      blue: 100

Player Data

# In data.yml
companions:
  <uuid>:
    active: "cat"
    owned:
      cat:
        customName: "Whiskers"
        nameVisible: true
        isLeft: false  # Position side
        level: 2
    coins: 50  # Companion coins currency

Key Functions

Apply Pet

function applyPet(p: offline player, c: text):
    # Set companion YAML data
    # Calculate position (left or right of player)
    # Create NBT for armor stand
    # Spawn invisible armor stand
    # Set head texture
    # Start follow loop

Follow Loop

# Inside applyPet every 1 tick:
    # Calculate offset from player
    # Apply bobbing animation
    # Update armor stand position
    # Check if should stop (player quit, etc.)

Get Pet Head

function getPetHead(c: text) :: item:
    # Get base64 texture from YAML
    # Create player head with NBT
    # Return head item

Customization Options

Feature Description
Custom Name Players can name their pet
Hide Name Toggle name visibility
Position Left or right side
Level Pet levels (cosmetic)

Cleanup

Stray armor stands are cleaned up: - On player quit - Every 15 minutes (scheduled task) - Manual admin cleanup

Troubleshooting

Pet not following

  1. Check if pet is applied: metadata tag "appliedPet" of player
  2. Verify player is online
  3. Check for follow loop errors

Duplicate pets

  1. Run cleanup: scheduled task or relog
  2. Check for spawning issues in console

Pet not showing

  1. Verify head texture is valid
  2. Check YAML syntax
  3. Verify companion is owned by player