---
description: Manage and synchronize a list of entities matching pre-defined conditions
---

# Filter

**Code:** [_guthscp.filter_](https://github.com/Guthen/guthscpbase/blob/master/lua/guthscp/keter/core/shared/filters/filter.lua)

**Realm:** <img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> Shared

***

## Description

Filters are containers useful for caching a list of entities with pre-determined conditions.

They must be instantiated on both client and server sides. As filters are automatically synchronized after a modification, only the server needs to manage their content. The client should only receive data from the server and should not alters the content by itself.

Internally, the container is a set data structure containing the entity indexes, providing fast checking and unique elements. The filter uses entity indexes instead of _Entity_ references for safer client network. It fixes the case where you reference an entity which was not sent to a player by the engine/game (probably caused by [PVS](https://developer.valvesoftware.com/wiki/PVS)), therefore giving to the player an invalid reference which won't resolves until a future synchronization.

***

## Events

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> `event_added( Entity entity )`

&#x20;   Emitted when the `entity` get added into the container.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> `event_removed( Entity entity )`

&#x20;   Emitted when the `entity` get removed from the container.

***

## Methods

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`guthscp.filter`** `new( string id, string name = id )`

&#x20;   Instantiates a filter object with given identifier. The `name` parameter is only used by the _Map Entities Filter Tool_. Must be used both sides (a.k.a. shared) for synchronization to take effect.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`bool`** `add( Entity entity )`

&#x20;   Tries to add the `entity` into the container, returns whenever the `entity` passed the filter and has been added. Internally call `FILTER:add_id`.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`bool`** `add_id( int id )`

&#x20;   Adds the entity `id` into the container, returns whenever the `id` has been added.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`bool`** `remove( Entity entity )`

&#x20;   Tries to remove the `entity` from the container, returns whenever the `entity` has been removed. Internally call `FILTER:remove_id`.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`bool`** `remove_id( int id )`

&#x20;   Removes the entity `id` from the container, returns whenever the `id` has been removed.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`void`** `clear()`

&#x20;   Clears the container.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`void`** `save()` `const`

&#x20;   Saves the data to file. Method `FILTER:serialize` must be implemented.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`void`** `load()`

&#x20;   Loads the data from file. Method `FILTER:un_serialize` must be implemented.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`bool`** `is_in( Entity entity )` `const`

&#x20;   Returns whenever the `entity` is contained.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`table[Entity]`** `get_entities()` `const`

&#x20;   Returns a new array of contained and valid entities. The array is not cached.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> **`int`** `get_count()` `const`

&#x20;   Returns number of contained entities.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> `(overridable)` **`bool`** `filter( Entity entity )` `const`

&#x20;   Returns whenever the `entity` can be added to the container. The `entity` is assumed to be valid. By default, returns `true`.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> `(overridable)` **`table`** `serialize()` `const`

&#x20;   Returns a table containing all the data to serialize. Called by `FILTER:save`. By default, returns `nil`.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> `(overridable)` **`void`** `un_serialize( table data )`

&#x20;   Re-creates the container from the serialized `data` which must be structured by `FILTER:serialize`. Called by `FILTER:load`. By default, does nothing.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> `(overridable)` **`string`** `get_save_file_path()` `const`

&#x20;   Returns the file path for saving and loading data for this filter.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2F3vKTySEXqcFnfu1fcEAX%2Frealm%20server.png?alt=media" alt="" data-size="line"> **`void`** `sync( Player receiver = nil )`

&#x20;   Synchronizes the filter's content to the `receiver` or all clients.

***

<img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2F3vKTySEXqcFnfu1fcEAX%2Frealm%20server.png?alt=media" alt="" data-size="line"> **`void`** `safe_sync( Player receiver = nil )`

&#x20;   Delay the synchronization of the filter's content to the `receiver` or all clients. Internally calls `FILTER:sync`.

***
