GameController

GameController

This page contains documentation for the GameController class, which handles game operations like creation, updates, player management, and retrieval for both users and admins.

Basic Information

Base Path: /api/v1/authorized
Package: dev.goral.rpghandyhelper.game

Authentication

All endpoints require a valid XSRF token in headers:

headers: {
  "X-XSRF-TOKEN": "<csrfToken>"
}

---

Endpoint Summary

HTTP Method	Path	Description
GET	/game/{gameId}	Retrieve a specific game by its ID
GET	/game/allPlayers/{gameId}	Retrieve all players in a specific game
GET	/game/userGames	Retrieve all active games of the current user
POST	/game/create	Create a new game
POST	/game/addUserToGame	Add a user to a game (GMs only)
DELETE	/game/deleteUserFromGame	Remove a user from a game (GMs only)
PUT	/game/updateGame/{gameId}	Update game metadata
PUT	/game/changeStatus/{gameId}	Change the status of a game
PUT	/game/updateGameUserRole/{gameUserId}	Update a player's role in a game (GMs only)
GET	/admin/game/all	Retrieve all games (admin only)

---

Field Descriptions

Request Body Fields

Game

• name (String): Game name. Required, max 255 characters.
• description (String): Optional description, max 500 characters.
• rpgSystem.id (Long): ID of the RPG system. Required.

AddUserToGameRequest

• userId (Long): ID of user to add. Required.
• gameId (Long): ID of the game. Required.
• role (String): Role to assign (GAMEMASTER, PLAYER, SPECTATOR). Required.

DeleteUserFromGameRequest

• userId (Long): ID of user to remove. Required.
• gameId (Long): ID of the game. Required.

Role update request

• Body: { "role": "NEW_ROLE" } where NEW_ROLE is GAMEMASTER, PLAYER, or SPECTATOR.

Status update request

• Body: { "status": "ACTIVE" | "DELETED" }

Response Fields

• message (String): Operation result.
• error (Integer): HTTP status code.
• timestamp (String): Generation time.
• Additional payload:
  • game, games, gameUsers, userGames, or result maps, depending on endpoint.

---

Example Objects

GameDTO

{
  "id": 1,
  "name": "title",
  "description": "description",
  "ownerId": 1,
  "rpgSystemId": 1
}

GameDTOAdmin

{
  "id": 1,
  "name": "title",
  "description": "description",
  "ownerId": 1,
  "rpgSystemId": 1,
  "status": "ACTIVE"
}

UserGamesDTO

{
  "id": 1,
  "rpgSystemId": 1,
  "rpgSystemName": "System name",
  "name": "Game name",
  "description": "description"
}

GameUsersDTO

{
  "id": 1,
  "userId": 1,
  "gameId": 1,
  "role": "PLAYER"
}

---

Endpoint Details

Endpoint Details

Retrieve Specific Game by ID

Method: GET
Path: /game/{gameId}

Path Parameters

• gameId (Long): ID of the game to retrieve.

Response Example

{
  "message": "Pobrano grę.",
  "error": 200,
  "timestamp": "...",
  "game": { ... }
}

Possible Errors

• 404 Not Found: Game with given ID does not exist.

---

Retrieve All Players in a Game

Method: GET
Path: /game/allPlayers/{gameId}

Path Parameters

• gameId (Long): ID of the game whose players are to be retrieved.

Response Example

{
  "gameUsers": [ ... ],
  "message": "Pobrano listę użytkowników gry.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 404 Not Found: Game with given ID does not exist.

---

Retrieve Current User's Games

Method: GET
Path: /game/userGames

Response Example

{
  "message": "Pobrano listę gier użytkownika.",
  "error": 200,
  "timestamp": "...",
  "games": [ ... ]
}

Possible Errors

• 401 Unauthorized: User is not authenticated.

---

Create a New Game

Method: POST
Path: /game/create

Request Body

• GameDTO: JSON object containing game name and description.

Response Example

{
  "message": "Gra została utworzona.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 400 Bad Request: Missing name or invalid data.
• 401 Unauthorized: User is not authenticated.

---

Add a User to a Game

Method: POST
Path: /game/addUserToGame

Request Body

• GameUserDTO: JSON object with userId and gameId.

Response Example

{
  "message": "Użytkownik został dodany do gry.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 400 Bad Request: User already added or invalid game/user ID.
• 403 Forbidden: User is not the Game Master.
• 404 Not Found: Game or user does not exist.

---

Remove a User from a Game

Method: DELETE
Path: /game/deleteUserFromGame

Request Body

• GameUserDTO: JSON object with userId and gameId.

Response Example

{
  "message": "Użytkownik został usunięty z gry.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 400 Bad Request: User is not in the game.
• 403 Forbidden: User is not the Game Master.
• 404 Not Found: Game or user does not exist.

---

Update Game Metadata

Method: PUT
Path: /game/updateGame/{gameId}

Path Parameters

• gameId (Long): ID of the game to update.

Request Body

• GameDTO: JSON object with updated game data.

Response Example

{
  "message": "Gra została zaktualizowana.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 400 Bad Request: Invalid game data.
• 403 Forbidden: User is not the Game Master.
• 404 Not Found: Game not found.

---

Change Game Status

Method: PUT
Path: /game/changeStatus/{gameId}

Path Parameters

• gameId (Long): ID of the game to change status.

Request Body

• String: New status ("ACTIVE", "DELETED").

Response Example

{
  "message": "Status gry został zaktualizowany.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 400 Bad Request: Invalid status value.
• 403 Forbidden: User is not the Game Master.
• 404 Not Found: Game not found.

---

Update Player Role in a Game

Method: PUT
Path: /game/updateGameUserRole/{gameUserId}

Path Parameters

• gameUserId (Long): ID of the GameUser entity.

Request Body

• String: New role ("GAMEMASTER", "PLAYER", "SPECTATOR").

Response Example

{
  "message": "Rola użytkownika gry została zaktualizowana.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 400 Bad Request: Invalid role value.
• 403 Forbidden: User is not the Game Master.
• 404 Not Found: GameUser not found.

---

Retrieve All Games (Admin Only)

Method: GET
Path: /admin/game/all

Response Example

{
  "games": [ ... ],
  "message": "Pobrano wszystkie gry.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 403 Forbidden: User is not an admin.

---

Common Troubleshooting Tips

• Missing XSRF Token: Ensure the X-XSRF-TOKEN header is included in every request.
• Invalid Fields: Double-check the request body for missing or invalid fields.
• Permission Issues: Verify that the user is the owner of the note and the game is accessible.