initial commit

examples/basic_game.py

@@ -0,0 +1,50 @@
+"""Basic example: play a random game of Blokus."""
+import numpy as np
+
+from blokus_gym import BlokusEnv
+
+
+def main():
+    # Create environment with 4 players
+    env = BlokusEnv(num_players=4, board_size=20, render_mode="ansi")
+
+    obs, info = env.reset(seed=42)
+    print("=== Initial State ===")
+    print(env.render())
+
+    total_reward = 0
+    steps = 0
+    terminated = False
+    truncated = False
+
+    while not (terminated or truncated):
+        # Select a random valid action
+        valid_actions = np.where(info["action_mask"])[0]
+        if len(valid_actions) == 0:
+            print("No valid moves!")
+            break
+
+        action = np.random.choice(valid_actions)
+        obs, reward, terminated, truncated, info = env.step(action)
+        total_reward += reward
+        steps += 1
+
+        if steps % 10 == 0:
+            print(f"\n=== Step {steps} ===")
+            print(env.render())
+            print(f"Reward: {reward}, Total: {total_reward}")
+
+    print("\n=== Game Over ===")
+    print(f"Total steps: {steps}")
+    print(f"Total reward: {total_reward}")
+    print(f"Terminated: {terminated}, Truncated: {truncated}")
+
+    # Final state
+    print("\n=== Final Board ===")
+    print(env.render())
+
+    env.close()
+
+
+if __name__ == "__main__":
+    main()

examples/multiagent.py

@@ -0,0 +1,46 @@
+"""Example: multi-agent self-play with BlokusMultiAgentEnv."""
+import numpy as np
+
+from blokus_gym import BlokusMultiAgentEnv, GreedyBot, RandomBot
+
+
+def main():
+    env = BlokusMultiAgentEnv(num_players=2, board_size=7)
+
+    # Create bots for each player
+    bots = {
+        "player_0": RandomBot(player_idx=0, seed=42),
+        "player_1": GreedyBot(player_idx=1),
+    }
+
+    obs, info = env.reset(seed=42)
+    print("=== Multi-Agent Game ===")
+    print(f"Agents: {env.agents}")
+
+    steps = 0
+    while True:
+        for agent in env.agents:
+            obs, info = env.last() if hasattr(env, "last") else (obs.get(agent, {}), {})
+            mask = env.get_action_mask(agent)
+            valid_actions = np.where(mask)[0]
+
+            if len(valid_actions) > 0:
+                bot = bots[agent]
+                action = bot.select_action(env.game, mask)
+                if action is not None:
+                    obs, rewards, terminations, truncations, infos = env.step(action)
+                    steps += 1
+
+                    if terminations[agent]:
+                        print(f"Game over after {steps} steps")
+                        scores = env.game.get_scores()
+                        for i, score in enumerate(scores):
+                            print(f"  Player {i}: {score}")
+                        env.close()
+                        return
+
+    env.close()
+
+
+if __name__ == "__main__":
+    main()

examples/train_sb3.py

@@ -0,0 +1,54 @@
+"""Example: train an agent with Stable-Baselines3 using action masking.
+
+Requires: pip install blokus-gym[train]
+"""
+from stable_baselines3 import PPO
+
+from blokus_gym import ActionMaskWrapper, BlokusEnv
+
+
+def main():
+    # Create environment with ActionMaskWrapper
+    env = BlokusEnv(num_players=2, board_size=7, bot_type=None)
+    env = ActionMaskWrapper(env)
+
+    # Train PPO agent
+    model = PPO(
+        "MultiInputPolicy",
+        env,
+        verbose=1,
+        learning_rate=3e-4,
+        n_steps=2048,
+        batch_size=64,
+        n_epochs=10,
+        gamma=0.99,
+        seed=42,
+    )
+
+    print("Training for 10,000 steps...")
+    model.learn(total_timesteps=10000)
+
+    # Save the model
+    model.save("blokus_ppo_agent")
+
+    # Evaluate
+    obs, info = env.reset(seed=42)
+    total_reward = 0
+    steps = 0
+    terminated = False
+    truncated = False
+
+    while not (terminated or truncated):
+        action, _ = model.predict(obs, deterministic=True)
+        obs, reward, terminated, truncated, info = env.step(action)
+        total_reward += reward
+        steps += 1
+
+    print(f"Evaluation: {steps} steps, reward: {total_reward}")
+
+    # Cleanup
+    env.close()
+
+
+if __name__ == "__main__":
+    main()