config.yml

Main Settings

These are the global plugin settings.

enabled: true
debug-messages: false
metrics: true

Setting	Description
enabled	Enables or disables the entire plugin.
debug-messages	Enables verbose debug output in the console. Only enable when troubleshooting.
metrics	Enables bStats metrics collection.

---

Event Monitoring

Configure which events the plugin listens to and how chunk inspections work.

events:
  spawn:
    creature: true
    vehicle: true
    entity: true
  inspections:
    enabled: true
    frequency: 60

Spawn Event Watching

Setting	Description
events.spawn.creature	Listen to CreatureSpawnEvent.
events.spawn.vehicle	Listen to VehicleCreateEvent.
events.spawn.entity	Listen to EntitySpawnEvent. Catches entities not handled by creature spawn.

Chunk Inspections

Setting	Description
events.inspections.enabled	Periodically re-check loaded chunks.
events.inspections.frequency	How often (in seconds) chunks are rechecked.

---

Entity Management

Entity Groups

You can define your own entity groups.

Use entities from https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/EntityType.html

You can also use the in-game command /cslsearch to view available entity types.

Example:

entities:
  entity-groups:
    ANIMALS:
      - COW
      - SHEEP
      - PIG
      - CHICKEN
    MONSTERS:
      - ZOMBIE
      - SKELETON
      - CREEPER

You may freely add or remove entity types depending on your server version.

---

Entity Limits

Define maximum entities per chunk per group.

entities:
  limits:
    ANIMALS: 50
    MONSTERS: 50
    NPC: 50
    OTHER: 500

If a group is not defined in entity-groups, it will fall under OTHER.

---

Preservation Settings

entities:
  preservation:
    named-entities: true
    raid-entities: true

Setting	Description
named-entities	Prioritizes unnamed entities for removal before named ones.
raid-entities	Prevents pillagers involved in raids from being removed.

---

Removal Modes

entities:
  removal:
    mode: "enforce"

Available modes:

Mode	Description
enforce	Cleans existing violations and prevents new ones.
enforce-kill	Same as enforce, but kills entities instead of removing them.
prevent	Only prevents new violations.
remove	Instantly removes excess entities.
kill	Kills excess entities (drops + effects).

Armor Stand Options

entities:
  removal:
    armor-stand:
      drop: false
      log-warnings: true

Setting	Description
drop	Drop items from armor stands when killed.
log-warnings	Enable or disable armor stand tick warnings.

Kill Players

entities:
  removal:
    kill-players: false

If enabled, players exceeding chunk limits may be killed when using kill-based modes.

---

Ignored Entities

Entities with matching metadata or NBT tags will be ignored.

entities:
  ignore:
    metadata:
      - shopkeeper
    nbt:
      - "tag"

NBT filtering requires NBTAPI https://modrinth.com/plugin/nbtapi

---

Spawn Reasons

Define which spawn reasons should be processed.

Use reasons from https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/entity/CreatureSpawnEvent.SpawnReason.html

spawn-reasons:
  - "BREEDING"
  - "BUILD_IRONGOLEM"
  - "SPAWNER"

To disable a reason, simply remove it from the list.

Example: If you want iron golems built by players to be checked, ensure:

- "BUILD_IRONGOLEM"

is present in the list.

---

Block Restrictions

Block Groups

blocks:
  block-groups:
    basic:
      - "STONE"
      - "DIRT"
    ores:
      - "DIAMOND_BLOCK"
      - "GOLD_BLOCK"

Block names must match Bukkit Material names.

---

Block Limits

blocks:
  limits:
    SPAWNER: 10

This example limits spawners to 10 per chunk.

---

World Configuration

Control which worlds the plugin applies to.

worlds:
  mode: excluded
  list: []

Mode	Description
excluded	Plugin runs in all worlds except those listed.
included	Plugin runs only in listed worlds.

Example (only run in world):

worlds:
  mode: included
  list: ["world"]

---

Notifications

Configure player notifications when entities or blocks are blocked or removed.

notifications:
  enabled: false
  cooldown-seconds: 3
  method:
    title: true
    message: false

Setting	Description
enabled	Enable player notifications.
cooldown-seconds	Cooldown between notifications per player.
method.title	Send as title/subtitle.
method.message	Send as chat message.

---

Custom Messages

You may use color codes with &.

Available placeholders:

• {count} — Number of entities affected

• {type} — Entity or block type

• {material} — Block material

• {amount} — Maximum allowed amount

Example:

notifications:
  messages:
    entities-blocked: "&7Blocked {count} {type} from spawning in your chunk."
    entities-removed: "&7Removed {count} {type} in your chunk."
    reload-complete: "&cReloaded csl config."
    max-blocks: "&6Cannot place more &4{material}&6. Max amount per chunk &2{amount}."
    max-blocks-title: "&6Cannot place more &4{material}&6."
    max-blocks-subtitle: "&6Max amount per chunk &2{amount}."

You may remove placeholders if not needed.