lt-script 1.0.1 → 1.0.5

package/README.md

@@ -1,33 +1,566 @@
-# LT Language Compiler
+# LT Language
 
-A compiler for the LT language, targeting FiveM Lua.
+<p align="center">
+  <img src="https://img.shields.io/npm/v/lt-script?color=blue&label=npm" alt="npm version">
+  <img src="https://img.shields.io/github/license/laot7490/lt-script" alt="license">
+  <img src="https://img.shields.io/badge/FiveM-Ready-green" alt="FiveM Ready">
+</p>
 
-## Installation
+**LT** is a modern, statically-typed superset of Lua designed specifically for **FiveM development**. It combines the elegance of TypeScript with the performance of Lua, adding FiveM-specific syntactic sugar to make your scripts robust, readable, and faster to write.
+
+> **Goodbye boilerplate, hello productivity.**  
+> Write clean, type-safe code that compiles to optimized 100% vanilla Lua.
+
+---
+
+## ✨ Why LT?
+
+*   **🛡️ Type Safety**: Catch type mismatches and `nil` errors *before* you run the game.
+*   **⚡ Modern Syntax**: Use Arrow Functions, Destructuring, Spread syntax, and more.
+*   **🎮 FiveM-First**: Built-in keywords like `netevent`, `addcmd`, `thread`, and `wait`.
+*   **🔌 Zero Overhead**: Compiles to pure, readable Lua with no runtime dependencies.
+
+---
+
+## 📦 Installation
+
+Prerequisites: [Node.js](https://nodejs.org/) (Version 16+)
 
 ```bash
+# Global installation (Recommended)
 npm install -g lt-script
+
+# OR run directly via npx
+npx lt-script build .
 ```
 
-## Usage
+---
+
+## 🚀 Quick Start
 
+Create a `client.lt` file:
+
+```typescript
+// Define a type for player data
+interface PlayerData {
+    id: number,
+    name: string,
+    health: number
+}
+
+// Variables with types
+let active: boolean = false
+const MAX_HEALTH = 100
+
+// FiveM Command
+addcmd "heal" (source, args)
+    let amount = tonumber(args[1]) ?? MAX_HEALTH
+    SetEntityHealth(PlayerPedId(), amount)
+    print("Healed for ${amount}")
+end
+
+// Thread with loop
+thread
+    print("System active")
+    loop (true)
+        wait 1000
+        if LocalPlayer.state?.isDead then
+            print("Player is dead!")
+        end
+    end
+end
+```
+
+**Compile it:**
 ```bash
-ltc help
+ltc build .
 ```
 
-### Compiler
+---
 
-```bash
-ltc build <sourceDir> <outDir>
+## 📘 Language Reference
+
+### 1. Variables & Types
+
+LT supports explicit typing with compile-time validation.
+
+```typescript
+// Mutable variables
+let score: number = 0
+var playerName: string = "John"     // Type inferred if omitted
+
+// Constants (Compiles to Lua 5.4 <const>)
+const MAX_PLAYERS = 32
+
+// Available primitive types
+let str: string = "hello"
+let num: number = 42
+let flag: boolean = true
+let data: table = { key: "value" }
+let pos: vector3 = <100.0, 200.0, 30.0>
+let callback: function = () => print("hi")
+
+// Arrays
+let inventory: string[] = ["Apple", "Water"]
+let numbers: number[] = [1, 2, 3]
 ```
 
-### Watch Mode
+### 2. Interfaces & Type Aliases
 
-```bash
-ltc watch <sourceDir> <outDir>
+Define complex data structures for compile-time validation.
+
+```typescript
+// Interface - Object shape definition
+interface VehicleConfig {
+    model: string,
+    price: number,
+    color: string
+}
+
+// Type Alias - Alternative syntax
+type PlayerPos = { x: number, y: number, z: number }
+
+// Usage with validation
+const myCar: VehicleConfig = {
+    model: "sultan",
+    price: 50000,
+    color: "red"
+}
+
+// Arrays of interfaces
+interface StoreConfig {
+    id: number,
+    position: vector3,
+    isOpen: boolean
+}
+
+const Stores: StoreConfig[] = [
+    { id: 1, position: <100.0, 200.0, 30.0>, isOpen: true },
+    { id: 2, position: <150.0, 250.0, 35.0>, isOpen: false }
+]
+```
+
+> **Note:** Type validation ensures field types match. Assigning `number` to a `vector3` field will cause a compile error.
+
+### 3. Functions
+
+```typescript
+// Standard function with typed parameters
+func Add(a: number, b: number)
+    return a + b
+end
+
+// Default parameters
+func Greet(name: string, prefix = "Hello")
+    print("${prefix}, ${name}!")
+end
+
+// Local function (Lua local function)
+local function PrivateHelper()
+    return "internal"
+end
+
+// Arrow functions
+let double = (x: number) => x * 2
+let greet = (name) => print("Hello ${name}")
+
+// Multi-line arrow
+let process = (data) => {
+    let result = data * 2
+    return result
+}
+```
+
+### 4. Control Flow
+
+#### If / Else
+```typescript
+// Note: 'then' keyword is required after condition
+if health < 20 then
+    print("Low health!")
+elseif health < 50 then
+    print("Medium health")
+else
+    print("Full health")
+end
+```
+
+#### Switch / Case
+```typescript
+let job = "police"
+
+switch job
+    case "police", "ambulance"
+        print("Government worker")
+    case "mechanic"
+        print("Service worker")
+    default
+        print("Civilian")
+end
+```
+
+#### Guard Clauses
+Clean up nested if-statements with early returns.
+
+```typescript
+func RevivePlayer(player)
+    // Returns immediately if player is nil
+    guard player return
+    
+    // Returns with custom logic if condition fails
+    guard player.isDead else
+        print("Player is already alive")
+        return
+    end
+
+    // Main logic
+    player.revive()
+end
+
+// Guard with return value
+func GetPlayer(id)
+    let player = GetPlayerById(id)
+    guard player return nil
+    return player
+end
+```
+
+#### For Loops
+```typescript
+// Numeric for (start, end)
+for i = 1, 10 do
+    print(i)
+end
+
+// Numeric for with step (start, end, step)
+for i = 0, 100, 5 do
+    print(i)
+end
+
+// Range for with step
+for i in 1..10 by 2 do
+    print(i)
+end
+
+// For-in (pairs)
+for key, value in pairs(myTable) do
+    print("${key}: ${value}")
+end
+
+// For-in (ipairs)
+for index, item in ipairs(myArray) do
+    print("${index}: ${item}")
+end
+```
+
+#### While Loop
+```typescript
+let count = 0
+while count < 10 do
+    print(count)
+    count += 1
+end
+```
+
+### 5. Modern Operators
+
+#### Compound Assignment
+```typescript
+let x = 10
+x += 5
+x -= 3
+x *= 2
+x /= 4
+x %= 3
+```
+
+#### Null Coalescing (`??`)
+```typescript
+let name = playerName ?? "Unknown"
+let health = GetHealth() ?? 100
+```
+
+#### Optional Chaining (`?.`)
+```typescript
+let state = LocalPlayer.state?.isDead
+let nested = obj?.deep?.value
+let arrItem = arr?[0]
+```
+
+#### Ternary Operator
+```typescript
+let status = isDead ? "Dead" : "Alive"
+let label = count > 0 ? "${count} items" : "Empty"
+```
+
+### 6. Destructuring & Spread
+
+```typescript
+// Object Destructuring
+let { x, y, z } = GetEntityCoords(ped)
+let { name, health } = playerData
+
+// Array Destructuring
+let [first, second] = GetValues()
+
+// Object Spread (tables only)
+let base = { a: 1, b: 2 }
+let extended = { ...base, c: 3 }
 ```
 
-## Features
+### 7. String Interpolation
+
+Use `${expression}` inside strings to embed values:
+
+```typescript
+let name = "John"
+let age = 25
+
+print("Hello, ${name}!")
+print("You are ${age} years old")
+print("Next year you'll be ${age + 1}")
+
+// Complex expressions
+let player = { health: 100 }
+print("Health: ${player.health}")
+```
+
+### 8. Vector Literals
+
+```typescript
+// Vector3 (FiveM native)
+let pos: vector3 = <100.0, 200.0, 30.0>
+
+// Vector2
+let screenPos: vector2 = <0.5, 0.5>
+
+// Vector4 (includes heading)
+let spawn: vector4 = <100.0, 200.0, 30.0, 90.0>
+```
+
+---
+
+## 🎮 FiveM Features
+
+### Thread & Loop
+
+```typescript
+// Create a thread (Citizen.CreateThread)
+thread
+    print("Thread started")
+    
+    loop (true)
+        wait 0  // Run every frame
+        
+        // Game logic here
+        let ped = PlayerPedId()
+        let health = GetEntityHealth(ped)
+        
+        if health < 50 then
+            print("Low health warning!")
+        end
+    end
+end
+```
+
+### Wait
+
+```typescript
+// Wait in milliseconds
+wait 1000           // Wait 1 second
+wait 0              // Yield one frame
+```
+
+### Network Events
+
+```typescript
+// Register + Handle network event (Client <-> Server)
+netevent "bank:deposit" (amount)
+    print("Depositing ${amount}")
+    UpdateBankBalance(amount)
+end
+
+// Local event handler
+event "onClientResourceStart" (resName)
+    guard resName == GetCurrentResourceName() return
+    print("Resource started!")
+end
+```
+
+### Emit Events
+
+```typescript
+// Emit to server
+emit "server:event:name" (arg1, arg2)
+
+// Explicit emit variants
+emitServer "myevent" (data)
+emitClient "myevent" (targetPlayer, data)
+```
+
+### Commands
+
+```typescript
+// Register a command (RegisterCommand wrapper)
+addcmd "teleport" (source, args)
+    let x = tonumber(args[1]) ?? 0
+    let y = tonumber(args[2]) ?? 0
+    let z = tonumber(args[3]) ?? 0
+    
+    SetEntityCoords(PlayerPedId(), x, y, z)
+    print("Teleported to ${x}, ${y}, ${z}")
+end
+```
+
+### Exports
+
+```typescript
+// Export a function
+export "GetPlayerMoney" ()
+    return playerMoney
+end
+```
+
+### Timeout & Interval
+
+```typescript
+// Run once after delay
+timeout 5000
+    print("5 seconds passed!")
+end
+
+// Run repeatedly
+interval 1000
+    print("Every second")
+end
+```
+
+### Try / Catch
+
+```typescript
+try
+    RiskyOperation()
+catch err
+    print("Error: ${err}")
+end
+```
+
+---
+
+## ⚡ Complete Example: Store Robbery System
+
+```typescript
+// 1. Type Definition
+interface StoreConfig {
+    id: number,
+    position: vector3,
+    reward: number,
+    isOpen: boolean
+}
+
+// 2. Configuration
+const Stores: StoreConfig[] = [
+    { id: 1, position: <120.5, -500.2, 30.0>, reward: 5000, isOpen: true },
+    { id: 2, position: <250.0, 300.0, 25.0>, reward: 10000, isOpen: true }
+]
+
+let isRobbing = false
+
+// 3. Main Game Loop
+thread
+    loop (true)
+        wait 0
+        
+        if isRobbing then
+            break
+        end
+        
+        let ped = PlayerPedId()
+        let pos = GetEntityCoords(ped)
+        
+        for _, store in ipairs(Stores) do
+            if not store.isOpen then
+                break
+            end
+            
+            let distance = #(pos - store.position)
+            if distance < 2.0 then
+                ShowHelpText("Press ~INPUT_CONTEXT~ to rob")
+                
+                if IsControlJustPressed(0, 38) then
+                    StartRobbery(store)
+                end
+            end
+        end
+    end
+end
+
+// 4. Robbery Function
+func StartRobbery(store: StoreConfig)
+    isRobbing = true
+    
+    // Notify server
+    emit "robbery:start" (store.id)
+    
+    // Play animation
+    TaskPlayAnim(PlayerPedId(), "anim_dict", "anim_name", 8.0, -8.0, -1, 0, 0, false, false, false)
+    
+    wait 5000
+    
+    ClearPedTasks(PlayerPedId())
+    isRobbing = false
+    
+    print("Robbery complete! Reward: ${store.reward}")
+end
+
+// 5. Server Sync Handler
+netevent "robbery:sync" (storeId, newState)
+    let store = Stores.find(s => s.id == storeId)
+    guard store return
+    
+    store.isOpen = newState
+    let stateStr = newState ? "open" : "closed"
+    print("Store ${storeId} is now ${stateStr}")
+end
+```
+
+---
+
+## 🛠️ CLI Reference
+
+| Command | Usage | Description |
+|:--------|:------|:------------|
+| **Build** | `ltc build ./` | Compiles all `.lt` files in the folder to `.lua` |
+| **Watch** | `ltc watch ./` | Watches for file changes and recompiles instantly |
+| **Version** | `ltc -v` | Displays the current compiler version |
+
+### Project Structure
+
+LT automatically detects `src/` folders:
+
+```
+my-resource/
+├── src/
+│   ├── client.lt
+│   └── server.lt
+├── client.lua      ← Generated
+└── server.lua      ← Generated
+```
+
+---
+
+## 🔧 VS Code Extension
+
+Get the official **[LT Language Extension](https://marketplace.visualstudio.com/items?itemName=laot.lt-language)** for the best experience.
+
+**Features:**
+*   🎨 Full Syntax Highlighting
+*   🔍 Intelligent Autocompletion
+*   📦 **FiveM Native Intellisense**
+*   ✨ Real-time Error Checking
+
+---
 
-- Transpiles LT to Lua 5.4 (FiveM compatible)
-- Supports static typing syntax (transpiled to comments or checked)
-- FiveM native function support
+<p align="center">
+    Made with ❤️ for the FiveM Community by <b>LaotScripts</b>
+</p>