Behaviours

This section documents all available NPC behaviours, what they do, when to use them, and which variables (if any) they require.

Behaviours control how an NPC acts in the world, not what it says. You can combine multiple behaviours on the same NPC.

---

🧩 How Behaviours Work

Behaviours are applied using:

{
  "type": "cobblemon:apply_behaviours",
  "behaviours": ["behaviour_id"]
}

Some behaviours require variables. Those variables are added using:

{
  "type": "add_variables",
  "variables": [ ... ]
}

⚠️ If a required variable is missing, the behaviour may not work or behave incorrectly.

---

🧑‍🎨 player_textured

Purpose

Applies a player skin to the NPC.

When to use

• Human NPCs

Required variables

Variable	Description
player_texture	Minecraft username whose skin will be used

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:player_textured"]
  },
  {
    "type": "add_variables",
    "variables": [
      {
        "variableName": "player_texture",
        "category": "cobblemon.entity.variable.category.appearance",
        "type": "TEXT",
        "defaultValue": "Korinesmans"
      }
    ]
  }
]

---

📏 npc_scale_configuration

Purpose

Changes the visual size and hitbox dimensions of the NPC.

When to use

• Giant or tiny NPCs

• Custom-sized bosses

• Non-standard models

Required variables

Variable	Description
npc_render_scale	Visual scale multiplier
npc_box_width	Hitbox width
npc_box_height	Hitbox height

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:npc_scale_configuration"]
  },
  {
    "type": "add_variables",
    "variables": [
      {
        "variableName": "npc_render_scale",
        "category": "cobblemon.entity.variable.category.appearance",
        "type": "NUMBER",
        "defaultValue": "1.2"
      },
      {
        "variableName": "npc_box_width",
        "category": "cobblemon.entity.variable.category.appearance",
        "type": "NUMBER",
        "defaultValue": "0.6"
      },
      {
        "variableName": "npc_box_height",
        "category": "cobblemon.entity.variable.category.appearance",
        "type": "NUMBER",
        "defaultValue": "2.0"
      }
    ]
  }
]

---

⚔️ battle_commands

Purpose

Executes server commands when a battle ends, depending on the outcome.

When to use

• Trainers that give rewards

• Punishments on loss

• Quest logic tied to battles

Required variables

Variable	Description
player_win_command	Command executed when player wins
player_lose_command	Command executed when player loses

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:battle_commands"]
  },
  {
    "type": "add_variables",
    "variables": [
      {
        "variableName": "player_win_command",
        "category": "cobblemon.entity.variable.category.battling",
        "type": "TEXT",
        "defaultValue": "give @p minecraft:diamond 1"
      },
      {
        "variableName": "player_lose_command",
        "category": "cobblemon.entity.variable.category.battling",
        "type": "TEXT",
        "defaultValue": "give @p minecraft:coal 1"
      }
    ]
  }
]

---

🥊 battler

Purpose

Allows the NPC to enter and exit Pokémon battles.

When to use

• Trainer NPCs

• Battle-based encounters

Variables

❌ None required

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:battler"]
  }
]

---

🧠 core

Purpose

Provides essential base AI logic.

What it handles

• Orientation

• Behaviour coordination

• Internal ticking

When to use

✅ Almost always

⚠️ Removing this may break other behaviours.

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:core"]
  }
]

---

🚶 wanders

Purpose

Allows the NPC to walk randomly on land.

When to use

• Ambient NPCs

• Villagers or wildlife

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:wanders"]
  }
]

---

🌊 wanders_water

Purpose

Random movement while in water.

When to use

• Aquatic NPCs

• Water-based creatures

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:wanders_water"]
  }
]

---

👀 looks_at_players

Purpose

Makes the NPC look at nearby players.

When to use

• Dialogue NPCs

• Immersive characters

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:looks_at_players"]
  }
]

---

🚫🌊 avoids_water

Purpose

Prevents the NPC from entering water and forces it out if it falls in.

When to use

• Land-only NPCs

• Important story characters

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:avoids_water"]
  }
]

---

🛟 floats

Purpose

Allows the NPC to float on water instead of sinking.

When to use

• Floating entities

• Water-safe NPCs

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:floats"]
  }
]

---

😱 panics

Purpose

Causes the NPC to run away when damaged.

When to use

• Passive creatures

• Scared civilians

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:panics"]
  }
]

---

📍 stationary

Purpose

Keeps the NPC tied to a fixed position.

When to use

• Guards

• Quest NPCs

• Dialogue NPCs that must not move

Required variables

Variable	Description
home_x	Home X coordinate
home_y	Home Y coordinate
home_z	Home Z coordinate
home_radius	Allowed movement radius

Example

"behaviours": [
  {
    "type": "cobblemon:apply_behaviours",
    "behaviours": ["cobblemon:stationary"]
  },
  {
    "type": "add_variables",
    "variables": [
      {
        "variableName": "home_x",
        "category": "cobblemon.entity.variable.category.movement",
        "type": "NUMBER",
        "defaultValue": "-5701"
      },
      {
        "variableName": "home_y",
        "category": "cobblemon.entity.variable.category.movement",
        "type": "NUMBER",
        "defaultValue": "110"
      },
      {
        "variableName": "home_z",
        "category": "cobblemon.entity.variable.category.movement",
        "type": "NUMBER",
        "defaultValue": "-1255"
      },
      {
        "variableName": "home_radius",
        "category": "cobblemon.entity.variable.category.movement",
        "type": "NUMBER",
        "defaultValue": "3"
      }
    ]
  }
]

---

🧠 Behaviour Summary

Behaviour	Requires Variables	Main Use
player_textured	✅	Player skins
npc_scale_configuration	✅	Size & hitbox
battle_commands	✅	Battle rewards
battler	❌	Enable battles
core	❌	Base logic
wanders	❌	Random walking
wanders_water	❌	Water movement
looks_at_players	❌	Immersion
avoids_water	❌	Land-only NPCs
floats	❌	Floating
panics	❌	Fear behavior
stationary	✅	Fixed position