AeThex-OS/AETHEX_QUICKSTART.md

# AeThex Language - Quick Start Guide

## 🎉 Your Cross-Platform Metaverse Language is Ready!

The AeThex programming language compiles to JavaScript, Lua (Roblox), and soon Verse (UEFN) and C# (Unity). It includes built-in modules for authentication, PII protection, COPPA compliance, and cross-platform data sync.

## Installation

### 1. Build the Packages

```bash
# Navigate to the workspace
cd /workspaces/AeThex-OS

# Build the standard library
cd packages/aethex-core
npm install
npm run build

# Build the CLI
cd ../aethex-cli
npm install
npm run build
```

### 2. Test the Compiler

```bash
# From the CLI directory
cd packages/aethex-cli

# Compile to JavaScript
node bin/aethex.js compile ../../examples/hello.aethex

# Compile to Lua (Roblox)
node bin/aethex.js compile ../../examples/hello.aethex --target roblox

# Test the output
cd ../../examples
node -e "$(cat hello.js); Main();"
```

You should see: `Hello, World from AeThex!`

## Language Basics

### Hello World

```aethex
reality HelloWorld {
    platforms: all
}

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

journey Main() {
    platform: all
    Greet("World")
}
```

### Authentication Example

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

reality AuthSystem {
    platforms: [roblox, web]
}

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

### COPPA Compliance Example

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

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

journey SubmitScore(player, playerName, score) {
    platform: roblox
    
    when !Compliance.isCOPPACompliant(player.age) {
        notify "Players under 13 cannot submit scores publicly"
        return
    }
    
    let nameValidation = SafeInput.validate(playerName)
    
    when !nameValidation.valid {
        notify "Invalid name: contains PII"
        return
    }
    
    notify "Score submitted successfully!"
    reveal { player: nameValidation.clean, score: score }
}
```

## CLI Commands

### Compile Files

```bash
# Compile to JavaScript (default)
aethex compile myfile.aethex

# Compile to Lua (Roblox)
aethex compile myfile.aethex --target roblox

# Specify output file
aethex compile myfile.aethex --output game.lua

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

### Create Projects

```bash
# Create new project with default template
aethex new my-project

# Create with Passport authentication
aethex new my-project --template passport

# Create game template
aethex new my-project --template game

# Initialize in current directory
aethex init
```

## Language Features

### Keywords

- **reality** - Define a namespace/module
- **journey** - Define a function
- **when/otherwise** - Conditional statements
- **sync** - Synchronize data across platforms
- **notify** - Output/logging (adapts to platform)
- **reveal** - Return value from journey
- **let** - Variable declaration
- **import/from** - Module imports
- **new** - Create object instances

### Operators

- Arithmetic: `+`, `-`, `*`, `/`
- Comparison: `==`, `!=`, `<`, `>`, `<=`, `>=`
- Logical: `!` (NOT)
- Member: `.` (property access)

### Standard Library Modules

#### Passport - Universal Identity

```aethex
let passport = new Passport("userId", "username")
when passport.verify() {
    notify "User verified!"
}
```

#### SafeInput - PII Detection

```aethex
let result = SafeInput.validate(userInput)
when result.valid {
    notify "Input is safe: " + result.clean
} otherwise {
    notify "Input contains PII"
}
```

#### Compliance - Age Gating

```aethex
when Compliance.isCOPPACompliant(user.age) {
    notify "User is 13 or older"
} otherwise {
    notify "Parental consent required"
}
```

#### DataSync - Cross-Platform Sync

```aethex
sync player.passport across [roblox, web, uefn]
```

## Example Outputs

### JavaScript Output

```javascript
// Generated by AeThex Compiler v1.0.0
// Target: JavaScript

const HelloWorld = {
  platforms: ["all"],
};

function Greet(name) {
  console.log((("Hello, " + name) + " from AeThex!"));
}

function Main() {
  Greet("World");
}
```

### Lua Output (Roblox)

```lua
-- Generated by AeThex Compiler v1.0.0
-- Target: Roblox (Lua)

local HelloWorld = {
  platforms = {"all"},
}

local function Greet(name)
  print((("Hello, " .. name) .. " from AeThex!"))
end

local function Main()
  Greet("World")
end
```

