createGameSession method
Creates a multiplayer game session for players. This operation creates a
game session record and assigns an available server process in the
specified fleet to host the game session. A fleet must have an
ACTIVE status before a game session can be created in it.
To create a game session, specify either fleet ID or alias ID and indicate a maximum number of players to allow in the game session. You can also provide a name and game-specific properties for this game session. If successful, a GameSession object is returned containing the game session properties and other settings you specified.
Idempotency tokens. You can add a token that uniquely identifies game session requests. This is useful for ensuring that game session requests are idempotent. Multiple requests with the same idempotency token are processed only once; subsequent requests return the original result. All response values are the same with the exception of game session status, which may change.
Resource creation limits. If you are creating a game session on a fleet with a resource creation limit policy in force, then you must specify a creator ID. Without this ID, Amazon GameLift has no way to evaluate the policy for this new game session request.
Player acceptance policy. By default, newly created game sessions are open to new players. You can restrict new player access by using UpdateGameSession to change the game session's player session creation policy.
Game session logs. Logs are retained for all active game sessions for 14 days. To access the logs, call GetGameSessionLogUrl to download the log files.
Available in Amazon GameLift Local.
- CreateGameSession
- DescribeGameSessions
- DescribeGameSessionDetails
- SearchGameSessions
- UpdateGameSession
- GetGameSessionLogUrl
- Game session placements
May throw ConflictException. May throw InternalServiceException. May throw UnauthorizedException. May throw InvalidFleetStatusException. May throw TerminalRoutingStrategyException. May throw InvalidRequestException. May throw NotFoundException. May throw FleetCapacityExceededException. May throw LimitExceededException. May throw IdempotentParameterMismatchException.
Parameter maximumPlayerSessionCount :
The maximum number of players that can be connected simultaneously to the
game session.
Parameter aliasId :
A unique identifier for an alias associated with the fleet to create a
game session in. You can use either the alias ID or ARN value. Each
request must reference either a fleet ID or alias ID, but not both.
Parameter creatorId :
A unique identifier for a player or entity creating the game session. This
ID is used to enforce a resource protection policy (if one exists) that
limits the number of concurrent active game sessions one player can have.
Parameter fleetId :
A unique identifier for a fleet to create a game session in. You can use
either the fleet ID or ARN value. Each request must reference either a
fleet ID or alias ID, but not both.
Parameter gameProperties :
Set of custom properties for a game session, formatted as key:value pairs.
These properties are passed to a game server process in the
GameSession object with a request to start a new game session (see
Start
a Game Session).
Parameter gameSessionData :
Set of custom game session properties, formatted as a single string value.
This data is passed to a game server process in the GameSession
object with a request to start a new game session (see Start
a Game Session).
Parameter gameSessionId :
This parameter is no longer preferred. Please use
IdempotencyToken instead. Custom string that uniquely
identifies a request for a new game session. Maximum token length is 48
characters. If provided, this string is included in the new game session's
ID. (A game session ARN has the following format:
arn:aws:gamelift:<region>::gamesession/<fleet
ID>/<custom ID string or idempotency token>.)
Parameter idempotencyToken :
Custom string that uniquely identifies a request for a new game session.
Maximum token length is 48 characters. If provided, this string is
included in the new game session's ID. (A game session ARN has the
following format:
arn:aws:gamelift:<region>::gamesession/<fleet
ID>/<custom ID string or idempotency token>.) Idempotency
tokens remain in use for 30 days after a game session has ended; game
session objects are retained for this time period and then deleted.
Parameter name :
A descriptive label that is associated with a game session. Session names
do not need to be unique.
Implementation
Future<CreateGameSessionOutput> createGameSession({
required int maximumPlayerSessionCount,
String? aliasId,
String? creatorId,
String? fleetId,
List<GameProperty>? gameProperties,
String? gameSessionData,
String? gameSessionId,
String? idempotencyToken,
String? name,
}) async {
ArgumentError.checkNotNull(
maximumPlayerSessionCount, 'maximumPlayerSessionCount');
_s.validateNumRange(
'maximumPlayerSessionCount',
maximumPlayerSessionCount,
0,
1152921504606846976,
isRequired: true,
);
_s.validateStringLength(
'creatorId',
creatorId,
1,
1024,
);
_s.validateStringLength(
'gameSessionData',
gameSessionData,
1,
4096,
);
_s.validateStringLength(
'gameSessionId',
gameSessionId,
1,
48,
);
_s.validateStringLength(
'idempotencyToken',
idempotencyToken,
1,
48,
);
_s.validateStringLength(
'name',
name,
1,
1024,
);
final headers = <String, String>{
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'GameLift.CreateGameSession'
};
final jsonResponse = await _protocol.send(
method: 'POST',
requestUri: '/',
exceptionFnMap: _exceptionFns,
// TODO queryParams
headers: headers,
payload: {
'MaximumPlayerSessionCount': maximumPlayerSessionCount,
if (aliasId != null) 'AliasId': aliasId,
if (creatorId != null) 'CreatorId': creatorId,
if (fleetId != null) 'FleetId': fleetId,
if (gameProperties != null) 'GameProperties': gameProperties,
if (gameSessionData != null) 'GameSessionData': gameSessionData,
if (gameSessionId != null) 'GameSessionId': gameSessionId,
if (idempotencyToken != null) 'IdempotencyToken': idempotencyToken,
if (name != null) 'Name': name,
},
);
return CreateGameSessionOutput.fromJson(jsonResponse.body);
}