AeThex-OS/aethex-docs/README.md

# AeThex Language

**Write once. Build everywhere. Comply by default.**

AeThex is a programming language for cross-platform metaverse development. Write your game logic, authentication, and compliance rules once in AeThex, then compile to JavaScript, Lua (Roblox), Verse (UEFN), and C# (Unity).

```aethex
reality MyGame {
    platforms: [roblox, uefn, web]
}

journey AuthenticatePlayer(username) {
    platform: all
    
    let passport = new Passport(username)
    
    when passport.verify() {
        sync passport across [roblox, uefn, web]
        notify "Welcome, " + username + "!"
    }
}
```

---

## Why AeThex?

### **The Problem**
Building cross-platform games means writing the same code multiple times:
- **Roblox** → Lua
- **UEFN/Fortnite** → Verse/Blueprint
- **Unity/VRChat** → C#
- **Web** → JavaScript

Plus managing compliance (COPPA, FERPA, PII) separately on each platform.

### **The Solution**
Write once in AeThex. Compile to all platforms. Compliance built-in.

---

## Features

🌐 **Cross-Platform Native** - Deploy to Roblox, UEFN, Unity, VRChat, Spatial, Web  
🔄 **State Synchronization** - Sync player data automatically across platforms  
🎫 **Universal Passport** - Single identity system across all metaverse platforms  
🛡️ **Compliance-First** - Built-in COPPA/FERPA/PII protection  
📦 **Standard Library** - Battle-tested utilities for auth, data sync, safety  
⚡ **Modern Syntax** - Readable code that looks like what it does  

---

## Quick Start

### Installation

```bash
# Install globally via npm
npm install -g @aethex.os/cli

# Verify installation
aethex --version
```

### Create Your First Project

```bash
# Create new project
aethex new my-game

# Navigate to project
cd my-game

# Install dependencies
npm install

# Build to JavaScript
npm run build

# Build to Roblox (Lua)
npm run build:roblox
```

### Hello World

Create `hello.aethex`:

```aethex
reality HelloWorld {
    platforms: all
}

journey Greet(name) {
    platform: all
    notify "Hello, " + name + "!"
}
```

Compile it:

```bash
aethex compile hello.aethex
node hello.js
```

---

## Language Syntax

### Realities (Namespaces)

```aethex
reality GameName {
    platforms: [roblox, uefn, web]
    type: "multiplayer"
}
```

### Journeys (Functions)

```aethex
journey ProcessScore(player, score) {
    platform: all
    
    # Automatically scrubs PII before processing
    when score > 1000 {
        notify "High score achieved!"
    }
}
```

### Cross-Platform Sync

```aethex
import { Passport } from "@aethex.os/core"

journey SaveProgress(player) {
    platform: all

    let passport = player.passport
    sync passport across [roblox, uefn, web]
}
```

### Conditional Logic

```aethex
when player.age < 13 {
    # COPPA compliance automatic
    notify "Parent permission required"
} otherwise {
    # Full features unlocked
    reveal player.stats
}
```

### Platform-Specific Code

```aethex
journey DisplayLeaderboard() {
    platform: roblox {
        # Roblox-specific code
        reveal leaderboardGUI
    }
    
    platform: web {
        # Web-specific code
        reveal leaderboardHTML
    }
}
```

---

## Standard Library

### @aethex.os/core

```aethex
import { Passport, DataSync, SafeInput, Compliance } from "@aethex.os/core"

# Passport - Universal identity
let passport = new Passport(userId, username)
passport.verify()
passport.syncAcross([roblox, web])

# DataSync - Cross-platform data
DataSync.sync(playerData, [roblox, uefn])

# SafeInput - PII protection
let result = SafeInput.validate(userInput)
when result.valid {
    # Input is safe
}

# Compliance - COPPA/FERPA checks
when Compliance.isCOPPACompliant(user.age) {
    # Can collect data
}
```

### @aethex.os/roblox

```aethex
import { RemoteEvent, Leaderboard } from "@aethex.os/roblox"

# Roblox-specific features
let event = RemoteEvent.new("PlayerJoined")
event.FireAllClients(player)

let stats = Leaderboard.new("Points", 0)
Leaderboard.updateScore(player, "Points", 100)
```

---

## Examples

### Secure Leaderboard (Foundry Exam)

```aethex
import { SafeInput, Leaderboard } from "@aethex.os/roblox"

reality SecureLeaderboard {
    platforms: [roblox]
}

journey SubmitScore(player, score) {
    platform: roblox
    
    # CRITICAL: Validate input for PII
    let validation = SafeInput.validate(score)
    
    when validation.valid {
        Leaderboard.updateScore(player, "Points", score)
        notify "Score submitted!"
    } otherwise {
        notify "Invalid score: " + validation.message
    }
}
```

