games.among_us.state_manager¶

Comprehensive state management mixin for Among Us social deduction gameplay.

This module provides the core state management functionality for Among Us games, handling complex game mechanics including role assignments, task management, sabotage systems, meeting coordination, and win condition evaluation. The state manager coordinates all gameplay elements for authentic Among Us experiences.

The state manager handles: - Game initialization with role assignments and task generation - Move validation and application for all player actions - Complex sabotage mechanics with resolution systems - Meeting and voting coordination - Win condition evaluation and game progression - Player state filtering for information hiding - Legal move generation for AI decision-making

Examples

Initializing a game:

state = AmongUsStateManagerMixin.initialize(
    player_names=["Alice", "Bob", "Charlie", "David", "Eve"],
    map_name="skeld",
    num_impostors=1
)

Applying player moves:

move = {"action": "move", "location": "electrical"}
new_state = AmongUsStateManagerMixin.apply_move(state, "Alice", move)

Checking game status:

updated_state = AmongUsStateManagerMixin.check_game_status(state)
if updated_state.game_status == "ended":
    print(f"Game over! Winner: {updated_state.winner}")

Note

This is a mixin class designed to be inherited by game agents, providing state management capabilities without agent-specific behavior.

Classes¶

AmongUsStateManagerMixin

Comprehensive state management mixin for Among Us social deduction gameplay.

Module Contents¶

class games.among_us.state_manager.AmongUsStateManagerMixin¶

Bases: haive.games.framework.multi_player.state_manager.MultiPlayerGameStateManager[haive.games.among_us.state.AmongUsState]

Comprehensive state management mixin for Among Us social deduction gameplay.

This mixin class provides complete state management functionality for Among Us games, handling complex mechanics including role-based gameplay, task systems, sabotage mechanics, meeting coordination, and win condition evaluation. The class separates state management from agent behavior, allowing any inheriting class to gain full Among Us state management capabilities.

The state manager handles: - Game initialization with intelligent role assignment - Task generation and completion tracking - Complex sabotage systems with resolution mechanics - Meeting and voting coordination - Move validation and application - Win condition evaluation - Player state filtering for information hiding - Legal move generation for AI systems

Examples

Initializing a new game:

state = AmongUsStateManagerMixin.initialize(
    player_names=["Alice", "Bob", "Charlie", "David", "Eve"],
    map_name="skeld",
    num_impostors=1,
    tasks_per_player=5
)

Applying player actions:

# Player movement
move = {"action": "move", "location": "electrical"}
new_state = AmongUsStateManagerMixin.apply_move(state, "Alice", move)

# Task completion
task_move = {"action": "complete_task", "task_id": "Alice_task_1"}
new_state = AmongUsStateManagerMixin.apply_move(state, "Alice", task_move)

# Impostor actions
kill_move = {"action": "kill", "target_id": "Bob"}
new_state = AmongUsStateManagerMixin.apply_move(state, "Eve", kill_move)

Checking game progression:

updated_state = AmongUsStateManagerMixin.check_game_status(state)
if updated_state.game_status == "ended":
    print(f"Game over! {updated_state.winner} wins!")

Note

This mixin is designed to be inherited by game agents, providing state management capabilities without imposing specific agent behaviors.

classmethod advance_phase(state)¶

Advance the game to the next phase in the game cycle.

Progresses the game through its phases: TASKS -> MEETING -> VOTING -> TASKS. Updates related state variables and resets phase-specific data.

Parameters:

state (haive.games.among_us.state.AmongUsState) – Current game state to advance.

Returns:

Updated state in the next phase.

Return type:

AmongUsState

Examples

Task to meeting transition:

new_state = cls.advance_phase(state)
# game_phase changes from TASKS to MEETING

Meeting to voting transition:

new_state = cls.advance_phase(state)
# game_phase changes from MEETING to VOTING

Voting to tasks transition:

new_state = cls.advance_phase(state)
# game_phase changes from VOTING to TASKS
# round_number increments, votes cleared
classmethod apply_move(state, player_id, move)¶

Apply a player’s move to the game state with comprehensive validation.

Processes and validates player moves, updating the game state accordingly. Handles all move types across different game phases with proper error handling and state consistency maintenance.

Parameters:
Returns:

Updated game state after applying the move.

Return type:

AmongUsState

Examples

Movement action:

move = {"action": "move", "location": "electrical"}
new_state = cls.apply_move(state, "Alice", move)

Task completion:

