Match
TGorillaArenaMatch is a Session in which everybody takes turns.
It adds seating, turn order, host authority and state synchronisation — the
half of a turn based game that is the same whether it is cards, dice or a
board.
What is left for the application is the rules, what a move contains, and the user interface.
Table of Contents
- Host Authority
- Starting a Match
- Taking a Turn
- Seating
- Where the Rules Come From
- Carrying Your Own Data
- What to Draw
- The Message Flow
- Two Hosts Meeting
- See Also
Host Authority
Whoever opened the session owns the only rules instance that decides anything.
The others keep one of their own purely to render the state the host ships
them — they never see SubmitTurn.
host client
---- ------
rules.SubmitTurn(seat, move) <----- move
rules.StateToJSON() -----> rules.StateFromJSON()
rules.CurrentSeat() -----> turn
The consequence worth knowing: a client's rules object is a renderer. Its
CurrentSeat and Finished are never asked; what it shows comes entirely from
the state the host sent.
Starting a Match
Host only:
FMatch.StartMatch(); // the linked rules
FMatch.StartMatch('poker'); // built through OnCreateRules
StartMatch builds the rules, checks that enough members are present
(MinMembers), fixes the seating, resets the rules, and sends everybody a
start message. Too few members, or an id nothing can build, produces a notice
and nothing else.
Taking a Turn
if FMatch.IsMyTurn() then
begin
LMove := TJSONObject.Create();
LMove.AddPair('card', 'Q');
FMatch.SubmitMove(LMove); // takes ownership; may be nil
end;
On the host that goes straight into the rules. On a client it travels to the
host, who decides and ships the result back. Either way SubmitMove does
nothing unless it really was your turn.
IsMyTurn is false again the moment you have moved, and stays false until the
host says otherwise — a repeated turn message does not put you back on.
IsMyTurn() |
It is our turn and we have not moved yet |
TurnSeat() |
Seat of whoever is on turn, or -1 |
TurnMemberName() |
Their name, or '' |
InMatch |
True while a match is running |
Seating
The seating is fixed when the match starts and does not change again.
Somebody who leaves keeps their seat and their score and is marked
Here := False; the rules are told through MemberLeft and decide what that
means — skipping their turn, or ending a match nobody is left in.
SeatOf(AId) resolves an id to a seat. Participants() is what to list:
| Situation | What it returns |
|---|---|
| A match is running | The seating |
| Before one, on a client | The roster the host sent |
| Otherwise | Whoever the session has found |
On a client the host's list beats what the local user list has caught up with — the host owns the session. A list the client is not itself in is ignored: that is one the host put together before it had heard of the newcomer, and taking it would drop them out of their own lobby until the next one arrives.
Where the Rules Come From
Three ways, tried in this order:
// 1. the event
FMatch.OnCreateRules := CreateRules;
procedure TForm1.CreateRules(const ASender : TObject; const AId : String;
out ARules : IGorillaArenaRules);
begin
ARules := MyGameRegistry.Build(AId); // nil for an id you do not have
end;
// 2. a component on the form
FMatch.RulesComponent := MyRules1;
// 3. set directly, for one fixed set of rules
FMatch.Rules := TMyRules.Create();
Or override CreateRules in a descendant to build them some other way. See
Rules for what to implement.
Carrying Your Own Data
The framework does not know what your game needs on top of the roster. Four hooks put it there and read it back:
| Host side | Client side | |
|---|---|---|
DoDecorateStart |
DoApplyStart |
Anything the match needs to know once, at the start |
DoDecorateTurn |
DoApplyTurn |
Anything that belongs on every turn message |
procedure TMyMatch.DoDecorateStart(AMsg : TGorillaArenaMessage);
begin
inherited;
AMsg.SetInt('dice', FDiceCount);
end;
procedure TMyMatch.DoApplyStart(AMsg : TGorillaArenaMessage);
begin
inherited;
FDiceCount := AMsg.GetInt('dice', 2);
end;
DoRemoteMove is the other half: somebody else moved, and this is where you
show it.
procedure TMyMatch.DoRemoteMove(const AName : String;
const AMove : TJSONObject);
begin
inherited; // raises OnRemoteMove
// AMove is borrowed and may be nil
end;
What to Draw
Participants() |
Everybody, in the order they should be listed |
Scoreboard() |
The rules' scoreboard, or empty outside a match |
Headline() |
One line above it — "Round 2 of 3" |
RulesId |
Id of the rules in play |
HostId |
Id of whoever is hosting |
| Event | |
|---|---|
OnMatchChanged |
The state, the turn or the outcome moved |
OnRemoteMove |
Somebody else moved |
OnCreateRules |
Build the rules behind an id |
plus everything the session already offers — OnMembersChanged, OnNotice,
OnAppMessage.
The Message Flow
Seven message types, all handled for you:
| Type | Direction | |
|---|---|---|
hello |
client → host | I am here, this is my name |
lobby |
host → all | Who is in, and which rules are selected |
start |
host → all | The match begins |
turn |
host → all | It is this member's turn |
state |
host → all | The state after a move |
over |
host → all | The match ended |
move |
client → host | What I did on my turn |
Two details that only show up in practice:
Turns are numbered. The host re-sends the current turn whenever somebody says hello — and the session layer greets more than once per join. Without a number on it, a player who had already moved would be told to move again, and would play the whole thing out a second time for nothing.
A newcomer mid match is caught up. Their hello gets the lobby, the
current state, and the running turn marked as a repeat rather than a new one.
Two Hosts Meeting
Two people open a session and then find each other. Rather than leaving both convinced they are in charge, the lower id keeps it and the other switches to client with a notice. An arbitrary rule, but the same one on both devices, which is the only property that matters.
See Also
- Rules — Writing the rules a match is played by
- Session — The layer below
- Gorilla.Arena.Match — API reference
- Gorilla.Arena.Rules — API reference