mirror of
https://github.com/AeThex-Corporation/AeThex-OS.git
synced 2026-04-17 22:07:20 +00:00
763 lines
17 KiB
Markdown
763 lines
17 KiB
Markdown
# 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.
|