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.