> For the complete documentation index, see [llms.txt](https://docs.nursultan.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nursultan.fun/scripting-api-ru/igrovye-dannye/sushnosti-i-filtry.md).

# Сущности и фильтры

Сущность — это всё, что живёт в мире: игроки, мобы, лодки, выпавшие предметы, стрелы. Берутся они из [мира](/scripting-api-ru/igrovye-dannye/mir-i-bloki.md), из [луча](/scripting-api-ru/igrovye-dannye/luchi-i-pricel.md) или из события.

## Что можно спросить у любой сущности

```kotlin
entity.id()              // числовой id в этом мире
entity.uuid()
entity.name()
entity.typeId()          // "minecraft:zombie"

entity.position()
entity.renderPosition()  // сглаженная, для рисования
entity.previousPosition()
entity.box()
entity.width()  entity.height()

entity.rotation()
entity.yaw()  entity.pitch()
entity.velocity()

entity.alive()
entity.onGround()
entity.sneaking()
entity.sprinting()
entity.invisible()
entity.glowing()
entity.onFire()
entity.inWater()
entity.pose()
entity.fallDistanceBlocks()

entity.distanceTo(other)
entity.distanceTo(point)
```

## Кто это

```kotlin
entity.isSelf()          // это я
entity.isPlayer()
entity.isLiving()
entity.isBot()           // похоже на бота
entity.isFriend()        // в списке друзей
entity.isParty()         // в моей пати
entity.isAlly()          // друг или пати
```

`isAlly()` — то, что обычно и нужно, чтобы не бить своих.

## Живые сущности

Если сущность живая, у неё есть здоровье, эффекты и предметы. Приведение возвращает `null`, если это, например, лодка:

```kotlin
val living = entity.asLiving() ?: return

living.health()
living.maxHealth()
living.absorption()
living.armorPoints()
living.bypassedHealth()   // здоровье с учётом брони и резистов
living.dead()
living.hurtTicks()

living.blocking()         // держит щит
living.usingItem()
living.isNaked()          // без брони

living.headYaw()
living.bodyYaw()

living.hasEffect("speed")
living.effect("speed")?.amplifier()
living.effects()

living.mainHandItem()
living.offHandItem()
living.armorItem(ArmorSlot.HELMET)
living.armorItems()
```

Для игроков есть отдельное приведение — оно даёт пинг и режим игры:

```kotlin
val target = entity.asPlayer() ?: return
target.pingMs()
target.gameMode()
```

## Фильтры

`filters` даёт возможность удобно отбирать сущности по нужным признакам, не расписывая условия руками:

| Фильтр         | Что отбирает              |
| -------------- | ------------------------- |
| `alive()`      | живые                     |
| `self()`       | тебя                      |
| `player()`     | игроков                   |
| `mob()`        | мобов                     |
| `monster()`    | враждебных                |
| `animal()`     | животных                  |
| `villager()`   | жителей                   |
| `item()`       | выпавшие предметы         |
| `friend()`     | друзей                    |
| `party()`      | пати                      |
| `ally()`       | друзей и пати             |
| `bot()`        | ботов                     |
| `attackable()` | всё, что имеет смысл бить |

Каждый фильтр — обычный `Predicate<Entity>`, так что их можно складывать:

```kotlin
val targets = world.entitiesNear(
    player.position(), 6.0,
    filters.player().and(filters.ally().negate())
)
```

И смешивать со своими условиями:

```kotlin
val weak = filters.attackable().and { it.asLiving()?.health() ?: 0f < 8f }

val victim = world.nearestEntity(player.position(), 5.0, weak)
```

## Появление и исчезновение

```kotlin
on<EntitySpawnEvent> { e ->
    if (filters.monster().test(e.entity())) {
        notify("рядом моб", NotifyKind.WARN)
    }
}

on<EntityRemoveEvent> { e ->
    chat.print(e.entity().name() + " пропал")
}
```

## Осторожно с хранением

Сущности приходят и уходят. Если держишь ссылку между тиками, проверяй, что она ещё жива:

```kotlin
var target: Entity? = null

on<ClientTickEvent> {
    val current = target
    if (current == null || !current.alive()) {
        target = world.nearestEntity(player.position(), 6.0, filters.attackable())
        return@on
    }
}
```

Надёжнее хранить `id()` и брать сущность заново через `world.entityById(...)`.