Lua Scripting

Документация для игроков

Руководство по написанию скриптов для объектов

---

Введение

Каждый объект в игре может содержать Lua-скрипт. Скрипт позволяет управлять поведением объекта: двигать его, поворачивать, масштабировать и реагировать на события.

Скрипт привязан к конкретному объекту и может обращаться к нему через переменную

Структура скрипта:

-- Вызывается один раз при запуске
function onStart()
-- ваш код здесь
end
-- Вызывается когда объект включается
function onEnable()
end
-- Вызывается когда объект выключается
function onDisable()
end
-- Вызывается при уничтожении объекта
function onDestroy()
end

Все эти функции необязательны — можно определить только те, что нужны.

self — текущий объект

self.obj — это ваш объект. Через него вы читаете и меняете позицию, поворот, масштаб и имя.

Позиция

Имя	Тип	Описание
self.obj.pos	Vector3	Глобальная позиция объекта
self.obj.pos	Vector3	Локальная позиция (относительно родителя)

function onStart()
	-- Прочитать позицию
	local p = self.obj.pos
	print(p.x, p.y, p.z)
	-- Переместить объект
	self.obj.pos = Vector3(0, 5, 0)
end

Поворот

Имя	Тип	Описание
self.obj.rot	Vector3	Глобальный поворот в градусах (Euler)
self.obj.localRot	Vector3	Локальный поворот в градусах

function onStart()
	-- Повернуть объект на 90 градусов по Y
	self.obj.rot = Vector3(0, 90, 0)
end

Масштаб

Имя	Тип	Описание
self.obj.scale	Vector3	Масштаб объекта

function onStart()
	-- Увеличить объект вдвое
	self.obj.scale = Vector3(2, 2, 2)
end

Имя

Имя	Тип	Описание
self.obj.name	string	Имя объекта в сцене

self.obj.name = "МойОбъект"
print(self.obj.name)

Vector3 — трёхмерный вектор

Vector3 используется для позиций, поворотов и масштабов. Он хранит три числа: x, y, z.

Создание

local v = Vector3(1, 2, 3) -- x=1, y=2, z=3
print(v.x) -- 1
print(v.y) -- 2
print(v.z) -- 3

Методы

Имя	Тип	Описание
v:Add(other)	Vector3	Сложить два вектора
v:Sub(other)	Vector3	Вычесть вектор
v:Mul(число)	Vector3	Умножить на число
v:Dot(other)	number	Скалярное произведение
v:Cross(other)	Vector3	Векторное произведение
v:Magnitude()	number	Длина вектора
v:Normalized()	Vector3	Единичный вектор (длина = 1)
v:Distance(other)	number	Расстояние между векторами
v:Equals(other)	bool	Сравнить два вектора

local a = Vector3(1, 0, 0)
local b = Vector3(0, 1, 0)
local sum = a:Add(b) -- Vector3(1, 1, 0)
local diff = a:Sub(b) -- Vector3(1, -1, 0)
local big = a:Mul(5) -- Vector3(5, 0, 0)
local dist = a:Distance(b) -- 1.414...
local norm = big:Normalized() -- Vector3(1, 0, 0)
local len = big:Magnitude() -- 5

Константы

Имя	Тип	Описание
Vector3.zero	Vector3(0,0,0)	Нулевой вектор
Vector3.one	Vector3(1,1,1)	Единичный вектор
Vector3.up	Vector3(0,1,0)	Вверх
Vector3.forward	Vector3(0,0,1)	Вперёд
Vector3.right	Vector3(1,0,0)	Вправо

-- Поднять объект вверх на 3 единицы
local pos = self.obj.pos
self.obj.pos = pos:Add(Vector3.up:Mul(3))

Object — создание новых объектов

Через Object можно создавать новые объекты прямо из скрипта.

Имя	Тип	Описание
Object.Create()	GameObject	Создать пустой объект
Object.CreateCube()	GameObject	Создать куб

function onStart()
	-- Создать куб и поставить его рядом
	local cube = Object.CreateCube()
	cube.pos = Vector3(5, 0, 0)
	cube.name = 'MyCube'
end

Примеры

Поднять объект на 2 единицы вверх

function onStart()
	local pos = self.obj.pos
	self.obj.pos = pos:Add(Vector3(0, 2, 0))
end

Напечатать расстояние до центра мира

function onStart()
	local pos = self.obj.pos
	local dist = pos:Distance(Vector3(0, 0, 0))
	print('Расстояние до центра: ' .. dist)
end

Сдвинуть объект вперёд и повернуть

function onStart()
	-- Переместить на 3 единицы вперёд
	local pos = self.obj.pos
	self.obj.pos = pos:Add(Vector3.forward:Mul(3))
	-- Повернуть на 45 градусов по оси Y
	self.obj.rot = Vector3(0, 45, 0)
end

Создать несколько кубов в ряд

function onStart()
	for i = 0, 4 do
		local cube = Object.CreateCube()
		cube.pos = Vector3(i * 2, 0, 0)
		cube.name = 'Cube_' .. i
	end
end

Нормализовать направление и передвинуть

function onStart()
	local dir = Vector3(3, 0, 4) 	-- длина = 5
	local norm = dir:Normalized() 	-- длина = 1
	self.obj.pos = norm:Mul(10) 		-- 10 единиц в том направлении
end