studio/RUBLOX_LUA_API.md

Lua API Рублокса (справочник для скриптеров)

Этот документ — полный список того, что работает в Lua-скриптах Рублокса. API максимально приближен к Roblox, чтобы можно было переносить чужие скрипты с минимальными правками.

Как переключить скрипт на Lua: в шапке вкладки редактора кода кликни по переключателю JS / Lua. Подсветка синтаксиса и автодополнение автоматически переключатся.

---

Содержание

1. Базовые типы
2. DataModel: game, workspace, Players
3. Part — куб на сцене
4. Создание и удаление
5. События: Touched, Heartbeat, RemoteEvent
6. Таймеры: task.wait, task.delay
7. GUI: TextLabel, TextButton, Frame
8. Звук: Sound
9. Анимации: TweenService
10. Игрок: Humanoid, LocalPlayer
11. Чего пока нет

---

Базовые типы

Vector3

local v = Vector3.new(1, 2, 3)
print(v.X, v.Y, v.Z)             -- 1 2 3
print(v.Magnitude)                -- 3.7416...  (длина)
print(v.Unit)                     -- нормализованный
print(v:Dot(otherVec))            -- скалярное произведение
print(v:Cross(otherVec))          -- векторное произведение
local mid = v:Lerp(otherVec, 0.5) -- линейная интерполяция

-- Константы:
Vector3.zero   -- (0,0,0)
Vector3.one    -- (1,1,1)
Vector3.xAxis  -- (1,0,0)
Vector3.yAxis, Vector3.zAxis

Поддержаны операторы: +, -, * (на число), /, унарный -.

Color3

local c = Color3.new(0.5, 0.2, 0.8)        -- 0..1 каждый
local c2 = Color3.fromRGB(255, 128, 0)     -- 0..255
local c3 = Color3.fromHSV(0.1, 0.8, 1)
local c4 = Color3.fromHex("#FF8000")
local mid = c:Lerp(c2, 0.5)
print(c:ToHex())  -- "#7F33CC"

UDim2 / UDim / Vector2

Для GUI-координат:

local pos = UDim2.new(0.5, 0, 0.5, 0)   -- центр экрана (scale/offset)
local pos2 = UDim2.fromScale(0.2, 0.1)
local pos3 = UDim2.fromOffset(100, 50)  -- в пикселях

CFrame

local cf = CFrame.new(0, 10, 0)         -- позиция
local cf2 = CFrame.lookAt(eye, target)  -- упрощённый
print(cf.Position)                       -- Vector3

Enum

Enum.KeyCode.W
Enum.KeyCode.Space
Enum.Material.Plastic, Enum.Material.Neon, Enum.Material.Wood
Enum.UserInputType.MouseButton1
Enum.HumanoidStateType.Running

---

DataModel

Виртуальное дерево, как в Roblox:

game                       -- корневой DataModel
game.Workspace             -- = workspace (короче)
game.Players               -- сервис игроков
game.Players.LocalPlayer   -- локальный игрок
game.ReplicatedStorage     -- хранилище общих ресурсов
game.StarterGui            -- стартовое GUI
game.Lighting              -- свет

Методы:

local svc = game:GetService("RunService")
local part = workspace:FindFirstChild("Coin")
local part2 = workspace:FindFirstChildOfClass("Part")
local all = workspace:GetChildren()       -- массив всех детей
local descendants = workspace:GetDescendants()
local sib = workspace.Coin:FindFirstAncestorOfClass("Workspace")
print(workspace:IsA("Workspace"))         -- true

---

Part

Part — куб/сфера/цилиндр на сцене. Это обёртка над примитивом Рублокса. Скрипт привязанный к кубу получает его через script.Parent:

-- script.Parent — Part к которому прицеплен скрипт
print(script.Parent.Name)              -- "Part_1"

-- Чтение свойств
print(script.Parent.Position)          -- Vector3
print(script.Parent.Size)              -- Vector3
print(script.Parent.Color)             -- Color3
print(script.Parent.Anchored)          -- bool
print(script.Parent.CanCollide)        -- bool
print(script.Parent.Transparency)      -- 0..1

-- Запись (двигает куб в реальном времени!)
script.Parent.Position = Vector3.new(0, 10, 0)
script.Parent.Size = Vector3.new(5, 1, 5)
script.Parent.Color = Color3.fromRGB(255, 0, 0)
script.Parent.Anchored = false           -- куб начнёт падать (физика)
script.Parent.Transparency = 0.5         -- полупрозрачный
script.Parent.CFrame = CFrame.new(0, 20, 0)

---

Создание и удаление

Instance.new