move = {"action": "complete_task", "task_id": "Alice_task_1"}
new_state = cls.apply_move(state, "Alice", move)

Impostor kill:

move = {"action": "kill", "target_id": "Bob"}
new_state = cls.apply_move(state, "Eve", move)

Voting action:

move = {"action": "vote", "vote_for": "Charlie"}
new_state = cls.apply_move(state, "Alice", move)

Note

The method creates a deep copy of the state to avoid modifying the original, ensuring state immutability.

classmethod check_game_status(state)¶

Check and update game status with win condition evaluation.

Evaluates the current game state to determine if any win conditions have been met and updates the game status accordingly.

Parameters:

state (haive.games.among_us.state.AmongUsState) – Current game state to check.

Returns:

Updated state with current game status.

Return type:

AmongUsState

Examples

Ongoing game:

updated_state = cls.check_game_status(state)
# Returns state with game_status="ongoing"

Crewmate victory:

updated_state = cls.check_game_status(state)
# Returns state with game_status="ended", winner="crewmates"

Impostor victory:

updated_state = cls.check_game_status(state)
# Returns state with game_status="ended", winner="impostors"
classmethod filter_state_for_player(state, player_id)¶

Filter game state to include only information visible to a specific player.

Creates a filtered view of the game state that includes only information the specified player should have access to, implementing proper information hiding for authentic social deduction gameplay.

Parameters:
Returns:

Filtered state dictionary with player-visible information.

Return type:

Dict[str, Any]

Examples

Crewmate filtered state:

filtered = cls.filter_state_for_player(state, "Alice")
# Includes: own location, tasks, observations, connected rooms
# Excludes: other players' roles, impostor identities

Impostor filtered state:

filtered = cls.filter_state_for_player(state, "Eve")
# Includes: fellow impostors, vent locations, kill cooldown
# Excludes: crewmate task progress details

Dead player filtered state:

filtered = cls.filter_state_for_player(state, "Bob")
# Includes: basic game information, spectator view
# Excludes: ability to influence game

Generate comprehensive legal moves for a player based on game state.

Analyzes the current game state and player situation to generate all valid moves available to the player, considering their role, location, game phase, and current constraints.

Parameters:
Returns:

List of legal move dictionaries.

Return type:

List[Dict[str, Any]]

Examples

Crewmate in task phase:

moves = cls.get_legal_moves(state, "Alice")
# Returns moves like:
# [{"action": "move", "location": "electrical"},
#  {"action": "complete_task", "task_id": "Alice_task_1"},
#  {"action": "report_body"}] (if body present)

Impostor in task phase:

moves = cls.get_legal_moves(state, "Eve")
# Returns moves like:
# [{"action": "move", "location": "medbay"},
#  {"action": "kill", "target_id": "Bob"},
#  {"action": "vent", "vent_id": "electrical_vent"},
#  {"action": "sabotage", "sabotage_type": "lights"}]

Player in voting phase:

moves = cls.get_legal_moves(state, "Alice")
# Returns moves like:
# [{"action": "vote", "vote_for": "Charlie"},
#  {"action": "vote", "vote_for": "skip"}]
classmethod initialize(player_names, **kwargs)¶

Initialize a new Among Us game state with intelligent defaults.

Creates a complete game state with role assignments, task generation, map initialization, and all necessary game components. The initialization process follows standard Among Us rules for balanced gameplay.

Parameters:

  • player_names (list[str]) – List of player identifiers (4-15 players).

  • **kwargs – Additional configuration options. map_name (str): Map to use (default: “skeld”). num_impostors (int): Number of impostors (auto-calculated if None). tasks_per_player (int): Tasks per crewmate (default: 5). kill_cooldown (int): Impostor kill cooldown in seconds (default: 45). seed: Random seed for reproducible games.

Returns:

Fully initialized game state ready for gameplay.

Return type:

AmongUsState

Examples

Standard initialization:

state = AmongUsStateManagerMixin.initialize(
    player_names=["Alice", "Bob", "Charlie", "David", "Eve"],
    map_name="skeld"
)
# Auto-assigns 1 impostor for 5 players

Custom configuration:

state = AmongUsStateManagerMixin.initialize(
    player_names=["Player_" + str(i) for i in range(10)],
    map_name="polus",
    num_impostors=2,
    tasks_per_player=6,
    kill_cooldown=30,
    seed=12345
)

Note

The initialization automatically balances impostor count based on player count following standard Among Us ratios.