GKTurnBasedParticipant Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in OS X v10.8 and later.
Companion guide
Declared in
GKTurnBasedMatch.h

Overview

A GKTurnBasedParticipant object stores information for a participant in a turn-based match. Your game never creates objects of this class directly; instead it retrieves an array of GKTurnBasedParticipant objects from a GKTurnBasedMatch object.

Most information stored in a GKTurnBasedParticipant object is read-only, and is provided by Game Kit to assist you in implementing your game logic. However, the matchOutcome property is quite important; before your game ends a match, it must set the matchOutcome property for every participant in the match.

Subclassing Notes

This class may not be subclassed.

Tasks

Participant Information

Setting the Match Outcome

Properties

lastTurnDate

The date and time that this participant last took a turn in the game. (read-only)

@property(readonly, copy, nonatomic) NSDate *lastTurnDate
Discussion

The value of this property is invalid until the participant first takes a turn in the match.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKTurnBasedMatch.h

matchOutcome

The end-state of this participant in the match.

@property(assign, nonatomic) GKTurnBasedMatchOutcome matchOutcome
Discussion

Initially, this property holds GKTurnBasedMatchOutcomeNone. Before your game can end a match, it must set the match outcome to a value that reflects the outcome of this participant when he or she left the match. See “Match Outcomes”. Optionally, it may also use an OR operation to include a custom match outcome for your specific game. Game Center does not use the custom value; it exists to allow your game to store its own information about the end of the match. The custom value must fit in the range provided by the GKTurnBasedMatchOutcomeCustomRange constant.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKTurnBasedMatch.h

playerID

The player identifier for this participant. (read-only)

@property(readonly, copy, nonatomic) NSString *playerID
Discussion

The value of this property may be nil if this slot in the match has not yet been filled by an actual player.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKTurnBasedMatch.h

status

The current status of the participant. (read-only)

@property(readonly, nonatomic) GKTurnBasedParticipantStatus status
Discussion

This property is updated by Game Kit to reflect the current status of the local player.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKTurnBasedMatch.h

timeoutDate

The date and time that the participant’s turn times out. (read-only)

@property(readonly, copy, nonatomic) NSDate *timeoutDate
Discussion

If a timeout was set when the turn state was advanced, this property holds when the player’s turn expires. Otherwise, this property is nil.

Availability
  • Available in OS X v10.9 and later.
Declared In
GKTurnBasedMatch.h

Constants

Match Outcomes

The state the participant was in when they left the match.

enum {
   GKTurnBasedMatchOutcomeNone = 0,
   GKTurnBasedMatchOutcomeQuit = 1,
   GKTurnBasedMatchOutcomeWon = 2,
   GKTurnBasedMatchOutcomeLost = 3,
   GKTurnBasedMatchOutcomeTied = 4,
   GKTurnBasedMatchOutcomeTimeExpired = 5,
   GKTurnBasedMatchOutcomeFirst = 6,
   GKTurnBasedMatchOutcomeSecond = 7,
   GKTurnBasedMatchOutcomeThird = 8,
   GKTurnBasedMatchOutcomeFourth = 9,
   GKTurnBasedMatchOutcomeCustomRange = 0x00FF0000
};
typedef NSInteger GKTurnBasedMatchOutcome;
Constants
GKTurnBasedMatchOutcomeNone

The participant’s outcome has not been set yet (typically because the match is still in progress).

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeQuit

The participant forfeited the match.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeWon

The participant won the match.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeLost

The participant lost the match.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeTied

The participant tied the match.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeTimeExpired

The participant was ejected from the match because he or she did not act in a timely fashion.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeFirst

The participant finished first.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeSecond

The participant finished second.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeThird

The participant finished third.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeFourth

The participant finished fourth.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedMatchOutcomeCustomRange

A mask used to allow your game to provide its own custom outcome. Any custom value must fit inside the mask.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedParticipantStatus

The state the participant is in during the match.

enum {      GKTurnBasedParticipantStatusUnknown = 0,
   GKTurnBasedParticipantStatusInvited = 1,
   GKTurnBasedParticipantStatusDeclined = 2,
   GKTurnBasedParticipantStatusMatching = 3,
   GKTurnBasedParticipantStatusActive = 4,
   GKTurnBasedParticipantStatusDone = 5,
};
typedef NSInteger GKTurnBasedParticipantStatus;
Constants
GKTurnBasedParticipantStatusUnknown

The participant is in an unexpected state.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedParticipantStatusInvited

The participant was invited to the match, but has not responded to the invitation.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedParticipantStatusDeclined

The participant declined the invitation to join the match. When a participant declines an invitation to join a match, the match is automatically terminated.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedParticipantStatusMatching

The participant represents an unfilled position in the match that Game Center promises to fill when needed. When you make this participant the next person to take a turn in the match, Game Center fills the position and updates the status and playerID properties.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedParticipantStatusActive

The participant has joined the match and is an active player in it.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.

GKTurnBasedParticipantStatusDone

The participant has exited the match. Your game sets the matchOutcome property to state why the participant left the match.

Available in OS X v10.8 and later.

Declared in GKTurnBasedMatch.h.