Documentation/Guides/Scripting with Luau

Scripting with Luau

Master the Luau scripting language, from basics to advanced patterns.

Introduction to Luau

StarForge uses Luau, a fast and secure scripting language derived from Lua 5.1. Luau adds type annotations, modern syntax features, and performance improvements while maintaining compatibility with most Lua code.

Why Luau?

  • Fast: Optimized for game development with quick compile times
  • Safe: Sandboxed execution prevents malicious code
  • Familiar: If you know Lua, you already know most of Luau
  • Typed: Optional type annotations for better tooling and error catching

Basic Syntax

Variables

-- Local variables (preferred)
local name = "Player1"
local score = 100
local isAlive = true

-- Multiple assignment
local x, y, z = 1, 2, 3

-- Type annotations (optional but recommended)
local health: number = 100
local playerName: string = "Guest"

Functions

-- Basic function
local function greet(name)
    print("Hello, " .. name .. "!")
end

-- Function with return value
local function add(a, b)
    return a + b
end

-- Function with type annotations
local function calculateDamage(baseDamage: number, multiplier: number): number
    return baseDamage * multiplier
end

-- Anonymous functions
local onClicked = function()
    print("Button clicked!")
end

Control Flow

-- If statements
if health <= 0 then
    print("Game Over")
elseif health < 25 then
    print("Low Health!")
else
    print("Health OK")
end

-- For loops
for i = 1, 10 do
    print(i)
end

-- For each (ipairs for arrays, pairs for dictionaries)
local items = {"Sword", "Shield", "Potion"}
for index, item in ipairs(items) do
    print(index, item)
end

-- While loops
while isRunning do
    update()
    wait(0.016)  -- ~60 FPS
end

Working with Instances

Everything in StarForge is an Instance. You create instances using the global new() function:

-- Create a new Part
local part = new("Part")
part.Name = "MyPart"
part.Position = Vector3.new(0, 10, 0)
part.Size = Vector3.new(5, 1, 5)
part.Color = Color.Red

-- Parent it to the world
part.Parent = world

-- Access properties
print(part.Name)        -- "MyPart"
print(part.Position.Y)  -- 10

-- Destroy an instance
part:Destroy()

Events

Events are how you respond to things happening in your game:

-- Connect to an event
local connection = part.Changed:Connect(function(propertyName)
    print(propertyName .. " was changed!")
end)

-- Disconnect when done
connection:Disconnect()

-- Input events
local inputSystem = engine:GetSystem("InputSystem")
inputSystem.InputBegan:Connect(function(input)
    if input.Key == KeyCode.Space then
        jump()
    end
end)

Math Types

StarForge provides several math types for 3D operations:

-- Vector3 - 3D position/direction
local pos = Vector3.new(10, 5, 3)
local direction = Vector3.new(1, 0, 0)
local moved = pos + direction * 5

-- Vector2 - 2D operations
local screenPos = Vector2.new(100, 200)

-- Color - RGBA colors
local red = Color.Red
local custom = Color.new(0.5, 0.3, 0.8, 1.0)
local hex = Color.FromHex("#FF5500")

-- UDim2 - UI positioning (scale + offset)
local position = UDim2.new(0.5, -50, 0.5, -25)  -- Centered with offset

-- Transform - 4x4 transformation matrix
local transform = Transform.Identity
transform = transform * Transform.FromPosition(Vector3.new(0, 5, 0))

Best Practices

  • Use local variables: They're faster and prevent pollution of the global scope
  • Add type annotations: Help catch bugs early and improve code readability
  • Disconnect events: When an event handler is no longer needed, disconnect it to prevent memory leaks
  • Use descriptive names: playerHealth is better than ph
  • Comment your code: Explain why, not what

Next Steps

All Guides