-- Создать Part на сцене
local p = Instance.new("Part")
p.Position = Vector3.new(0, 5, 0)
p.Size = Vector3.new(2, 2, 2)
p.Color = Color3.fromRGB(255, 100, 0)
p.Anchored = true
p.Parent = workspace

-- Удалить через 3 секунды
task.delay(3, function()
    p:Destroy()
end)

Поддержанные классы:

• Сцена: Part, WedgePart, MeshPart
• События: RemoteEvent, BindableEvent
• GUI: ScreenGui, Frame, TextLabel, TextButton, ImageLabel, ImageButton, TextBox, ScrollingFrame
• Звук: Sound
• Прочее: Folder, Humanoid, Configuration, любой ClassName

---

События

script.Parent.Touched — касание игрока

script.Parent.Touched:Connect(function(hit)
    print("Игрок коснулся!", hit.Name)
    local h = game.Players.LocalPlayer.Character:FindFirstChildOfClass("Humanoid")
    if h then
        h:TakeDamage(100)  -- KillBrick
    end
end)

RunService.Heartbeat — каждый кадр

local RunService = game:GetService("RunService")
RunService.Heartbeat:Connect(function(dt)
    -- dt — время с прошлого кадра (~0.016)
    script.Parent.Position = script.Parent.Position + Vector3.new(0, 0.1, 0)
end)

BindableEvent / RemoteEvent — общение между скриптами

-- Скрипт A создаёт событие в общем месте
local event = Instance.new("BindableEvent")
event.Name = "MyEvent"
event.Parent = game.ReplicatedStorage

-- Скрипт B подписывается
local event = game.ReplicatedStorage:WaitForChild("MyEvent")
event.Event:Connect(function(msg, num)
    print("Получено:", msg, num)
end)

-- Скрипт A триггерит
event:Fire("привет", 42)

Humanoid.Died

local h = game.Players.LocalPlayer.Character:FindFirstChildOfClass("Humanoid")
h.Died:Connect(function()
    print("игрок умер")
end)
h.HealthChanged:Connect(function(newHp)
    print("здоровье:", newHp)
end)

---

Таймеры

task.wait(сек) — приостановить скрипт

print("сейчас")
task.wait(1)
print("через секунду")

task.wait не блокирует другие скрипты — это yield через coroutines. Можно использовать в while true do ... task.wait(0.1) end без проблем.

task.delay(сек, fn) — выполнить через

task.delay(2, function()
    print("через 2 секунды")
end)

task.spawn(fn) — асинхронно

task.spawn(function()
    print("параллельно с основным потоком")
end)

---

GUI

Базовая иерархия

-- ScreenGui — корень всех GUI
local sg = Instance.new("ScreenGui")
sg.Parent = game.Players.LocalPlayer.PlayerGui

-- TextLabel — статичный текст
local label = Instance.new("TextLabel")
label.Parent = sg
label.Text = "Привет!"
label.TextColor3 = Color3.fromRGB(255, 255, 0)
label.BackgroundColor3 = Color3.fromRGB(50, 30, 20)
label.Position = UDim2.new(0.4, 0, 0.1, 0)   -- 40% от ширины, 10% от высоты
label.Size = UDim2.new(0.2, 0, 0.05, 0)
label.TextSize = 24

-- TextButton — кликабельная кнопка
local btn = Instance.new("TextButton")
btn.Parent = sg
btn.Text = "Нажми"
btn.Position = UDim2.new(0.4, 0, 0.5, 0)
btn.Size = UDim2.new(0.2, 0, 0.08, 0)
btn.MouseButton1Click:Connect(function()
    print("Клик!")
    label.Text = "Нажата!"
end)

Свойства

Свойство	Тип	Описание
Text	string	Видимый текст
TextColor3	Color3	Цвет текста
TextSize	number	Размер шрифта
BackgroundColor3	Color3	Цвет фона
BackgroundTransparency	0..1	0=сплошной, 1=прозрачный
Position	UDim2	Позиция (scale=%, offset=px/10)
Size	UDim2	Размер
Visible	bool	Виден или нет

События кнопок

btn.MouseButton1Click:Connect(fn)  -- ЛКМ клик
btn.MouseEnter:Connect(fn)         -- наведение
btn.MouseLeave:Connect(fn)         -- увод
btn.Activated:Connect(fn)          -- = MouseButton1Click

---

Звук

local sound = Instance.new("Sound")
sound.SoundId = "coin"       -- или "jump", "win", "lose", "hit", "click", "pickup"
sound.Volume = 1             -- 0..2
sound.PlaybackSpeed = 1      -- pitch
sound:Play()

Также Roblox-AssetID работает с эвристикой:

