3a8b2efd-8df2-4277-9336-5d97408d6574

2025-08-13 23:27:08 +00:00
parent 77cd457a50
commit 7a4a9be611
19 changed files with 1003 additions and 1009 deletions
--- a/examples/README.md
+++ b/examples/README.md
@@ -0,0 +1,127 @@
+# Examples Directory (`examples/`)
+
+This directory contains example programs and tutorials demonstrating how to use the Pokemon battle simulator.
+
+## Structure
+
+```
+examples/
+├── basic/                 # Basic usage examples
+│   ├── hello_battle.cpp   # Simplest possible battle
+│   ├── pokemon_creation.cpp # Creating and configuring Pokemon
+│   ├── move_usage.cpp     # Using moves and calculating damage
+│   └── type_effectiveness.cpp # Type matchup examples
+├── intermediate/          # More complex examples
+│   ├── tournament.cpp     # Tournament simulation
+│   ├── ai_comparison.cpp  # Comparing different AI strategies
+│   ├── custom_pokemon.cpp # Loading custom Pokemon data
+│   └── battle_analytics.cpp # Analyzing battle statistics
+├── advanced/              # Advanced usage patterns
+│   ├── custom_ai.cpp      # Implementing custom AI
+│   ├── parallel_battles.cpp # Multi-threaded battle simulation
+│   ├── memory_optimization.cpp # Memory-efficient patterns
+│   └── performance_tuning.cpp # Performance optimization
+├── data/                  # Example data files
+│   ├── sample_pokemon.json # Sample Pokemon definitions
+│   ├── custom_moves.json   # Custom move examples
+│   └── test_scenarios.json # Battle test scenarios
+├── python/                # Python integration examples
+│   ├── wrapper_usage.py   # Using Python bindings
+│   ├── data_analysis.py   # Battle result analysis
+│   └── visualization.py   # Battle visualization
+└── CMakeLists.txt         # Build configuration for examples
+```
+
+## Example Categories
+
+### Basic Examples
+Perfect for developers new to the library:
+- **hello_battle.cpp**: Minimal battle between two Pokemon
+- **pokemon_creation.cpp**: Different ways to create Pokemon instances
+- **move_usage.cpp**: How moves work and damage calculation
+- **type_effectiveness.cpp**: Understanding the type system
+
+### Intermediate Examples
+For developers comfortable with the basics:
+- **tournament.cpp**: Simulate a complete tournament bracket
+- **ai_comparison.cpp**: Compare performance of different AI strategies
+- **custom_pokemon.cpp**: Load and use custom Pokemon data
+- **battle_analytics.cpp**: Collect and analyze battle statistics
+
+### Advanced Examples
+For experienced users and contributors:
+- **custom_ai.cpp**: Implement sophisticated AI strategies
+- **parallel_battles.cpp**: Optimize performance with multithreading
+- **memory_optimization.cpp**: Minimize memory usage patterns
+- **performance_tuning.cpp**: Squeeze maximum performance
+
+## Building Examples
+
+```bash
+# Build all examples
+mkdir build && cd build
+cmake -DBUILD_EXAMPLES=ON ..
+make
+
+# Run a specific example
+./examples/basic/hello_battle
+
+# Build only specific examples
+make hello_battle tournament
+```
+
+## Example Template
+
+Each example follows this structure:
+```cpp
+/**
+ * @file example_name.cpp
+ * @brief Brief description of what this example demonstrates
+ * 
+ * Detailed explanation of the concepts covered, expected output,
+ * and any prerequisites or setup required.
+ */
+
+#include <pokemon_sim/pokemon_sim.h>
+#include <iostream>
+
+int main() {
+    // Clear, commented code demonstrating the concept
+    // with realistic usage patterns
+    
+    return 0;
+}
+```
+
+## Data Files
+
+The `data/` subdirectory contains:
+- **Minimal datasets** for quick examples
+- **Complete scenarios** for comprehensive demonstrations
+- **Custom data examples** showing data format flexibility
+- **Test cases** that can be used for validation
+
+## Python Integration
+
+Python examples demonstrate:
+- **C++ binding usage** with pybind11
+- **Data analysis** of battle results using pandas
+- **Visualization** of battle statistics and AI performance
+- **Integration** with machine learning libraries
+
+## Running Examples
+
+Each example is self-contained and includes:
+- **Clear output** explaining what's happening
+- **Error handling** for educational purposes
+- **Performance metrics** where relevant
+- **Cleanup code** demonstrating proper resource management
+
+## Contributing Examples
+
+When adding new examples:
+- **Focus on one concept** per example
+- **Include comprehensive comments** explaining the code
+- **Provide expected output** in comments or separate files
+- **Test thoroughly** to ensure examples work correctly
+- **Keep dependencies minimal** to reduce complexity