carre_magic_logic #

carre_magic_logic est un moteur de règles et d'intelligence artificielle en Dart pur (aucune dépendance Flutter) pour le jeu du Carré Magique (jeu de plateau combinatoire à déplacements et captures).

Ce package fournit la logique complète du jeu : déplacements réguliers, captures, système de promotion dynamique, gestion de fin de partie, sérialisation JSON, et IA Minimax avec élagage Alpha-Bêta exécutable en Isolate.

Sommaire #

• Fonctionnalités
• Installation
• Structure du package
• Guide d'utilisation
  • 1. Initialiser une partie
  • 2. Obtenir et appliquer des coups légaux
  • 3. Calculer un coup avec l'IA
  • 4. Sauvegarde et Sérialisation JSON
  • 5. Tailles de plateau personnalisées
• Exécution des exemples et tests
• Licence

Fonctionnalités #

• ♟️ Moteur de règles complet : validation des déplacements orthogonaux et diagonaux selon la topologie des cases, calcul de captures et statut de la partie.
• 🔄 Système de promotion : détection de promotion de pion atteignant la ligne opposée, réintégration de pions capturés (ApplyPromotion).
• 🤖 Intelligence Artificielle Minimax :
  • Évaluateur de plateau heuristique (BoardEvaluator).
  • Moteur Minimax avec élagage $\alpha$-$\beta$ (MinimaxEngine).
  • Calcul asynchrone non-bloquant en arrière-plan via Isolate (ComputeAiMove).
  • Presets de difficulté (AiDifficulty.easy, medium, hard) ou échelle continue (AiConfigStrength.fromStrength).
• ⚙️ Plateaux et règles configurables : support des grilles 5x5, 7x7, 9x9 (BoardConfig) et options de règles (GameRules).
• 🧩 Support des puzzles / niveaux : chargement de dispositions de pions personnalisées via GameLevel.
• 💾 Codec JSON : sérialisation / désérialisation complète de l'état du jeu (GameCodec).
• 🚀 100% Dart pur : utilisable côté serveur, CLI, Flutter ou n'importe quel environnement Dart.

Installation #

Ajoutez carre_magic_logic à votre projet Dart / Flutter :

dart pub add carre_magic_logic

Ou dans votre pubspec.yaml :

dependencies:
  carre_magic_logic: ^1.0.0

Puis importez le package dans votre code :

import 'package:carre_magic_logic/carre_magic_logic.dart';

Structure du package #

lib/
├── carre_magic_logic.dart      # Barrel principal (exporte toutes les APIs publiques)
└── src/
    ├── constants/              # Constantes géométriques
    ├── config/                 # BoardConfig, GameRules
    ├── enums/                  # PlayerColor, GameStatus
    ├── entities/               # Position, Piece, Board, Move, PendingPromotion, GameState
    ├── errors/                 # GameFailure, Result (Ok / Err)
    ├── levels/                 # GameLevel
    ├── engine/                 # BoardGeometry, GetValidMoves, CheckGameOver, ApplyMove, ApplyPromotion, InitializeGame
    ├── ai/                     # AiConfig, AiDifficulty, BoardEvaluator, MinimaxEngine, ComputeAiMove
    └── codec/                  # GameCodec (JSON ⇄ GameState)

Guide d'utilisation #

1. Initialiser une partie #

import 'package:carre_magic_logic/carre_magic_logic.dart';

// Initialise un plateau standard 5x5 (10 pions par joueur)
final state = InitializeGame.call();

print('Trait aux : ${state.currentPlayer.displayName}');
print('Pions blancs : ${state.board.countPieces(PlayerColor.white)}');
print('Pions noirs : ${state.board.countPieces(PlayerColor.black)}');

2. Obtenir et appliquer des coups légaux #

// Récupérer les coups disponibles pour la position (3, 0)
final moves = GetValidMoves.forState(state, const Position(row: 3, col: 0));

if (moves.isNotEmpty) {
  final move = moves.first;
  final nextState = ApplyMove.call(state, move);
  print('Coup joué : $move');
}

3. Calculer un coup avec l'IA #

Le calcul de l'IA s'effectue en arrière-plan via un Isolate pour ne jamais figer l'interface :

// Calcul du meilleur coup pour l'état courant
final aiMove = await ComputeAiMove.call(state, AiDifficulty.medium);

if (aiMove != null) {
  var updatedState = ApplyMove.call(state, aiMove);
  
  // Résolution automatique d'une éventuelle promotion pour l'IA
  updatedState = MinimaxEngine.resolvePendingPromotion(updatedState);
}

4. Sauvegarde et Sérialisation JSON #

// Exporter l'état en Map JSON
final jsonMap = state.toJson();

// Restaurer l'état
final restoredState = GameStateJson.fromJson(jsonMap);
assert(restoredState == state);

5. Tailles de plateau personnalisées #

// Démarrer une partie sur une grille 7x7
final state7x7 = InitializeGame.call(
  config: BoardConfig.standard7x7,
);

Exécution des exemples et tests #

Pour exécuter l'exemple console :

dart run example/main.dart

Pour lancer l'ensemble des tests unitaires :

dart test

Licence #

Ce projet est sous licence MIT.