## Public API Reference

- Main Page
- Classes
- Files

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# iCelPlLayer Struct Reference

This is the Physical Layer itself. More...

`#include <physicallayer/pl.h>`

List of all members.

## Public Member Functions

virtual void | AddEntityRemoveCallback (iCelEntityRemoveCallback *clback)=0
| This registers a callback that is called each time when an entity is removed.
virtual void | AddNewEntityCallback (iCelNewEntityCallback *clback)=0
| This registers a callback that is called each time when an entity is added.
virtual int | AddScope (csString version, int size)=0
| Add an ID scope to the physical layer.
virtual void | AttachEntity (iObject *object, iCelEntity *entity)=0
| Attach an entity to some object (usually an object from the engine).
virtual void | Cache (iBase *object)=0
| Cache an SCF object.
virtual void | CallbackEveryFrame (iCelTimerListener *listener, int where)=0
| Register this listener as one that is interested in getting an event every frame.
virtual void | CallbackOnce (iCelTimerListener *listener, csTicks delta, int where)=0
| Register this listener as one that is interested in getting an event in 'delta' milliseconds.
virtual void | CleanCache ()=0
| Clean up the cache.
virtual csPtr< iCelDataBuffer > | CreateDataBuffer (long serialnr)=0
| Create a data buffer.
virtual csPtr< iCelEntityList > | CreateEmptyEntityList ()=0
| Create an empty entity list for personal use.
virtual iCelEntity * | CreateEntity (iCelEntityTemplate *factory, const char *name,...)=0
| Create an entity from a template.
virtual iCelEntity * | CreateEntity (iCelEntityTemplate *factory, const char *name, const celEntityTemplateParams &params)=0
| Create an entity from a template.
virtual csPtr< iCelEntity > | CreateEntity (const char *entname, iCelBlLayer *bl, const char *bhname,...)=0
| Create a new physical layer entity.
virtual csPtr< iCelEntity > | CreateEntity (uint id)=0
| Create a new physical layer entity, with an id provided.
virtual csPtr< iCelEntity > | CreateEntity ()=0
| Create a new physical layer entity.
virtual csPtr< iCelEntity > | CreateEntityInScope (int scope)=0
| Create a new physical layer entity, with the ID being allocated in the given scope.
virtual iCelEntityTemplate * | CreateEntityTemplate (const char *factname)=0
| Create an entity template.
virtual iCelEntityTracker * | CreateEntityTracker (const char *name)=0
| Create an entity tracker that you can use to keep track of specific sets of entities.
virtual iCelPropertyClass * | CreatePropertyClass (iCelEntity *entity, const char *propname)=0
| Convenience function to create a property class from a registered class factory.
virtual iCelPropertyClass * | CreateTaggedPropertyClass (iCelEntity *entity, const char *propname, const char *tagname)=0
| Convenience function to create a property class with a tag from a registered class factory.
virtual const char * | FetchString (csStringID id)=0
| Find the string that corresponds with some ID.
virtual csStringID | FetchStringID (const char *str)=0
| Retreive the unique ID associated with this string or create a new ID if needed.
virtual iCelEntity * | FindAttachedEntity (iObject *object)=0
| Given an iObject, find the attached entity (if any).
virtual iCelBlLayer * | FindBehaviourLayer (const char *name) const =0
| Find a behaviour layer by name.
virtual iCelEntity * | FindEntity (const char *name)=0
| Find an entity with a given name.
virtual iCelEntityTemplate * | FindEntityTemplate (const char *factname)=0
| Find an entity template with a given name.
virtual iCelEntityTracker * | FindEntityTracker (const char *name)=0
| Find a tracker by name.
virtual csPtr< iCelEntityList > | FindNearbyEntities (iSector *sector, const csVector3 &start, const csVector3 &end, bool do_invisible=false)=0
| Find all entities that are intersected by a beam.
virtual csPtr< iCelEntityList > | FindNearbyEntities (iSector *sector, const csBox3 &box, bool do_invisible=false)=0
| Find all entities that are in a given box.
virtual csPtr< iCelEntityList > | FindNearbyEntities (iSector *sector, const csVector3 &pos, float radius, bool do_invisible=false)=0
| Find all entities that are within a certain radius of a given position.
virtual iCelPropertyClassFactory * | FindPropertyClassFactory (const char *name) const =0
| Find a property class factory by name.
virtual iCelBehaviour * | GetBehaviour (uint id)=0
| This is a convenience function to get the behaviour that belongs to the entity for a given ID.
virtual iCelBlLayer * | GetBehaviourLayer (size_t idx) const =0
| Get the specificied behaviour layer.
virtual size_t | GetBehaviourLayerCount () const =0
| Get the number of registered behaviour layers.
virtual iCelEntity * | GetEntity (uint id)=0
| Returns the entity with ID id.
virtual iCelEntity * | GetEntityByIndex (size_t idx) const =0
| Get the specific entity by index (not by ID).
virtual size_t | GetEntityCount () const =0
| Get the total number of entities.
virtual iCelEntityTemplate * | GetEntityTemplate (size_t idx) const =0
| Get a specific entity template.
virtual size_t | GetEntityTemplateCount () const =0
| Get the number of entity templates.
virtual iCelEntity * | GetHitEntity (iCamera *camera, int x, int y)=0
| Given a position on screen find the nearest entity to the camera.
virtual iCelPropertyClassFactory * | GetPropertyClassFactory (size_t idx) const =0
| Get the specificied property class factory.
virtual size_t | GetPropertyClassFactoryCount () const =0
| Get the number of registered property class factories.
virtual bool | IsEntityAddonAllowed () const =0
| Query if entity addons are allowed.
virtual bool | LoadPropertyClassFactory (const char *plugin_id)=0
| Load a property class plugin by class id if it doesn't already exist.
virtual void | RegisterBehaviourLayer (iCelBlLayer *bl)=0
| Register a behaviour layer.
virtual void | RegisterPropertyClassFactory (iCelPropertyClassFactory *pf)=0
| Register a property class factory with this physical layer.
virtual void | RemoveCallbackEveryFrame (iCelTimerListener *listener, int where)=0
| Remove all 'every-frame' callbacks to a specific listener.
virtual void | RemoveCallbackOnce (iCelTimerListener *listener, int where)=0
| Remove all 'once' callbacks to a specific listener.
virtual void | RemoveEntities ()=0
| Remove all entities.
virtual void | RemoveEntity (iCelEntity *entity)=0
| Remove an entity from the physical layer.
virtual void | RemoveEntityRemoveCallback (iCelEntityRemoveCallback *clback)=0
| Removes a registered RemoveCallback.
virtual void | RemoveEntityTemplate (iCelEntityTemplate *entfact)=0
| Remove an entity template.
virtual void | RemoveEntityTemplates ()=0
| Remove all entity templates.
virtual void | RemoveEntityTracker (iCelEntityTracker *tracker)=0
| Remove a tracker.
virtual void | RemoveNewEntityCallback (iCelNewEntityCallback *clback)=0
| Removes a registered NewCallback.
virtual void | SetEntityAddonAllowed (bool allow)=0
| Enable or disable the operations of the cel entity addon.
virtual void | UnattachEntity (iObject *object, iCelEntity *entity)=0
| Unattach an entity from some object.
virtual void | Uncache (iBase *object)=0
| Uncache an SCF object.
virtual void | UnregisterBehaviourLayer (iCelBlLayer *bl)=0
| Unregister a behaviour layer.
virtual void | UnregisterPropertyClassFactory (iCelPropertyClassFactory *pf)=0
| Unregister a property class factory.

