# Unreal MCP WASM Module
WebAssembly module providing high-performance operations for the Unreal Engine MCP Server.
## Features
- **Property Parser**: Efficient JSON property parsing and serialization
- **Transform Math**: Optimized 3D vector and matrix operations
- **Dependency Resolver**: Asset dependency graph traversal and analysis
- **Utils**: Common mathematical utilities
## Prerequisites
- Rust (latest stable)
- wasm-pack
- Node.js (for integration testing)
## Build Instructions
### Install wasm-pack
```bash
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
```
### Build for Release
```bash
wasm-pack build --release --target web
```
This creates a `pkg/` directory with:
- `unreal_mcp_wasm.js` - JavaScript bindings
- `unreal_mcp_wasm_bg.wasm` - Compiled WebAssembly binary
- `unreal_mcp_wasm.d.ts` - TypeScript definitions
### Build for Development
```bash
wasm-pack build --dev --target web --watch
```
The `--watch` flag enables hot reloading during development.
### Testing
```bash
# Run Rust tests
cargo test
# Run integration tests
wasm-pack test --headless --firefox
```
## Usage
### In TypeScript
```typescript
import init, {
PropertyParser,
TransformCalculator,
Vector
} from './pkg/unreal_mcp_wasm.js';
async function main() {
await init();
// Property parsing
const parser = new PropertyParser();
const json = '{"name": "Test", "value": 42}';
const result = parser.parse_properties(json);
console.log(result);
// Vector math
const v1 = new Vector(1, 2, 3);
const v2 = new Vector(4, 5, 6);
const sum = v1.add(v2);
console.log(sum); // { x: 5, y: 7, z: 9 }
// Transform calculations
const calculator = new TransformCalculator();
const location = [100, 200, 300];
const rotation = [0, 90, 0];
const scale = [1, 1, 1];
const matrix = calculator.compose_transform(location, rotation, scale);
console.log(matrix);
}
main();
```
## API Reference
### PropertyParser
```typescript
new PropertyParser(maxDepth?: number)
parse_properties(jsonStr: string, maxDepth?: number): Promise<ParseResult>
serialize_properties(properties: JsValue): Promise<string>
extract_property_names(jsonStr: string): Promise<string[]>
get_property_type(jsonStr: string): string
```
### TransformCalculator
```typescript
new TransformCalculator()
compose_transform(location: [number, number, number], rotation: [number, number, number], scale: [number, number, number]): number[]
decompose_matrix(matrix: number[]): number[]
apply_transform(point: number[], transform: number[]): number[]
```
### Vector
```typescript
new Vector(x: number, y: number, z: number)
add(other: Vector): Vector
subtract(other: Vector): Vector
multiply(other: Vector): Vector
scale(scalar: number): Vector
dot(other: Vector): number
cross(other: Vector): Vector
length(): number
normalize(): Vector
distance_to(other: Vector): number
lerp(other: Vector, t: number): Vector
to_array(): number[]
```
### DependencyResolver
```typescript
new DependencyResolver(maxDepth?: number)
analyze_dependencies(assetPath: string, dependenciesJson: string, maxDepth?: number): Promise<DependencyAnalysis>
find_dependents(assetPath: string, dependenciesJson: string): string[]
calculate_depth(assetPath: string, dependenciesJson: string, maxDepth?: number): number
find_circular_dependencies(dependenciesJson: string, maxDepth?: number): string[][]
topological_sort(dependenciesJson: string): string[]
```
### Utils
```typescript
now(): number
random(): number
clamp(value: number, min: number, max: number): number
lerp(a: number, b: number, t: number): number
deg_to_rad(degrees: number): number
rad_to_deg(radians: number): number
```
### Metrics
```typescript
new Metrics()
record(name: string, durationMs: number): void
average_for(name: string): number
count(): number
clear(): void
```
## Performance
### Benchmarks (Approximate)
| Operation | WASM | TypeScript | Speedup |
|-----------|------|------------|---------|
| Parse 1000 properties | 20-40ms | 150-300ms | **5-8x** |
| Vector operations (1000) | 1-2ms | 5-10ms | **5x** |
| Transform composition | 0.5ms | 5ms | **10x** |
| Dependency analysis | 10-20ms | 50-100ms | **5x** |
## Limitations
1. Requires WebAssembly support (all modern browsers)
2. Limited to f32 for floating-point operations (performance optimization)
3. Maximum recursion depth defaults to 100 (configurable)
## Troubleshooting
### Build Errors
**Error: `wasm-pack` not found**
```bash
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
```
**Error: `cargo` not found**
Install Rust from https://rustup.rs/
### Runtime Errors
**Error: "WebAssembly module not initialized"**
```typescript
await init(); // Must be called before using WASM functions
```
**Error: "Maximum nesting depth exceeded"**
```typescript
const parser = new PropertyParser(200); // Increase max depth
```
## Development
### Project Structure
```
wasm/
├── src/
│ ├── lib.rs # Entry point
│ ├── property_parser.rs # Property parsing
│ ├── transform_math.rs # Vector/matrix math
│ └── dependency_resolver.rs # Dependency graphs
├── tests/
│ └── integration.rs # Integration tests
├── Cargo.toml # Rust configuration
└── README.md # This file
```
### Adding New Functions
1. Add function to appropriate module
2. Mark with `#[wasm_bindgen]`
3. Build with `wasm-pack build --dev`
4. Run tests with `cargo test`
### Code Style
- Use `f32` for floating-point numbers
- Prefer simple types over complex generics
- Add documentation comments
- Include tests for new functionality
## License
MIT
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run `cargo test`
6. Submit a pull request
## See Also
- [WebAssembly.org](https://webassembly.org/)
- [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/)
- [wasm-pack](https://rustwasm.github.io/wasm-pack/)
- [serde](https://serde.rs/)
