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

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