AeThex-Engine-Core/docs/AETHEX_LANG_INTEGRATION.md

# AeThex Language Integration

AeThex Engine includes deep integration with **AeThex Lang**, a cross-platform scripting language that compiles to multiple game engine targets.

## Overview

AeThex Lang allows you to write game logic once and deploy it to:
- **Roblox** (Luau)
- **UEFN/Fortnite** (Verse)
- **Unity** (C#)
- **Web** (JavaScript)
- **AeThex Engine** (Native VM)

## Language Features

### Reality Blocks (Modules)
```aethex
reality MyGame {
    platforms: [roblox, uefn, unity, web]
    
    // Module content
}
```

### Journey Functions
Cross-platform functions that work identically across all targets:
```aethex
journey calculateDamage(baseDamage: Number, multiplier: Number) {
    reveal baseDamage * multiplier
}
```

### Beacons (Signals)
Events that can be emitted and listened to:
```aethex
beacon onPlayerDied(playerId: String)
beacon onScoreChanged(newScore: Number)

// Emit a beacon
emit onPlayerDied("player_123")
```

### Artifacts (Classes)
Object-oriented classes:
```aethex
artifact Player {
    let health: Number = 100
    let name: String = "Player"
    
    journey takeDamage(amount: Number) {
        health = health - amount
        when health <= 0 {
            notify `${name} died!`
        }
    }
}
```

### Control Flow
```aethex
// Conditionals
when condition {
    // true branch
} otherwise {
    // false branch
}

// Loops
traverse item in collection {
    notify item
}

while isRunning {
    // loop body
}
```

### Cross-Platform Sync
```aethex
// Sync data across all platforms
sync playerData across all

// Sync to specific platforms
sync inventory across [roblox, uefn]
```

### Platform-Specific Code
```aethex
@platform(roblox)
journey robloxOnly() {
    // Only runs on Roblox
}

@platform(unity)
journey unityOnly() {
    // Only runs on Unity
}
```

## Type System

| AeThex Type | Roblox | UEFN | Unity | JavaScript |
|-------------|--------|------|-------|------------|
| Number | number | float | float | number |
| String | string | string | string | string |
| Boolean | boolean | logic | bool | boolean |
| Array | table | array | List<T> | Array |
| Dictionary | table | map | Dictionary<K,V> | Object |
| Vector2 | Vector2 | vector2 | Vector2 | {x,y} |
| Vector3 | Vector3 | vector3 | Vector3 | {x,y,z} |

## Built-in Functions

| AeThex | Description |
|--------|-------------|
| `notify(msg)` | Print to console/log |
| `reveal value` | Return from function |
| `emit beacon(args)` | Emit a signal |
| `await task()` | Async wait |
| `sync data across targets` | Cross-platform sync |

## Using in Editor

1. Create a new file with `.aethex` extension
2. Write your cross-platform code
3. The editor provides syntax highlighting
4. Export to any target platform using the Export menu

## Export Targets

### Roblox Export
Generates `.lua` files compatible with Roblox Studio:
```lua
-- Generated from player.aethex
local Player = {}

function Player.takeDamage(amount)
    -- Implementation
end

return Player
```

### UEFN Export
Generates `.verse` files for Unreal Editor for Fortnite:
```verse
# Generated from player.aethex
using { /Fortnite.com/Devices }

player_device := class(creative_device):
    TakeDamage(Amount : float)<suspends> : void =
        # Implementation
```

### Unity Export
Generates `.cs` files for Unity:
```csharp
// Generated from player.aethex
using UnityEngine;

public class Player : MonoBehaviour
{
    public void TakeDamage(float amount)
    {
        // Implementation
    }
}
```

### Web Export
Generates JavaScript bundle:
```javascript
// Generated from player.aethex
const Player = {
    takeDamage(amount) {
        // Implementation
    }
};
export default Player;
```

## Module Structure

```
modules/aethex_lang/
├── register_types.cpp/h    # Module registration
├── aethex_script.cpp/h     # Script resource class
├── aethex_tokenizer.cpp/h  # Lexer
├── aethex_parser.cpp/h     # AST parser
├── aethex_compiler.cpp/h   # Bytecode + cross-platform compiler
├── aethex_vm.cpp/h         # Virtual machine
├── editor/
│   └── aethex_highlighter.cpp/h  # Syntax highlighting
├── export/
│   └── aethex_exporter.cpp/h     # Cross-platform export
└── examples/
    └── cross_platform_player.aethex
```

## Integration with AeThex Ecosystem

- **AeThex Studio**: Templates use AeThex Lang for cross-platform logic
- **AeThex Forge**: Marketplace assets can include `.aethex` scripts
- **AeThex Launcher**: Build and deploy AeThex Lang projects