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

# Players Filter

**Code:** [_guthscp.players\_filter_](https://github.com/Guthen/guthscpbase/blob/master/lua/guthscp/keter/core/shared/filters/players_filter.lua)

**Extends:** [_guthscp.filter_]()

**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

Players filters are containers useful for caching a list of players with pre-determined conditions.

Similarly to filters, 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.

By itself, a filter won't do anything unless you told him so. Therefore, you should either use `FILTER:listen_<...>` methods or manually hook into game events and use `FILTER:add` and `FILTER:remove` methods.

***

## Methods

{% hint style="info" %}
Inherited methods will NOT appear here, please read the parent's documentation.
{% endhint %}

<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`** `listen_disconnect()`

&#x20;   Makes the filter to automatically clean-up disconnected players.

***

<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`** `listen_weapon_users( string weapon_class )`

&#x20;   Makes the filter to automatically add players who are using a specific weapon class and to remove those who are not.

***

## Example

A common use case is to gather a list of players using a certain SCP weapon for later use. Code from [_guthscp173_](https://github.com/Guthen/guthscp173/blob/update-to-guthscpbase-remaster/lua/guthscp/modules/guthscp173/shared.lua):

<pre class="language-lua"><code class="lang-lua"><strong>guthscp173.filter = <a data-footnote-ref href="#user-content-fn-1">guthscp.players_filter:new( "guthscp173" )</a>
</strong>if SERVER then
	guthscp173.filter:listen_disconnect()
	guthscp173.filter:listen_weapon_users( "guthscp_173" )  --  being SCP-173 just mean a player having the weapon 

	<a data-footnote-ref href="#user-content-fn-2">guthscp173.filter.event_removed:add_listener</a>( "guthscp173:unfreeze", function( ply )
		ply:SetNWBool( "guthscp173:looked", false )
	end )
end
</code></pre>

[^1]: Creates an instance of a Players Filter

[^2]: Subscribes to the "remove event", called when a player is being removed from the filter
