nucleation 0.1.58

A high-performance Minecraft schematic parser and utility library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

# 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! 🎉