### Cross-Platform Authentication

```aethex
import { Passport, DataSync } from "@aethex.os/core"

reality UniversalAuth {
    platforms: [roblox, uefn, web]
}

journey Login(username, password) {
    platform: all
    
    let passport = new Passport(username)
    
    when passport.verify() {
        sync passport across [roblox, uefn, web]
        
        # Pull existing data from any platform
        let playerData = DataSync.pull(passport.userId, "roblox")
        
        notify "Logged in across all platforms!"
        reveal passport
    }
}
```

### COPPA-Compliant User Registration

```aethex
import { Compliance, Passport } from "@aethex.os/core"

journey RegisterUser(username, age) {
    platform: all
    
    when Compliance.isCOPPACompliant(age) {
        # User is 13+, can proceed
        let passport = new Passport(username)
        passport.verify()
        notify "Account created!"
    } otherwise {
        # Under 13, require parent consent
        notify "Parent permission required"
        # Send email to parent (implementation omitted)
    }
}
```

---

## VS Code Extension

Get syntax highlighting, auto-completion, and compile commands:

1. Install from VS Code Marketplace: `AeThex Language Support`
2. Open any `.aethex` file
3. Press `Ctrl+Shift+B` (or `Cmd+Shift+B` on Mac) to compile

**Features:**
- Syntax highlighting
- Auto-completion for keywords
- One-click compilation
- Error underlining
- Snippets

---

## Compilation Targets

| Target | Extension | Use Case |
|--------|-----------|----------|
| JavaScript | `.js` | Web applications, Node.js backends |
| Roblox (Lua) | `.lua` | Roblox games |
| UEFN (Verse) | `.verse` | Fortnite Creative (Coming soon) |
| Unity (C#) | `.cs` | Unity games, VRChat (Coming soon) |

---

## CLI Commands

```bash
# Compile a file
aethex compile myfile.aethex

# Compile to specific target
aethex compile myfile.aethex --target roblox --output game.lua

# Watch mode (recompile on save)
aethex compile myfile.aethex --watch

# Create new project
aethex new my-project

# Initialize in existing directory
aethex init
```

---

## Project Structure

```
my-game/
├── aethex.config.json   # Compilation settings
├── package.json          # npm dependencies
├── src/
│   ├── main.aethex      # Entry point
│   ├── auth.aethex      # Authentication logic
│   └── game.aethex      # Game logic
└── build/
    ├── main.js          # JavaScript output
    └── main.lua         # Roblox output
```

---

## Configuration

**aethex.config.json:**

```json
{
  "targets": ["javascript", "roblox", "uefn"],
  "srcDir": "src",
  "outDir": "build",
  "stdlib": true,
  "compliance": {
    "coppa": true,
    "ferpa": true,
    "piiDetection": true
  }
}
```

---

## For The Foundry Students

AeThex is the official language taught at **The AeThex Foundry** certification program.

### Why Learn AeThex?

1. **One Language, Every Platform** - No need to learn Lua, C#, and JavaScript separately
2. **Compliance Built-In** - Your code is COPPA/FERPA compliant by default
3. **Industry Standard** - AeThex certification recognized by metaverse studios
4. **Future-Proof** - New platforms added as they emerge

### Certification Path

- **Module 1:** AeThex Basics (Syntax, Realities, Journeys)
- **Module 2:** Cross-Platform Development (Sync, Passport)
- **Module 3:** Compliance & Safety (PII, COPPA, FERPA)
- **Final Exam:** Build a PII-safe leaderboard in AeThex

---

## Contributing

AeThex is open source and welcomes contributions!

```bash
# Clone the repo
git clone https://github.com/aethex/aethex-lang.git

# Install dependencies
npm install

# Run tests
npm test

# Build the compiler
npm run build
```

---

## License

MIT License - see [LICENSE](LICENSE) for details

---

## Links

- **Documentation:** https://aethex.dev/lang
- **GitHub:** https://github.com/aethex/aethex-lang
- **VS Code Extension:** [AeThex Language Support](https://marketplace.visualstudio.com/items?itemName=aethex.aethex-language)
- **npm:** [@aethex.os/cli](https://www.npmjs.com/package/@aethex.os/cli)
- **The Foundry:** https://aethex.foundation

---

**Built by The AeThex Foundation** • Empowering the next generation of metaverse developers