## Detailed Description

This is the Physical Layer itself.

Definition at line 107 of file pl.h.

## Member Function Documentation

virtual void iCelPlLayer::AddEntityRemoveCallback | ( | iCelEntityRemoveCallback * | clback | ) | `[pure virtual]`

This registers a callback that is called each time when an entity is removed.

virtual void iCelPlLayer::AddNewEntityCallback | ( | iCelNewEntityCallback * | clback | ) | `[pure virtual]`

This registers a callback that is called each time when an entity is added.

virtual int iCelPlLayer::AddScope | ( | csString | version,
|  | int | size |
| ) |  |  | `[pure virtual]`

Add an ID scope to the physical layer.

Entities are created by propclasses only in the default scope so you can completely manage the ID allocation of your own scopes.

virtual void iCelPlLayer::AttachEntity | ( | iObject * | object,
|  | iCelEntity * | entity |
| ) |  |  | `[pure virtual]`

Attach an entity to some object (usually an object from the engine).

This function will check if the entity was already attached and do nothing in that case.

virtual void iCelPlLayer::Cache | ( | iBase * | object | ) | `[pure virtual]`

Cache an SCF object.

This effectively means that the PL will keep a references to this object. This function will not add the object if it is already cached so it is safe to call multiple times.

virtual void iCelPlLayer::CallbackEveryFrame | ( | iCelTimerListener * | listener,
|  | int | where |
| ) |  |  | `[pure virtual]`

Register this listener as one that is interested in getting an event every frame.

