/**
 * Game Framework Handlers
 *
 * Complete game framework system including:
 * - Core Classes (GameMode, GameState, PlayerController, PlayerState, GameInstance, HUD)
 * - Game Mode Configuration (default pawn, player controller, game state classes, game rules)
 * - Match Flow (match states, round system, team system, scoring, spawn system)
 * - Player Management (player start, respawn rules, spectating)
 *
 * @module game-framework-handlers
 */

import { ITools } from '../../../types/tools/tool-interfaces.js';
import { cleanObject } from '../../../utils/serialization/safe-json.js';
import type { HandlerArgs } from '../../../types/handlers/handler-types.js';
import { createSubActionDispatcher, requireNonEmptyString } from '../foundation/dispatch/common-handlers.js';


/**
 * Gets the game mode blueprint path from args, supporting both `gameModeBlueprint` and `blueprintPath`.
 */
function getGameModePath(argsRecord: Record<string, unknown>): string | undefined {
  return (argsRecord.gameModeBlueprint ?? argsRecord.blueprintPath) as string | undefined;
}

/**
 * Handles all game framework actions for the manage_game_framework tool.
 */
export async function handleGameFrameworkTools(
  action: string,
  args: HandlerArgs,
  tools: ITools
): Promise<Record<string, unknown>> {
  const { argsRecord, sendRequest } = createSubActionDispatcher(tools, args, {
    toolName: 'manage_game_framework',
    domainName: 'game framework',
    pathFields: [
      'path',
      'blueprintPath',
      'gameModeBlueprint'
    ]
  });

  switch (action) {
    // =========================================================================
    // 21.1 Core Classes (6 actions)
    // =========================================================================

    case 'create_game_mode': {
      requireNonEmptyString(argsRecord.name, 'name', 'Missing required parameter: name');
      requireNonEmptyString(argsRecord.path, 'path', 'Missing required parameter: path');
      // Creates a new GameModeBase blueprint
      // Optional: parentClass, defaultPawnClass, playerControllerClass, gameStateClass, playerStateClass, hudClass
      return sendRequest('create_game_mode');
    }

    case 'create_game_state': {
      requireNonEmptyString(argsRecord.name, 'name', 'Missing required parameter: name');
      requireNonEmptyString(argsRecord.path, 'path', 'Missing required parameter: path');
      // Creates a new GameStateBase blueprint
      // Optional: parentClass
      return sendRequest('create_game_state');
    }

    case 'create_player_controller': {
      requireNonEmptyString(argsRecord.name, 'name', 'Missing required parameter: name');
      requireNonEmptyString(argsRecord.path, 'path', 'Missing required parameter: path');
      // Creates a new PlayerController blueprint
      // Optional: parentClass
      return sendRequest('create_player_controller');
    }

    case 'create_player_state': {
      requireNonEmptyString(argsRecord.name, 'name', 'Missing required parameter: name');
      requireNonEmptyString(argsRecord.path, 'path', 'Missing required parameter: path');
      // Creates a new PlayerState blueprint
      // Optional: parentClass
      return sendRequest('create_player_state');
    }

    case 'create_game_instance': {
      requireNonEmptyString(argsRecord.name, 'name', 'Missing required parameter: name');
      requireNonEmptyString(argsRecord.path, 'path', 'Missing required parameter: path');
      // Creates a new GameInstance blueprint for persistent game data
      // Optional: parentClass
      return sendRequest('create_game_instance');
    }

    case 'create_hud_class': {
      requireNonEmptyString(argsRecord.name, 'name', 'Missing required parameter: name');
      requireNonEmptyString(argsRecord.path, 'path', 'Missing required parameter: path');
      // Creates a new HUD blueprint
      // Optional: parentClass, hudClass
      return sendRequest('create_hud_class');
    }

    // =========================================================================
    // 21.2 Game Mode Configuration (5 actions)
    // =========================================================================

    case 'set_default_pawn_class': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      requireNonEmptyString(argsRecord.pawnClass ?? argsRecord.defaultPawnClass, 'pawnClass', 'Missing required parameter: pawnClass or defaultPawnClass');
      // Sets the default pawn class for a game mode
      return sendRequest('set_default_pawn_class');
    }

    case 'set_player_controller_class': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      requireNonEmptyString(argsRecord.playerControllerClass, 'playerControllerClass', 'Missing required parameter: playerControllerClass');
      // Sets the player controller class for a game mode
      return sendRequest('set_player_controller_class');
    }

    case 'set_game_state_class': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      requireNonEmptyString(argsRecord.gameStateClass, 'gameStateClass', 'Missing required parameter: gameStateClass');
      // Sets the game state class for a game mode
      return sendRequest('set_game_state_class');
    }

    case 'set_player_state_class': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      requireNonEmptyString(argsRecord.playerStateClass, 'playerStateClass', 'Missing required parameter: playerStateClass');
      // Sets the player state class for a game mode
      return sendRequest('set_player_state_class');
    }

    case 'configure_game_rules': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      // Configures supported GameMode rule flags
      // Optional: bDelayedStart
      return sendRequest('configure_game_rules');
    }

    // =========================================================================
    // 21.3 Match Flow (5 actions)
    // =========================================================================

    case 'setup_match_states': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      // Sets up match state machine (waiting, warmup, in_progress, post_match, custom)
      // Optional: states (array of state definitions)
      return sendRequest('setup_match_states');
    }

    case 'configure_round_system': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      // Configures round-based gameplay
      // Optional: numRounds, roundTime, intermissionTime
      return sendRequest('configure_round_system');
    }

    case 'configure_team_system': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      // Configures team-based gameplay
      // Optional: numTeams, teamSize, autoBalance, friendlyFire
      return sendRequest('configure_team_system');
    }

    case 'configure_scoring_system': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      // Configures scoring mechanics
      // Optional: scorePerKill, scorePerAssist, scorePerObjective, winScore, scorePerDeath
      return sendRequest('configure_scoring_system');
    }

    case 'configure_spawn_system': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      // Configures spawn system behavior
      // Optional: spawnSelectionMethod, respawnDelay, respawnLocation, usePlayerStarts
      return sendRequest('configure_spawn_system');
    }

    // =========================================================================
    // 21.4 Player Management (3 actions)
    // =========================================================================

    case 'configure_player_start': {
      // Requires blueprintPath to identify context
      const bpPath = argsRecord.blueprintPath ?? argsRecord.gameModeBlueprint;
      requireNonEmptyString(bpPath, 'blueprintPath', 'Missing required parameter: blueprintPath');
      // Optional: teamIndex
      return sendRequest('configure_player_start');
    }

    case 'set_respawn_rules': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      // Configures respawn behavior
      // Optional: respawnDelay, respawnLocation, forceRespawn, respawnLives
      return sendRequest('set_respawn_rules');
    }

    case 'configure_spectating': {
      const gmPath = getGameModePath(argsRecord);
      requireNonEmptyString(gmPath, 'gameModeBlueprint', 'Missing required parameter: gameModeBlueprint or blueprintPath');
      // Configures spectator mode settings
      // Optional: allowSpectating, spectatorClass, spectatorViewMode
      return sendRequest('configure_spectating');
    }

    // =========================================================================
    // 21.5 Utility (1 action)
    // =========================================================================

    case 'get_game_framework_info': {
      // Returns game framework info for a level or game mode
      // Optional: gameModeBlueprint, blueprintPath
      return sendRequest('get_game_framework_info');
    }

    // =========================================================================
    // Default: Unknown action
    // =========================================================================

    default:
      return cleanObject({
        success: false,
        error: 'UNKNOWN_ACTION',
        message: `Unknown manage_game_framework action: ${action}`
      });
  }
}