Note: Lua automatically converts operators:
- `+` → `..` (for string concatenation)
- `!` → `not` (logical NOT)
- `!=` → `~=` (not equals)

## Project Structure

```
packages/
├── aethex-core/              # Standard Library
│   ├── src/
│   │   ├── Passport.ts      # Universal identity
│   │   ├── SafeInput.ts     # PII detection
│   │   ├── Compliance.ts    # Age gating
│   │   └── DataSync.ts      # Cross-platform sync
│   └── lib/                 # Compiled output
│
└── aethex-cli/              # Compiler & CLI
    ├── src/
    │   ├── compiler/
    │   │   ├── Lexer.ts           # Tokenizer
    │   │   ├── Parser.ts          # AST builder
    │   │   ├── Compiler.ts        # Orchestrator
    │   │   ├── JavaScriptGenerator.ts
    │   │   └── LuaGenerator.ts
    │   └── index.ts               # CLI entry
    ├── bin/
    │   └── aethex.js              # Executable
    └── lib/                       # Compiled output

examples/
├── hello.aethex             # Hello World
├── auth.aethex              # Authentication
└── leaderboard.aethex       # COPPA compliance
```

## Compilation Flow

```
Source (.aethex)
    ↓
Lexer (Tokenization)
    ↓
Parser (AST Generation)
    ↓
Semantic Analysis
    ↓
Code Generator
    ↓
Output (.js, .lua, .verse, .cs)
```

## Supported Platforms

| Platform | Target | Status | Extension |
|----------|--------|--------|-----------|
| Web | JavaScript | ✅ Ready | `.js` |
| Roblox | Lua | ✅ Ready | `.lua` |
| UEFN | Verse | 🚧 Coming Soon | `.verse` |
| Unity | C# | 🚧 Coming Soon | `.cs` |

## Error Handling

The compiler provides clear error messages with line and column numbers:

```
❌ Compilation failed with errors:

  myfile.aethex - Unexpected character: @ at line 5, column 10
  myfile.aethex - Expected identifier at line 8, column 3
```

## Development Workflow

### 1. Write AeThex Code

```bash
nano myfile.aethex
```

### 2. Compile

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

### 3. Test

```bash
# JavaScript
node myfile.js

# Roblox (copy to Studio)
aethex compile myfile.aethex --target roblox
```

### 4. Watch Mode (Auto-Recompile)

```bash
aethex compile myfile.aethex --watch
```

## Next Steps

1. **Try the Examples**
   ```bash
   cd packages/aethex-cli
   node bin/aethex.js compile ../../examples/auth.aethex
   ```

2. **Create Your First Project**
   ```bash
   aethex new my-first-game
   cd my-first-game
   ```

3. **Read the Full Documentation**
   - [AETHEX_COMPILER_SPEC.md](AETHEX_COMPILER_SPEC.md) - Technical details
   - [AETHEX_LANGUAGE_PACKAGE.md](AETHEX_LANGUAGE_PACKAGE.md) - Language reference
   - [AETHEX_CODE_EXAMPLES.md](AETHEX_CODE_EXAMPLES.md) - Code patterns
   - [AETHEX_IMPLEMENTATION.md](AETHEX_IMPLEMENTATION.md) - Implementation guide

4. **Global Installation** (Coming Soon)
   ```bash
   npm install -g @aethex.os/cli
   aethex --version
   ```

## Troubleshooting

### "npm: command not found"

Install Node.js and npm:
```bash
sudo apk add nodejs npm
```

### "Permission denied"

Create home directory:
```bash
sudo mkdir -p /home/codespace
sudo chown -R $(whoami):$(whoami) /home/codespace
```

### Compilation Errors

Check syntax against examples and ensure proper indentation.

## Contributing

We welcome contributions! Areas to explore:
1. **Verse Generator** - Add UEFN support
2. **C# Generator** - Add Unity support
3. **Optimizations** - Improve code generation
4. **Tests** - Add comprehensive test suite
5. **Documentation** - Create tutorials and guides

## License

MIT License - Copyright © 2025-2026 AeThex Corporation

---

**Happy Coding! Build the next generation of cross-platform metaverse experiences with AeThex!** 🚀

For questions or support, refer to the documentation files or create an issue in the repository.