This will call TickEveryFrame().

Special note. The physical layer will keep a weak reference to the listener only. So you must keep track of your own reference. This also means that having this callback will not prevent removal of the class that implements the timer listener.

Parameters:

  | listener | is the iCelTimerListener listener.
  | where | should be CEL_EVENT_PRE, CEL_EVENT_VIEW, or CEL_EVENT_POST.

virtual void iCelPlLayer::CallbackOnce | ( | iCelTimerListener * | listener,
|  | csTicks | delta,
|  | int | where |
| ) |  |  | `[pure virtual]`

Register this listener as one that is interested in getting an event in 'delta' milliseconds.

This will call Tick().

Special note. The physical layer will keep a weak reference to the listener only. So you must keep track of your own reference. This also means that having this callback will not prevent removal of the class that implements the timer listener.

Parameters:

  | listener | is the iCelTimerListener listener.
  | delta | is the time to wait before firing in milliseconds.
  | where | should be CEL_EVENT_PRE, CEL_EVENT_VIEW, or CEL_EVENT_POST.

virtual void iCelPlLayer::CleanCache | ( |  | ) | `[pure virtual]`

Clean up the cache.

This will decrease the ref count of all objects in the cache. Possibly this will remove them unless some other object still has a reference.

virtual csPtr<iCelDataBuffer> iCelPlLayer::CreateDataBuffer | ( | long | serialnr | ) | `[pure virtual]`

Create a data buffer.

Usually property class implementations will call this to create a data buffer for their own persistent data. The use of this is not required. A property class can just as well make its own implementation of iCelDataBuffer.

virtual csPtr<iCelEntityList> iCelPlLayer::CreateEmptyEntityList | ( |  | ) | `[pure virtual]`

Create an empty entity list for personal use.

virtual iCelEntity* iCelPlLayer::CreateEntity | ( | iCelEntityTemplate * | factory,
|  | const char * | name,
|  |  | ... |
| ) |  |  | `[pure virtual]`

Create an entity from a template.

Parameters:

  | factory | is the template to create from.
  | name | is the name of the new entity. After that comes a list of parameter pairs (two strings) with the last one being equal to CEL_PARAM_END. This will construct a celEntityTemplateParams instance from these parameters and then call the other CreateEntity() variant.

virtual iCelEntity* iCelPlLayer::CreateEntity | ( | iCelEntityTemplate * | factory,
|  | const char * | name,
|  | const celEntityTemplateParams & | params |
| ) |  |  | `[pure virtual]`

Create an entity from a template.

Parameters:

  | factory | is the template to create from.
  | name | is the name of the new entity.
  | params | is a hash with parameters that will be used during entity creation.

virtual csPtr<iCelEntity> iCelPlLayer::CreateEntity | ( | const char * | entname,
|  | iCelBlLayer * | bl,
|  | const char * | bhname,
|  |  | ... |
| ) |  |  | `[pure virtual]`

Create a new physical layer entity.

The physical layer will keep a reference to this entity. You need to call RemoveEntity() to remove the entity. This version accepts a name for the entity and will also create a behaviour from the given behaviour layer. This function will use the reporter to report an error if the entity could not be created for some reason (or the behaviour failed). In that case this function returns 0. This function will also create a number of property classes for this entity. You have to end the list of property class names with CEL_PROPCLASS_END. The variable parameters should be property class strings.

Parameters:

  | entname | can be 0. In that case no name will be set.
  | bl | is the behaviour layer and can be 0.
  | bhname | can be 0.

virtual csPtr<iCelEntity> iCelPlLayer::CreateEntity | ( | uint | id | ) | `[pure virtual]`

Create a new physical layer entity, with an id provided.

You should ensure that the id provided isn't already used and that you use the hash implementation of the numreg.

virtual csPtr<iCelEntity> iCelPlLayer::CreateEntity | ( |  | ) | `[pure virtual]`

Create a new physical layer entity.

The physical layer will keep a reference to this entity. You need to call RemoveEntity() to remove the entity.

virtual csPtr<iCelEntity> iCelPlLayer::CreateEntityInScope | ( | int | scope | ) | `[pure virtual]`

Create a new physical layer entity, with the ID being allocated in the given scope.

virtual iCelEntityTemplate* iCelPlLayer::CreateEntityTemplate | ( | const char * | factname | ) | `[pure virtual]`

Create an entity template.

Parameters:

  | factname | is the name of the template.

virtual iCelEntityTracker* iCelPlLayer::CreateEntityTracker | ( | const char * | name | ) | `[pure virtual]`