sound.SoundId = "rbxassetid://1234567890"  -- автоподбор по имени переменной

Поддержанные звуки (процедурные, не из файлов):

• jump — прыжок
• pickup — подбор
• coin — звон монеты
• win — победа
• lose — поражение
• click — клик
• hit — удар

Зацикливание:

sound.Looped = true
sound:Play()  -- играет до sound:Stop()

---

TweenService

Плавная анимация свойств:

local TweenService = game:GetService("TweenService")

local part = script.Parent
local tween = TweenService:Create(
    part,
    { Time = 2 },                              -- длительность 2 сек
    { Position = Vector3.new(0, 20, 0),
      Color = Color3.fromRGB(255, 0, 0) }      -- цели
)
tween:Play()

tween.Completed:Connect(function()
    print("Анимация завершилась!")
end)

Работает с Position, Size, Color (Vector3/Color3) и числовыми свойствами (Transparency, TextSize, и т.д.).

---

Игрок

game.Players.LocalPlayer

local plr = game.Players.LocalPlayer
print(plr.Name, plr.UserId, plr.DisplayName)
print(plr.Character)                              -- Model

Humanoid

local char = game.Players.LocalPlayer.Character
local h = char:FindFirstChildOfClass("Humanoid")

print(h.Health, h.MaxHealth)
print(h.WalkSpeed)        -- скорость ходьбы
print(h.JumpPower)        -- сила прыжка

h.Health = 0              -- мгновенная смерть → респавн
h:TakeDamage(50)          -- урон с учётом invulnerability

h.Died:Connect(function()
    print("Помер")
end)
h.HealthChanged:Connect(function(newHp)
    if newHp < 30 then
        print("Здоровье низкое!")
    end
end)

HumanoidRootPart

local hrp = char:FindFirstChild("HumanoidRootPart")
print(hrp.Position)

---

Чего пока нет

Не работает (пока):

• Скрипты не делятся на Server/LocalScript — все скрипты client-side.
• DataStoreService — методы есть, но возвращают nil/no-op.
• workspace:Raycast / game.Lighting.ClockTime — заглушки.
• Players.PlayerAdded — никогда не фейерится (только один игрок).
• 3D-анимации (Animation instance + AnimationController) — LoadAnimation возвращает заглушку.
• Sound из файлов — только встроенные процедурные.
• SurfaceGui / BillboardGui — нет, только ScreenGui.
• Model:MoveTo / :SetPrimaryPartCFrame — нет.
• Networking (RemoteFunction:InvokeServer) — RemoteEvent работает только в пределах одного клиента.

Если что-то из этого критично — открой issue в репо.

---

Пример: KillBrick + монета + GUI-счётчик

Положи 1 куб и 1 шарик на сцене. К каждому привяжи скрипт:

На кубе (KillBrick):

script.Parent.Color = Color3.fromRGB(200, 30, 30)
script.Parent.Touched:Connect(function()
    local h = game.Players.LocalPlayer.Character:FindFirstChildOfClass("Humanoid")
    if h then h:TakeDamage(100) end
end)

На шарике (Coin):

script.Parent.Color = Color3.fromRGB(255, 215, 0)
script.Parent.Touched:Connect(function()
    -- Запускаем событие на ReplicatedStorage
    local re = game.ReplicatedStorage:FindFirstChild("CoinPicked")
    if not re then
        re = Instance.new("BindableEvent")
        re.Name = "CoinPicked"
        re.Parent = game.ReplicatedStorage
    end
    re:Fire()
    script.Parent:Destroy()
end)

Глобальный скрипт (GUI):

local sg = Instance.new("ScreenGui")
sg.Parent = game.Players.LocalPlayer.PlayerGui

local label = Instance.new("TextLabel")
label.Parent = sg
label.Text = "Монет: 0"
label.Position = UDim2.new(0.05, 0, 0.05, 0)
label.Size = UDim2.new(0.1, 0, 0.05, 0)
label.TextSize = 20
label.TextColor3 = Color3.fromRGB(255, 215, 0)

local count = 0
task.spawn(function()
    while not game.ReplicatedStorage:FindFirstChild("CoinPicked") do
        task.wait(0.1)
    end
    game.ReplicatedStorage.CoinPicked.Event:Connect(function()
        count = count + 1
        label.Text = "Монет: " .. count
        local sound = Instance.new("Sound")
        sound.SoundId = "coin"
        sound:Play()
    end)
end)

Получится: красный куб убивает, золотая монета даёт +1 к счётчику со звуком.

---

Версия документации: Этап 7 (готово после реализации Этапов 1-6). Если что-то описанное здесь не работает — это баг, репортуй.