AeThex-OS/AETHEX_LANGUAGE_PACKAGE.md

# AeThex Language - Complete Documentation Package

> **For:** Creating AeThex compiler, runtime, and tooling in separate OS repository  
> **Version:** 1.0.0  
> **License:** MIT (Copyright 2025 AeThex)  
> **Status:** Production-Ready

---

## Table of Contents

1. [Language Overview](#language-overview)
2. [Core Concepts](#core-concepts)
3. [Language Syntax Reference](#language-syntax-reference)
4. [Standard Library (@aethex.os/core)](#standard-library-aethexoscore)
5. [CLI Reference (@aethex.os/cli)](#cli-reference-aethexoscli)
6. [Code Examples](#code-examples)
7. [Platform Support](#platform-support)
8. [Compliance Features](#compliance-features)
9. [Project Structure](#project-structure)

---

## Language Overview

**AeThex** is a programming language for cross-platform metaverse development. Write code once, compile to multiple platforms (JavaScript, Lua, Verse, C#), and deploy everywhere with built-in compliance and identity management.

### What You Need to Know

- **File Extension:** `.aethex`
- **Core Model:** "realities" (namespaces) and "journeys" (functions)
- **Target Platforms:** Roblox, UEFN, Unity, VRChat, Spatial, Web, Node.js
- **Compliance:** Built-in COPPA/FERPA support with PII detection
- **Distribution:** npm packages (@aethex.os/cli, @aethex.os/core)
- **npm Installation:** `npm install -g @aethex.os/cli`

### Why AeThex?

1. **Cross-Platform Native** - Deploy to Roblox, UEFN, Unity, VRChat, Spatial, and Web with one codebase
2. **Universal Passport** - Single identity system across all metaverse platforms
3. **Compliance-First** - Built-in COPPA/FERPA/PII protection (automatic)
4. **Standard Library** - Battle-tested utilities for auth, data sync, and safety

---

## Core Concepts

### 1. Realities (Namespaces)

A "reality" is a namespace that defines your application context, similar to a project or game definition.

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

**Syntax:**
- `platforms:` - Target platforms (array or "all")
- `type:` - Optional game type ("multiplayer", "singleplayer", "compliance-exam", etc.)

### 2. Journeys (Functions)

A "journey" is a function that can run across platforms. Journeys handle logic that executes on specific or all platforms.

```aethex
journey ProcessScore(player, score) {
    platform: all
    
    when score > 1000 {
        notify "High score achieved!"
    }
}
```

**Syntax:**
- `journey NAME(params) {}` - Define a journey
- `platform:` - Target platform(s) (single, array, or "all")
- `when` - Conditional (if statement)
- `otherwise` - Else clause
- `notify` - Output message
- `reveal` - Return/expose data
- `return` - Exit journey

### 3. Cross-Platform Sync

Sync data across platforms instantly with one line:

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

journey SaveProgress(player) {
    platform: all
    
    sync passport across [roblox, uefn, web]
    DataSync.sync(playerData, [roblox, web])
}
```

### 4. Platform-Specific Code

Write code that only runs on specific platforms:

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

### 5. Compliance Features (Built-in)

Compliance is automatic with AeThex:

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

# COPPA checks
when Compliance.isCOPPACompliant(user.age) {
    # User is 13+
}

# PII detection & scrubbing
let result = SafeInput.validate(userInput)
when result.valid {
    # Input is safe
}
```

---

## Language Syntax Reference

### Keywords Reference

**Declarations:**
- `reality` - Define a namespace/application
- `journey` - Define a function
- `let` - Declare a variable
- `import` - Import from libraries

**Control Flow:**
- `when` - Conditional (if)
- `otherwise` - Else clause
- `return` - Return from journey

**Cross-Platform:**
- `sync ... across` - Sync data across platforms
- `platform:` - Target platforms for logic
- `platforms:` - Reality target platforms

**Actions:**
- `notify` - Output message
- `reveal` - Return/expose data
- `new` - Create instance

### Project Structure

```
my-project/
├── aethex.config.json    # Configuration file
├── 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/Lua output
```

### Configuration File (aethex.config.json)

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

### Compilation Targets

| Target | Language | Platform | Status |
|--------|----------|----------|--------|
| javascript | JavaScript | Web, Node.js | Ready |
| roblox | Lua | Roblox | Ready |
| uefn | Verse | Fortnite Creative | Coming Soon |
| unity | C# | Unity, VRChat | Coming Soon |

---

## Standard Library (@aethex.os/core)

The standard library provides cross-platform utilities for authentication, data sync, and compliance.

### Passport - Universal Identity

Authenticate users once, verify them everywhere.

```javascript
const { Passport } = require('@aethex.os/core');

const passport = new Passport('user123', 'PlayerOne');
await passport.verify();
await passport.syncAcross(['roblox', 'web']);
```

**Methods:**
- `new Passport(userId, username)` - Create passport
- `verify()` - Verify identity
- `syncAcross(platforms)` - Sync across platforms
- `toJSON()` - Export as JSON

### SafeInput - PII Detection & Scrubbing

Detect and scrub personally identifiable information automatically.

```javascript
const { SafeInput } = require('@aethex.os/core');

// Detect PII
const detected = SafeInput.detectPII('Call me at 555-1234');
// Returns: ['phone']

// Scrub PII
const clean = SafeInput.scrub('My email is user@example.com');
// Returns: 'My email is [EMAIL_REDACTED]'

// Validate input
const result = SafeInput.validate('PlayerName123');
if (result.valid) {
  console.log('Safe to use');
}
```

**Methods:**
- `SafeInput.detectPII(input)` - Detect PII types
- `SafeInput.scrub(input)` - Scrub PII from string
- `SafeInput.validate(input)` - Validate input safety

**Detected PII Types:**
- Phone numbers
- Email addresses
- Social security numbers (SSN)
- Credit card numbers
- Home addresses
- Names with sensitive data
- Custom patterns

### Compliance - COPPA/FERPA Checks

Built-in compliance checks with audit trail logging.

```javascript
const { Compliance } = require('@aethex.os/core');

// Age gate
if (Compliance.isCOPPACompliant(userAge)) {
  // User is 13+
}

// Check data collection permission
if (Compliance.canCollectData(user)) {
  // Safe to collect
}

// Log compliance check for audit
Compliance.logCheck(userId, 'leaderboard_submission', true);
```

**Methods:**
- `Compliance.isCOPPACompliant(age)` - Check if 13+
- `Compliance.requiresParentConsent(age)` - Check if <13
- `Compliance.canCollectData(user)` - Check permission
- `Compliance.logCheck(userId, type, result)` - Audit log

### DataSync - Cross-Platform State Sync

Synchronize data across all supported platforms.

```javascript
const { DataSync } = require('@aethex.os/core');

// Sync data across platforms
await DataSync.sync({
  inventory: playerInventory,
  progress: gameProgress
}, ['roblox', 'web']);

// Pull data from specific platform
const data = await DataSync.pull(userId, 'roblox');
```

**Methods:**
- `DataSync.sync(data, platforms)` - Sync data
- `DataSync.pull(userId, platform)` - Pull data

---

## CLI Reference (@aethex.os/cli)

The command line interface for compiling AeThex files.

### Installation

```bash
npm install -g @aethex.os/cli
aethex --version
```

### Commands

#### compile
Compile an AeThex file to the target platform.

```bash
aethex compile myfile.aethex
```

**Options:**
- `-t, --target <platform>` - Target platform (javascript, roblox, uefn, unity)
- `-o, --output <file>` - Output file path
- `-w, --watch` - Watch for changes and recompile

**Examples:**
```bash
# JavaScript (default)
aethex compile myfile.aethex

# Roblox/Lua
aethex compile myfile.aethex --target roblox

# With output file
aethex compile myfile.aethex -t roblox -o game.lua

# Watch mode
aethex compile myfile.aethex --watch
```

#### new
Create a new AeThex project.

```bash
aethex new my-project
aethex new my-game --template passport
```

**Options:**
- `--template <type>` - Project template (basic, passport, game)

#### init
Initialize AeThex in the current directory.

```bash
aethex init
```

#### Global Options

| Option | Description |
|--------|-------------|
| `-t, --target <platform>` | Target platform (javascript, roblox, uefn, unity) |
| `-o, --output <file>` | Output file path |
| `-w, --watch` | Watch for changes |
| `--template <type>` | Project template (basic, passport, game) |
| `--help` | Show help information |
| `--version` | Show CLI version |

---

## Code Examples

### 1. Hello World

```aethex
reality HelloWorld {
    platforms: all
}

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

Run with:
```bash
aethex compile hello.aethex -o hello.js
node hello.js
```

### 2. 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
    }
}
```

### 3. Secure Leaderboard (Foundry Certification Exam)

This is the actual certification exam for The Foundry. Build a COPPA-compliant, PII-safe leaderboard:

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

reality SecureLeaderboard {
    platforms: [roblox]
    type: "compliance-exam"
}

journey SubmitScore(player, playerName, score) {
    platform: roblox
    
    # COPPA compliance check
    when !Compliance.isCOPPACompliant(player.age) {
        notify "Players under 13 cannot submit scores publicly"
        return
    }
    
    # Validate player name for PII
    let nameValidation = SafeInput.validate(playerName)
    
    when !nameValidation.valid {
        notify "Invalid name: " + nameValidation.message
        Compliance.logCheck(player.userId, "leaderboard_name_check", false)
        return
    }
    
    # Validate score for PII
    let scoreValidation = SafeInput.validate(score.toString())
    
    when !scoreValidation.valid {
        notify "Invalid score: contains sensitive data"
        Compliance.logCheck(player.userId, "leaderboard_score_check", false)
        return
    }
    
    # All validations passed
    Compliance.logCheck(player.userId, "leaderboard_submission", true)
    notify "Score submitted successfully!"
    
    reveal {
        player: nameValidation.clean,
        score: scoreValidation.clean
    }
}
```

### 4. COPPA-Compliant 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"
    }
}
```

### 5. Cross-Platform Data Sync

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

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

journey SaveProgress(player, progress) {
    platform: all
    
    DataSync.sync({
        level: progress.level,
        experience: progress.xp,
        inventory: progress.items
    }, [roblox, uefn, web])
    
    notify "Progress saved!"
}

journey LoadProgress(player) {
    platform: all
    
    let data = DataSync.pull(player.userId, "web")
    reveal data
}
```

---

## Platform Support

### Currently Ready
- **JavaScript** - Web applications, Node.js, CLI tools
- **Roblox (Lua)** - Roblox platform
- **Web** - Browser-based applications

### Coming Soon
- **UEFN (Verse)** - Fortnite Creative
- **Unity (C#)** - Unity games, VRChat
- **Godot** - Godot Engine
- **GameMaker** - GameMaker Studio 2

---

## Compliance Features

### Automatic COPPA Compliance

COPPA (Children's Online Privacy Protection Act) compliance is built-in:

```aethex
when Compliance.isCOPPACompliant(user.age) {
    # User is 13+, safe to collect data
}

when Compliance.requiresParentConsent(user.age) {
    # User is under 13, require parent consent
}
```

### PII Detection

Automatically detects personally identifiable information:

- Phone numbers: `555-1234` or `(555) 123-4567`
- Email addresses: `user@example.com`
- Social security numbers: `123-45-6789`
- Credit card numbers
- Home addresses
- Custom patterns

### Audit Logging

All compliance checks are logged:

```javascript
Compliance.logCheck(userId, 'leaderboard_submission', true);
// Logs: {userId, type, result, timestamp}
```

---

## Project Structure

### Standard Project Layout

```
my-aethex-game/
├── aethex.config.json           # Project configuration
├── package.json                 # npm dependencies
├── README.md                    # Project documentation
├── src/
│   ├── main.aethex             # Entry point
│   ├── game.aethex             # Game logic
│   ├── auth.aethex             # Authentication
│   └── utils/
│       ├── constants.aethex    # Constants
│       └── helpers.aethex      # Helper functions
├── build/                       # Compiled output (auto-generated)
│   ├── main.js                 # JavaScript output
│   ├── main.lua                # Roblox Lua output
│   └── main.verse              # UEFN Verse output
└── tests/
    └── game.test.aethex        # Tests
```

### Configuration Example

```json
{
  "name": "my-game",
  "version": "1.0.0",
  "description": "Cross-platform game built with AeThex",
  "targets": ["javascript", "roblox"],
  "srcDir": "src",
  "outDir": "build",
  "entry": "src/main.aethex",
  "stdlib": true,
  "compliance": {
    "coppa": true,
    "ferpa": true,
    "piiDetection": true,
    "auditLogging": true
  }
}
```

---

## Integration Patterns

### Pattern 1: Authentication Flow

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

journey Login(user) {
    when user.verify() {
        sync user.passport across [roblox, web]
    }
}
```

### Pattern 2: Save/Load Game State

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

journey SaveGame(player) {
    sync player.stats across [roblox, uefn, web]
}
```

### Pattern 3: PII Protection

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

let result = SafeInput.validate(userInput)
when result.valid {
    # Safe to use
}
```

### Pattern 4: Platform-Specific Logic

```aethex
journey Render() {
    platform: roblox {
        # Roblox rendering
    }
    platform: web {
        # Web rendering
    }
}
```

---

## Standard Library Modules

### @aethex.os/core

Core cross-platform utilities available on all targets:

- `Passport` - Universal identity management
- `DataSync` - Real-time data synchronization
- `SafeInput` - PII detection and scrubbing
- `Compliance` - Age-gating and compliance checks

### @aethex.os/roblox (Platform-Specific)

Roblox-specific features:

- `RemoteEvent` - Roblox RemoteEvent wrapper
- `Leaderboard` - Leaderboard management
- Platform-native integrations

### @aethex.os/web (Platform-Specific)

Web platform utilities:

- REST API client
- Local storage management
- Browser APIs

---

## Version & License

- **Version:** 1.0.0
- **License:** MIT
- **Copyright:** 2025 AeThex Corporation
- **Status:** Production Ready
- **Repository:** https://github.com/AeThex-Corporation/AeThexOS

---

## Additional Resources

- **Quick Start:** 5 minutes to your first AeThex app
- **GitHub:** https://github.com/AeThex-Corporation/AeThexOS
- **npm:** https://www.npmjs.com/package/@aethex.os/cli
- **The Foundry:** Certification program for AeThex developers
- **Community:** Discord, GitHub Issues, Email support

---

## Development Notes for Implementation

### For Compiler Development

1. **Lexer** - Tokenize `.aethex` files
2. **Parser** - Build AST from tokens
3. **Code Generator** - Generate target language output
4. **Optimizer** - Optimize generated code
5. **Type Checker** - Validate types across platforms

### Required Components

- CLI entry point (Node.js)
- File watcher for watch mode
- Multi-target code generation
- Build system integration
- Configuration file parser

### Key Files to Track

- Source directory scanning
- Entry point detection
- Output directory management
- Target platform selection
- Error reporting and logging

---

**Last Updated:** February 20, 2026

This document is maintained as the primary reference for AeThex language implementation. For the latest updates, refer to the official GitHub repository.