Create an entity tracker that you can use to keep track of specific sets of entities.

Call RemoveEntityTracker() to remove it.

virtual iCelPropertyClass* iCelPlLayer::CreatePropertyClass | ( | iCelEntity * | entity,
|  | const char * | propname |
| ) |  |  | `[pure virtual]`

Convenience function to create a property class from a registered class factory.

Note that the reference count of the returned class is not turned up.

virtual iCelPropertyClass* iCelPlLayer::CreateTaggedPropertyClass | ( | iCelEntity * | entity,
|  | const char * | propname,
|  | const char * | tagname |
| ) |  |  | `[pure virtual]`

Convenience function to create a property class with a tag from a registered class factory.

Note that the reference count of the returned class is not turned up.

virtual const char* iCelPlLayer::FetchString | ( | csStringID | id | ) | `[pure virtual]`

Find the string that corresponds with some ID.

Returns 0 if there is no such string.

virtual csStringID iCelPlLayer::FetchStringID | ( | const char * | str | ) | `[pure virtual]`

Retreive the unique ID associated with this string or create a new ID if needed.

There are various places in CEL where this is used.

The convention on string names is usually 'cel.xxx.yyy'. With 'xxx' equal to the type of string (i.e. 'property'), and 'yyy' the name of the given type (i.e. the property name). An example: 'cel.property.startsector'.

virtual iCelEntity* iCelPlLayer::FindAttachedEntity | ( | iObject * | object | ) | `[pure virtual]`

Given an iObject, find the attached entity (if any).

virtual iCelBlLayer* iCelPlLayer::FindBehaviourLayer | ( | const char * | name | ) | const`[pure virtual]`

Find a behaviour layer by name.

virtual iCelEntity* iCelPlLayer::FindEntity | ( | const char * | name | ) | `[pure virtual]`

Find an entity with a given name.

This function will scan all entities (at maximum) the first time it is called for a given entity. Later on it will use a hash for faster finding.

virtual iCelEntityTemplate* iCelPlLayer::FindEntityTemplate | ( | const char * | factname | ) | `[pure virtual]`

Find an entity template with a given name.

virtual iCelEntityTracker* iCelPlLayer::FindEntityTracker | ( | const char * | name | ) | `[pure virtual]`

Find a tracker by name.

virtual csPtr<iCelEntityList> iCelPlLayer::FindNearbyEntities | ( | iSector * | sector,
|  | const csVector3 & | start,
|  | const csVector3 & | end,
|  | bool | do_invisible = `false` |
| ) |  |  | `[pure virtual]`

Find all entities that are intersected by a beam.

This uses the attached entities from above.

Parameters:

  | do_invisible | if true then also return invisible entities.

virtual csPtr<iCelEntityList> iCelPlLayer::FindNearbyEntities | ( | iSector * | sector,
|  | const csBox3 & | box,
|  | bool | do_invisible = `false` |
| ) |  |  | `[pure virtual]`

Find all entities that are in a given box.

This uses the attached entities from above.

Parameters:

  | do_invisible | if true then also return invisible entities.

virtual csPtr<iCelEntityList> iCelPlLayer::FindNearbyEntities | ( | iSector * | sector,
|  | const csVector3 & | pos,
|  | float | radius,
|  | bool | do_invisible = `false` |
| ) |  |  | `[pure virtual]`

Find all entities that are within a certain radius of a given position.

This uses the attached entities from above.

Parameters:

  | do_invisible | if true then also return invisible entities.

virtual iCelPropertyClassFactory* iCelPlLayer::FindPropertyClassFactory | ( | const char * | name | ) | const`[pure virtual]`

Find a property class factory by name.

virtual iCelBehaviour* iCelPlLayer::GetBehaviour | ( | uint | id | ) | `[pure virtual]`

This is a convenience function to get the behaviour that belongs to the entity for a given ID.

virtual iCelBlLayer* iCelPlLayer::GetBehaviourLayer | ( | size_t | idx | ) | const`[pure virtual]`

Get the specificied behaviour layer.

virtual size_t iCelPlLayer::GetBehaviourLayerCount | ( |  | ) | const`[pure virtual]`

Get the number of registered behaviour layers.

virtual iCelEntity* iCelPlLayer::GetEntity | ( | uint | id | ) | `[pure virtual]`

Returns the entity with ID id.

virtual iCelEntity* iCelPlLayer::GetEntityByIndex | ( | size_t | idx | ) | const`[pure virtual]`

Get the specific entity by index (not by ID).

virtual size_t iCelPlLayer::GetEntityCount | ( |  | ) | const`[pure virtual]`

