Filter

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

Code: guthscp.filter

Realm: 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), therefore giving to the player an invalid reference which won't resolves until a future synchronization.

---

Events

event_added( Entity entity )

Emitted when the entity get added into the container.

---

event_removed( Entity entity )

Emitted when the entity get removed from the container.

---

Methods

guthscp.filter new( string id, string name = id )

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.

---

bool add( Entity entity )

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

---

bool add_id( int id )

Adds the entity id into the container, returns whenever the id has been added.

---

bool remove( Entity entity )

Tries to remove the entity from the container, returns whenever the entity has been removed. Internally call FILTER:remove_id.

---

bool remove_id( int id )

Removes the entity id from the container, returns whenever the id has been removed.

---

void clear()

Clears the container.

---

void save() const

Saves the data to file. Method FILTER:serialize must be implemented.

---

void load()

Loads the data from file. Method FILTER:un_serialize must be implemented.

---

bool is_in( Entity entity ) const

Returns whenever the entity is contained.

---

table[Entity] get_entities() const

Returns a new array of contained and valid entities. The array is not cached.

---

int get_count() const

Returns number of contained entities.

---

(overridable) bool filter( Entity entity ) const

Returns whenever the entity can be added to the container. The entity is assumed to be valid. By default, returns true.

---

(overridable) table serialize() const

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

---

(overridable) void un_serialize( table data )

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

---

(overridable) string get_save_file_path() const

Returns the file path for saving and loading data for this filter.

---

void sync( Player receiver = nil )

Synchronizes the filter's content to the receiver or all clients.

---

void safe_sync( Player receiver = nil )

Delay the synchronization of the filter's content to the receiver or all clients. Internally calls FILTER:sync.

---