# Nucleation Examples & Documentation

This directory contains comprehensive documentation and working code examples for all Nucleation language bindings.

## 📁 File Structure

```
examples/
├── README.md              # This file
├── rust.md               # Rust API documentation
├── rust_example.rs       # Complete Rust example code
├── wasm.md               # JavaScript/WASM API documentation  
├── wasm_example.js       # Complete JavaScript/WASM example code
├── python.md             # Python API documentation
├── python_example.py     # Complete Python example code
├── ffi.md                # C/FFI API documentation
├── ffi_example.c         # Complete C/FFI example code
└── blockpedia_showcase.rs # Blockpedia integration example (Rust only)
```

## 📖 Documentation vs Examples

Each binding has **two types of resources**:

### 1. 📋 API Documentation (`.md` files)
- **Purpose**: Reference documentation for all available APIs
- **Format**: Structured tables with method signatures and descriptions
- **Usage**: Quick lookup for specific functions, parameters, and return types
- **Examples**: [`rust.md`](rust.md), [`wasm.md`](wasm.md), [`python.md`](python.md), [`ffi.md`](ffi.md)

### 2. 🔧 Working Code Examples (source files)
- **Purpose**: Complete, runnable examples demonstrating real-world usage
- **Format**: Full source code with comments and multiple usage patterns
- **Usage**: Copy-paste starting points, learning comprehensive workflows
- **Examples**: [`rust_example.rs`](rust_example.rs), [`wasm_example.js`](wasm_example.js), [`python_example.py`](python_example.py), [`ffi_example.c`](ffi_example.c)

## 🚀 Running the Examples

### Rust Example
```bash
cargo run --example rust_example
# or
rustc --extern nucleation examples/rust_example.rs && ./rust_example
```

### JavaScript/WASM Example
```bash
# Node.js
node examples/wasm_example.js

# Browser
# Serve the example with a local HTTP server
npx serve . --cors
# Open browser to http://localhost:3000/examples/wasm_example.js
```

### Python Example
```bash
# First install nucleation
pip install nucleation
# or build locally: maturin develop --features python

python examples/python_example.py
```

### C/FFI Example
```bash
# First build the FFI library
cargo build --release --features ffi

# Compile the example
gcc -o ffi_example examples/ffi_example.c \
    -L./target/release -lnucleation \
    -lpthread -ldl -lm

# Run (Linux/macOS)
LD_LIBRARY_PATH=./target/release ./ffi_example

# Run (Windows)
# Add target/release to PATH or copy nucleation.dll to current directory
./ffi_example.exe
```

## 🧪 What Each Example Demonstrates

All examples cover the same comprehensive feature set:

- ✅ **Basic Usage**: Creating schematics, adding blocks
- ✅ **BlockState Management**: Working with block properties
- ✅ **File Operations**: Loading/saving different schematic formats
- ✅ **Advanced Features**: Querying blocks, ASCII visualization, debug info
- ✅ **Chunk Operations**: Working with chunked data and different strategies
- ✅ **Region Copying**: Copying sections between schematics
- ✅ **Error Handling**: Proper error management patterns
- ✅ **Memory Management**: Language-specific resource cleanup

## 🔗 Type Definitions

Generated type definitions are available for type-safe development:

- **TypeScript**: [`../pkg/nucleation.d.ts`](../pkg/nucleation.d.ts) (auto-generated by wasm-pack)
- **Python**: [`../python-stubs/nucleation.pyi`](../python-stubs/nucleation.pyi) (auto-generated from API definition)
- **C**: [`../include/nucleation.h`](../include/nucleation.h) (auto-generated from API definition)
- **Rust**: Native Rust documentation via `cargo doc`

## 🤖 Auto-Generation

All binding documentation and type definitions are **automatically generated** from the single source of truth in [`../src/api_definition.rs`](../src/api_definition.rs).

To regenerate all bindings:
```bash
cargo run --bin generate-bindings
```

This ensures **feature parity** and **consistency** across all language bindings.

## 📊 Feature Matrix

| Feature | Rust | WASM/JS | Python | C/FFI |
|---------|------|---------|--------|-------|
| Core Schematic API | ✅ | ✅ | ✅ | ✅ |
| File I/O | ✅ | ✅ | ✅ | ✅ |
| Block Management | ✅ | ✅ | ✅ | ✅ |
| Chunk Operations | ✅ | ✅ | ✅ | ⚠️ Limited |
| Region Copying | ✅ | ✅ | ✅ | ⚠️ Limited |
| Blockpedia Integration | ✅ | ❌ | ❌ | ❌ |
| Memory Safety | ✅ | ✅ | ✅ | ⚠️ Manual |

**Note**: Blockpedia integration (color analysis, block transformations) is only available on native Rust targets due to WASM compatibility constraints.

## 💡 Getting Help

1. **Quick Reference**: Check the `.md` documentation files
2. **Working Examples**: Run the example source files
3. **Type Safety**: Use the generated type definitions
4. **API Report**: See [`../API_REPORT.md`](../API_REPORT.md) for a complete API overview
5. **Issues**: Report problems on [GitHub Issues](https://github.com/Schem-at/Nucleation/issues)

Happy building! 🎉