Get the total number of entities.

virtual iCelEntityTemplate* iCelPlLayer::GetEntityTemplate | ( | size_t | idx | ) | const`[pure virtual]`

Get a specific entity template.

virtual size_t iCelPlLayer::GetEntityTemplateCount | ( |  | ) | const`[pure virtual]`

Get the number of entity templates.

virtual iCelEntity* iCelPlLayer::GetHitEntity | ( | iCamera * | camera,
|  | int | x,
|  | int | y |
| ) |  |  | `[pure virtual]`

Given a position on screen find the nearest entity to the camera.

Returns 0 if no entity found. This function depends on the attached entities.

virtual iCelPropertyClassFactory* iCelPlLayer::GetPropertyClassFactory | ( | size_t | idx | ) | const`[pure virtual]`

Get the specificied property class factory.

virtual size_t iCelPlLayer::GetPropertyClassFactoryCount | ( |  | ) | const`[pure virtual]`

Get the number of registered property class factories.

virtual bool iCelPlLayer::IsEntityAddonAllowed | ( |  | ) | const`[pure virtual]`

Query if entity addons are allowed.

virtual bool iCelPlLayer::LoadPropertyClassFactory | ( | const char * | plugin_id | ) | `[pure virtual]`

Load a property class plugin by class id if it doesn't already exist.

Returns false on failure. This must be called before you can use property classes from this factory.

virtual void iCelPlLayer::RegisterBehaviourLayer | ( | iCelBlLayer * | bl | ) | `[pure virtual]`

Register a behaviour layer.

virtual void iCelPlLayer::RegisterPropertyClassFactory | ( | iCelPropertyClassFactory * | pf | ) | `[pure virtual]`

Register a property class factory with this physical layer.

It is not needed for apps to call this function as the property class factory itself will do it when it is loaded. To load a property class factory plugin you can use LoadPropertyClassFactory().

virtual void iCelPlLayer::RemoveCallbackEveryFrame | ( | iCelTimerListener * | listener,
|  | int | where |
| ) |  |  | `[pure virtual]`

Remove all 'every-frame' callbacks to a specific listener.

virtual void iCelPlLayer::RemoveCallbackOnce | ( | iCelTimerListener * | listener,
|  | int | where |
| ) |  |  | `[pure virtual]`

Remove all 'once' callbacks to a specific listener.

virtual void iCelPlLayer::RemoveEntities | ( |  | ) | `[pure virtual]`

Remove all entities.

virtual void iCelPlLayer::RemoveEntity | ( | iCelEntity * | entity | ) | `[pure virtual]`

Remove an entity from the physical layer.

virtual void iCelPlLayer::RemoveEntityRemoveCallback | ( | iCelEntityRemoveCallback * | clback | ) | `[pure virtual]`

Removes a registered RemoveCallback.

virtual void iCelPlLayer::RemoveEntityTemplate | ( | iCelEntityTemplate * | entfact | ) | `[pure virtual]`

Remove an entity template.

virtual void iCelPlLayer::RemoveEntityTemplates | ( |  | ) | `[pure virtual]`

Remove all entity templates.

virtual void iCelPlLayer::RemoveEntityTracker | ( | iCelEntityTracker * | tracker | ) | `[pure virtual]`

Remove a tracker.

virtual void iCelPlLayer::RemoveNewEntityCallback | ( | iCelNewEntityCallback * | clback | ) | `[pure virtual]`

Removes a registered NewCallback.

virtual void iCelPlLayer::SetEntityAddonAllowed | ( | bool | allow | ) | `[pure virtual]`

Enable or disable the operations of the cel entity addon.

This addon will enable users to add entities from a CS world file. This addon will not do that if this flag is disabled (enabled by default). This is mostly used by the persistence layer to prevent the addons from working then since the entities will be loaded otherwise in that situation.

virtual void iCelPlLayer::UnattachEntity | ( | iObject * | object,
|  | iCelEntity * | entity |
| ) |  |  | `[pure virtual]`

Unattach an entity from some object.

virtual void iCelPlLayer::Uncache | ( | iBase * | object | ) | `[pure virtual]`

Uncache an SCF object.

virtual void iCelPlLayer::UnregisterBehaviourLayer | ( | iCelBlLayer * | bl | ) | `[pure virtual]`

Unregister a behaviour layer.

virtual void iCelPlLayer::UnregisterPropertyClassFactory | ( | iCelPropertyClassFactory * | pf | ) | `[pure virtual]`

Unregister a property class factory.

The documentation for this struct was generated from the following file:

- physicallayer/pl.h