lt-script 1.0.3 → 1.0.6

package/README.md

@@ -6,269 +6,561 @@
   <img src="https://img.shields.io/badge/FiveM-Ready-green" alt="FiveM Ready">
 </p>
 
-**LT** is a modern, developer-friendly language that compiles to FiveM Lua. It brings TypeScript-like syntax, modern JavaScript features, and FiveM-specific sugar to the Lua ecosystem — making your scripts cleaner, safer, and more enjoyable to write.
+**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?
 
-Writing vanilla Lua for FiveM can be tedious. LT fixes that with:
+*   **🛡️ 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.
 
-- **Modern Syntax**: Arrow functions, destructuring, spread operator, optional chaining
-- **FiveM Sugar**: Built-in `thread`, `wait`, `netevent`, `addcmd`, `export` keywords
-- **Type Safety**: Static type checking catches errors at compile time
-- **Clean Code**: No more boilerplate — just write what you mean
+---
 
 ## 📦 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 .
 ```
 
+---
+
 ## 🚀 Quick Start
 
-Create a file called `main.lt`:
+Create a `client.lt` file:
 
 ```typescript
-// Variables with modern scoping
-let health: number = 100
-const MAX_HEALTH = 200
+// Define a type for player data
+interface PlayerData {
+    id: number,
+    name: string,
+    health: number
+}
 
-// Arrow functions
-let double = (x) => x * 2
+// Variables with types
+let active: boolean = false
+const MAX_HEALTH = 100
 
-// String interpolation
-print("Health: $health / $MAX_HEALTH")
+// FiveM Command
+addcmd "heal" (source, args)
+    let amount = tonumber(args[1]) ?? MAX_HEALTH
+    SetEntityHealth(PlayerPedId(), amount)
+    print("Healed for ${amount}")
+end
 
-// FiveM thread with wait
+// Thread with loop
 thread
+    print("System active")
     loop (true)
         wait 1000
-        print("Tick...")
+        if LocalPlayer.state?.isDead then
+            print("Player is dead!")
+        end
     end
 end
-
-// Register a command easily
-addcmd "heal" (source, args)
-    health = MAX_HEALTH
-    print("Player healed!")
-end
-
-// Network events without boilerplate
-netevent "player:spawn" (data)
-    print("Player spawned: $data")
-end
 ```
 
-Compile it:
-
+**Compile it:**
 ```bash
 ltc build .
 ```
 
-Output `main.lua`:
-```lua
-local health = 100
-local MAX_HEALTH <const> = 200
+---
 
-local double = function(x) return x * 2 end
+## 📘 Language Reference
 
-print("Health: " .. tostring(health) .. " / " .. tostring(MAX_HEALTH))
+### 1. Variables & Types
 
-CreateThread(function()
-    while true do
-        Wait(1000)
-        print("Tick...")
-    end
-end)
+LT supports explicit typing with compile-time validation.
 
-RegisterCommand("heal", function(source, args)
-    health = MAX_HEALTH
-    print("Player healed!")
-end, false)
-
-RegisterNetEvent("player:spawn")
-AddEventHandler("player:spawn", function(data)
-    print("Player spawned: " .. tostring(data))
-end)
+```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]
 ```
 
-## 🛠️ CLI Commands
+### 2. Interfaces & Type Aliases
 
-| Command | Description |
-|---------|-------------|
-| `ltc build <dir>` | Compile all `.lt` files in directory |
-| `ltc watch <dir>` | Watch mode — auto-compile on save |
+Define complex data structures for compile-time validation.
 
-## 🎯 Feature Highlights
-
-### Variables & Constants
 ```typescript
-var globalVar = "I am global"     // Global variable
-let localVar = 10                 // Local variable
-const MAX = 100                   // Constant (Lua 5.4 <const>)
-```
+// Interface - Object shape definition
+interface VehicleConfig {
+    model: string,
+    price: number,
+    color: string
+}
 
-### Type System
-```typescript
-// Explicit types
-let name: string = "John"
-let age: number = 25
-let active: boolean = true
+// Type Alias - Alternative syntax
+type PlayerPos = { x: number, y: number, z: number }
 
-// Type Aliases
-interface PlayerData = {
-    name: string,
-    level: number,
-    isVip: boolean
+// Usage with validation
+const myCar: VehicleConfig = {
+    model: "sultan",
+    price: 50000,
+    color: "red"
 }
 
-func Calculate(a: number, b: number)
-    return a + b
-end
-```
+// Arrays of interfaces
+interface StoreConfig {
+    id: number,
+    position: vector3,
+    isOpen: boolean
+}
 
