Gorilla.Arena.Entity Unit Reference

Overview

The Gorilla.Arena.Entity unit provides TGorillaArenaEntity, the base class for every object exchanged by tethering between all connected profiles — users and their items, weapons, collected things, skills.

An entity keeps its properties in a JSON document rather than in fields. Give each property a getter and setter that call GetJSONProperty and SetJSONProperty, and no field declaration is needed: the document is the storage, and it is also what goes on the wire.

Class Hierarchy

TInterfacedObject
  └── TJSONWrapObject                 (Gorilla.Arena.JSONWrap)
        └── TGorillaArenaEntity       implements IGorillaArenaEntity
              └── TGorillaArenaUser

TGorillaArenaItemList = TList<IGorillaArenaEntity>

Constants

Field names every entity carries.

Constant Value Description
ARENA_ITEM_FIELD_SOURCEPROFILE SourceProfile Identifier of the profile the entity came from
ARENA_ITEM_FIELD_GUID GUID The entity's identity
ARENA_ITEM_FIELD_QUALIFIEDNAME QualifiedName Qualified class name, so the other side can build the right class
ARENA_ITEM_FIELD_ID Id Free identifier
ARENA_ITEM_FIELD_GROUP Group Free grouping key

IGorillaArenaEntity

GUID {6D9D6905-61EF-4CF6-BC9E-3DB2CACD757A}, descends IJSONWrapObject.

Member Type Description
SourceProfile String Where it came from
QualifiedName String Qualified class name (read only in effect)
GUID TGUID Identity
GUIDStr String The same as a string
Id String Free identifier
Group String Free grouping key
SendLocalResource(AProfile) Broadcasts the complete entity
SendLocalResource(AProfile, AProperty, AValue) Broadcasts one changed property
BeginUpdate, EndUpdate, Submit, Changed See below

TGorillaArenaEntity

Constructor

constructor Create(const AProfile : TObject); reintroduce; virtual;

AProfile is whatever the entity reports its changes to — a component that implements IGorillaArenaEntityHost (a session, a match, a manager), or, as in code written for tethering, the manager's Profile: the manager installs TGorillaArenaEntity.HostResolver, which leads from its app profile to itself. The constructor generates a GUID and fills in GUID, QualifiedName and SourceProfile — the host's EntityOwnerId, which makes the entity ours.

IGorillaArenaEntityHost

Method Called when
EntityOwnerId() : String An entity is created here — its SourceProfile
EntityChanged(const AEntity) A property changed (once per BeginUpdate/EndUpdate bracket)
EntitySubmit(const AEntity) Submit or SendLocalResource — the entity is to reach everybody in full
EntityPropertySubmit(const AEntity; const AProperty; const AValue) One property is to reach everybody

The entity is handed over as an object, not as an interface: passing Self as an interface from a reference counted object nobody holds yet would free it. The tethering manager writes the shared resource and sends Item/Update streams, as entities always did; a session on atDirect sends an owned, listed entity in full to everybody.

Class Methods

Method Description
RegisterEntityClass(const AClass) Makes a class findable by its qualified name when another participant shares an entity of it — and keeps the linker from dropping it
FindEntityClass(const AQualifiedName) Registered classes first, then RTTI; nil when neither knows it
HostResolver See above

Published Properties

Property Type Description
QualifiedName String Setting it does nothing — the class name is not yours to change
GUID TGUID Identity
GUIDStr String Identity as a string
Id String Free identifier
Group String Free grouping key

Public Properties

Property Type Description
Profile TObject What the entity was created with
Host IGorillaArenaEntityHost Where changes go; nil once the host is gone
SourceProfile String The owner — the tethering profile identifier, or the session member id on atDirect
Bitmap TBitmap An image belonging to the entity. Needs streaming separately — it is not part of the JSON document

Public Methods

Method Description
BeginUpdate() Hold back updates while several properties change
EndUpdate() End that
Submit() Push the whole entity to everybody — EntitySubmit on the host
Changed() Report the entity as changed — EntityChanged on the host
SetJSONProperty(const AName : String; const AValue : TValue) Sets a property and reports the change; inside BeginUpdate/EndUpdate it is reported once, when the outermost EndUpdate is reached
DetachHost() Lets go of the host; called by a host that is being destroyed
GetEntity() : TGorillaArenaEntity The object behind the interface (also on IGorillaArenaEntity)
ApplyFromJSON(const AData : TJSONObject) Replaces the document with the supplied one, then submits. Does not check that the data belongs to this class

Protected Methods

Method Description
SendLocalResource(AProfile : TObject) EntitySubmit on the host. AProfile is kept for compatibility and ignored
SendLocalResource(AProfile : TObject; const AProperty : String; const AValue : TValue) EntityPropertySubmit on the host
UpdateLocalResource() EntityChanged on the host

All three return immediately while an update is in progress.

Batching Updates

Changing a property updates the local resource, which the other side mirrors. Changing several in a row therefore produces one update each — which is a lot of network traffic for no reason:

LItem.BeginUpdate();
try
  LItem.Property1 := 'abc';
  LItem.Property2 := 123;
  LItem.Property3 := 1.25;
finally
  LItem.EndUpdate();
  LItem.Submit();
end;

Writing an Entity

type
  TCard = class(TGorillaArenaEntity)
    protected
      function  GetSuit() : String;
      procedure SetSuit(const AValue : String);
    published
      property Suit : String read GetSuit write SetSuit;
  end;

function TCard.GetSuit() : String;
begin
  Result := GetJSONProperty('Suit').AsString().DeQuotedString('"');
end;

procedure TCard.SetSuit(const AValue : String);
begin
  SetJSONProperty('Suit', AValue);
end;

Simple types are stored directly as JSON. For values that are not — a colour, a 3D point — convert on the way in and out; see Gorilla.Arena.Utils and the implementation of TGorillaArenaUser.

See Also