-### Arrow Functions
-```typescript
-let add = (a, b) => a + b
-let greet = (name) => print("Hello, $name!")
+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 }
+]
 ```
 
-### Destructuring
+> **Note:** Type validation ensures field types match. Assigning `number` to a `vector3` field will cause a compile error.
+
+### 3. Functions
+
 ```typescript
-let player = { name: "Alex", level: 50 }
-let { name, level } = player
+// 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
 
-let coords = [100, 200, 300]
-let [x, y, z] = coords
+// 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
+}
 ```
 
-### Optional Chaining & Null Coalescing
+### 4. Control Flow
+
+#### If / Else
 ```typescript
-let job = player?.metadata?.job?.label ?? "Unemployed"
+// 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
 ```
 
-### Vector Literals
+#### Switch / Case
 ```typescript
-let pos = <100.0, 50.0, 20.0>   // vector3
-let rot = <0.0, 90.0>           // vector2
+let job = "police"
+
+switch job
+    case "police", "ambulance"
+        print("Government worker")
+    case "mechanic"
+        print("Service worker")
+    default
+        print("Civilian")
+end
 ```
 
-### Switch/Case
+#### Guard Clauses
+Clean up nested if-statements with early returns.
+
 ```typescript
-switch weather
-    case "RAIN", "THUNDER"
-        print("Stay inside!")
-    case "CLEAR"
-        print("Nice day!")
-    default
-        print("Unknown weather")
+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
+#### For Loops
 ```typescript
-// Range loop
-for i in 1..10 do
+// Numeric for (start, end)
+for i = 1, 10 do
     print(i)
 end
 
-// Range with step
-for i in 10..1 by -1 do
+// Numeric for with step (start, end, step)
+for i = 0, 100, 5 do
     print(i)
 end
 
-// C-style loop
-for i = 0, 100, 5 do
+// 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
 ```
 
-### FiveM Specific
+#### 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 }
+```
+
+### 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
 
-#### Threads & Wait
 ```typescript
+// Create a thread (Citizen.CreateThread)
 thread
-    wait 1000
-    print("After 1 second")
+    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
 ```
 
-#### Events
+### Wait
+
 ```typescript
-netevent "myResource:sync" (data)
-    -- RegisterNetEvent + AddEventHandler
+// 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
 
-event "localEvent" (data)
-    -- AddEventHandler only
+// Local event handler
+event "onClientResourceStart" (resName)
+    guard resName == GetCurrentResourceName() return
+    print("Resource started!")
 end
 ```
 
-#### Commands
+### 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)
-    print("Teleporting...")
+    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
+### Exports
+
 ```typescript
-export func GetPlayerData(id)
-    return players[id]
+// Export a function
+export "GetPlayerMoney" ()
+    return playerMoney
 end
 ```
 
-#### Guard Statements
+### Timeout & Interval
+
 ```typescript
-guard player return              // Early return if nil/false
-guard player.job == "police" return print("Access denied")
+// Run once after delay
+timeout 5000
+    print("5 seconds passed!")
+end
 
-// Guard with else block
-guard isValid else
-    print("Invalid state")
-    return
+// Run repeatedly
+interval 1000
+    print("Every second")
 end
 ```
 
-#### Try/Catch
+### Try / Catch
+
 ```typescript
 try
-    riskyOperation()
+    RiskyOperation()
 catch err
-    print("Error: $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
 ```
 
-## 📁 Project Structure
+---
+
+## 🛠️ 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)
-└── fxmanifest.lua
+├── client.lua      ← Generated
+└── server.lua      ← Generated
 ```
 
-Run `ltc watch .` in your resource folder for automatic compilation.
+---
 
 ## 🔧 VS Code Extension
 
-Get syntax highlighting and IntelliSense for `.lt` files:
-
-**[LT Language Extension](https://marketplace.visualstudio.com/items?itemName=laot.lt-language)**
-
-- Syntax Highlighting
-- IntelliSense for Variables & Functions
-- **Native FiveM Autocompletion** (GetHashKey, CreateVehicle, etc.)
-- Snippets for common patterns
-
-## 📜 License
+Get the official **[LT Language Extension](https://marketplace.visualstudio.com/items?itemName=laot.lt-language)** for the best experience.
 
-MIT © [LaotScripts](https://github.com/laot7490)
+**Features:**
+*   🎨 Full Syntax Highlighting
+*   🔍 Intelligent Autocompletion
+*   📦 **FiveM Native Intellisense**
+*   ✨ Real-time Error Checking
 
 ---
 
 <p align="center">
-  Made with ❤️ for the FiveM community
+    Made with ❤️ for the FiveM Community by <b>LaotScripts</b>
 </p>