Написання програм на Lua

Keira має вбудовану віртуальну машину мови програмування Lua. Це дозволяє писати та виконувати програми на Lua прямо з SD-картки, без необхідності компіляції чи перепрошивання Лілки.

Попередження

Якщо ви не знайомі з мовою Lua, рекомендуємо прочитати туторіал з Lua перед тим, як продовжувати: https://www.lua.org/pil/1.html

Приклад програми

Оскільки Lua сама по собі - це універсальна мова програмування, вона не має вбудованих функцій для роботи з дисплеєм, звуком тощо. Тому для роботи з цими пристроями на Лілці в Keira доступні спеціальні вбудовані модулі, які надають доступ до функцій пристроїв.

Модулі завантажуються автоматично - не потрібно писати жодних require(...). Ось приклад простої програми на Lua, яка виводить текст «Hello, world!» на екран:

function lilka::update()
    if controller.get_state().a.just_pressed then
        -- Завершуємо програму при натисканні кнопки "A"
        util.exit()
    end
end

function lilka::draw()
    -- Заповнюємо екран чорним кольором:
    display.fill_screen(display.color565(0, 0, 0))

    -- Виводимо текст "Hello, world!" на екран:
    display.set_cursor(0, 32)
    display.print("Hello, world!")
end

Ви можете зберегти цей код у файл з розширенням .lua на SD-картці, а потім виконати його, обравши його в браузері SD-картки.

Повний перелік доступних модулів та їх функцій можна знайти в розділі Lua API.

init, update, draw

В іграх важливо, щоб гра була плавною та виконувалася з певною стабільною кількістю кадрів на секунду.

Імовірно, ви знайомі з функцією delay(...) з фреймворка Arduino, яка затримує виконання програми на певну кількість мілісекунд. Це зручно для простих програм, що не використовують дисплей, але для ігор це не підходить, оскільки такі функції заблокують виконання програми на певну кількість мілісекунд, незалежно від швидкості виконання програми, а також не дозволяють вам взаємодіяти з грою під час затримки.

Для цього існує можливість визначити функції lilka.init(), lilka.update() і lilka.draw(). Якщо при запуску вашої програми Keira знайде цю функції, вона буде викликати їх автоматично.

• lilka.init() викликається один раз при запуску програми.

• lilka.update() викликається 30 разів на секунду, тому ви можете використовувати його для оновлення стану гри та обробки введення користувача.

• lilka.draw() викликається після lilka.update() та використовується для малювання графіки на екрані.

Попередження

Програма на Lua буде виконуватись доти, доки не буде викликано функцію util.exit(). Інакше для виходу вам доведеться перезавантажити Лілку.

Попередження

Не варто використовувати util.sleep() всередині ваших функцій lilka.update() та lilka.draw(), оскільки це призведе до заповільнення виконання програми.

Намагайтесь писати код, який не блокує виконання програми, а використовує функцію lilka.update() для оновлення стану гри та обробки введення користувача.

lilka.update() також отримує необов’язковий аргумент delta, який вказує (в секундах), скільки часу пройшло з початку її попереднього виклику. Це дозволяє вам робити рухи та анімації, які будуть відбуватись з однаковою швидкістю незалежно від швидкості виконання програми.

За ідеальних обставин, delta буде дорівнювати 1/30, або приблизно 0.0333 секунди, але якщо код гри дуже складний і його виконання займає більше часу, ніж 1/30 мекунди, то значення delta буде більшим. Ваша програма може використовувати delta для того, щоб, наприклад, рухати об’єкти на екрані залежно від часу, а не від кількості кадрів на секунду.

Ці три функції повинні бути визначені у головному файлі програми, наприклад:

local ball_x
local ball_y

-- Завантажуємо зображення м'яча, яке знаходиться в корені SD-картки:
local ball = resources.load_image("ball.bmp", display.color565(255, 255, 255))

function lilka.init()
    -- Ця функція викликається один раз при запуску програми.
    -- Цей код можна було б виконати в глобальному контексті (поза цією функцією), як ми це зробили з "ball",
    -- але ініціалізація гри буде очевиднішою, якщо вона відбувається тут.
    ball_x = display.width / 2
    ball_y = display.height / 2
end

function lilka.update(delta)
    local dir_x = 0
    local dir_y = 0

    -- Обробляємо введення користувача:
    local state = controller.get_state()
    if state.up.pressed then
        dir_y = -1
    elseif state.down.pressed then
        dir_y = 1
    end
    if state.left.pressed then
        dir_x = -1
    elseif state.right.pressed then
        dir_x = 1
    end
    if state.a.pressed then
        -- Вихід з програми:
        util.exit()
    end

    -- Переміщуємо м'яч зі швидкістю 50 пікселів на секунду
    ball_x = ball_x + dir_x * 50 * delta
    ball_y = ball_y + dir_y * 50 * delta
end

function lilka.draw()
    -- Малюємо графіку:
    display.fill_screen(display.color565(0, 0, 0))
    display.draw_image(ball, ball_x, ball_y)

    -- Після виконання цієї функції Лілка автоматично відобразить все, що ми намалювали на екрані.
    -- Не потрібно викликати display.queue_draw() чи щось подібне.
end

-- Інші функції:
-- ...

Цей код створить просту програму, в якій ви можете керувати м’ячем за допомогою стрілок на контролері. Кожен кадр гри м’яч переміщується на певну відстань залежно від натиснутих кнопок, а потім малюється на екрані.

Завдяки аргументу delta м’яч завжди рухатиметься з однаковою швидкістю незалежно від того, як швидко виконується програма - чи це 30 кадрів на секунду, чи 10, чи 1000.

Попередження

Ваш код всередині функції lilka.draw() не повинен робити жодних припущень щодо того, що вже було намальовано раніше. Кожен кадр гри потрібно малювати повністю.

Це потрібно тому, що Keira використовує подвійну буферизацію екрану, тобто ваша гра малює на передньому буфері, а в цей час Keira відображає задній буфер на екрані.

Тому радимо починати кожен кадр гри з виклику display.fill_screen(display.color565(0, 0, 0)), щоб очистити передній буфер перед малюванням нового кадру, оскільки він може бути забруднений попереднім кадром.

Швидке тестування програм

Звісно, ви можете зберегти вашу програму на SD-картці, а потім вибрати її в браузері SD-картки, але це може бути доволі незручно, особливо якщо ви працюєте над програмою, яка вимагає багато ітерацій. Щоразу, коли ви зберігаєте програму на SD-картці, ви повинні виймати її з Лілки, вставляти в комп’ютер, зберігати файл, виймати з комп’ютера, вставляти в Лілку, вибирати файл в браузері SD-картки, запускати програму, перевіряти, в͟и̛п͜р͢а̵в̀л͟я̕т̴и͜ ̢п͟о̨м͘и̴л͢к͡и́,͝ ̕з́б͠е͞р͠і͞г͏а̢т͞и̧ ͘з̶н̛о̶в͢у̢,͡ ͡О НІ! Це - нестерпно і в нас немає часу на це!

Саме тому Keira має функцію, яка називається Live Lua. Вона дозволяє вам запускати Lua-код на Лілці через USB-кабель прямо з вашого комп’ютера, без необхідності зберігати його на SD-картці.

Попередження

Якщо ваша Lua-програма завантажує додаткові ресурси з SD-картки - наприклад, зображення, звуки тощо - ви спершу повинні вручну скопіювати ці ресурси на SD-картку, оскільки Live Lua не підтримує завантаження файлів на SD-картку через USB-кабель. Вона надсилає на Лілку лише код Lua.

Попередження

Live Lua підтримує запуск програм, які складаються лише з одного файлу. Якщо ваша програма складається з декількох файлів, які завантажуються через require(), вам потрібно спершу скопіювати всі модулі на SD-картку, а потім використовувати Live Lua для запуску головного файлу програми.

Щоб використовувати Live Lua, вам потрібно встановити розширення для Visual Studio Code, яке називається Serial Monitor:

Після цього підключіть Лілку до комп’ютера за допомогою USB-кабеля та перейдіть в меню «Розробка» -> «Live Lua». Лілка перейде в режим «Live Lua» та очікуватиме код Lua через USB-порт.

Далі створіть новий файл з розширенням .lua - наприклад, test.lua. Напишіть в ньому якийсь код:

display.fill_screen(display.color565(255, 0, 0))
display.set_cursor(50, 50)
display.print('Привіт, Лілка!')
display.queue_draw() -- Потрібно викликати цю функцію, щоб відобразити зміни на екрані, оскільки цей код знаходиться поза функцією lilka.draw
util.sleep(1)

Тепер перейдіть на вкладку «Serial Monitor» у VS Code, оберіть COM-порт, на якому підключена Лілка, та натисніть «Start Monitoring»:

Після цього натисніть правою кнопкою будь-де в коді на вкладці з вашим файлом test.lua та оберіть «Send to Serial Monitor» -> «Send Entire File»:

Вжух - і код миттєво запуститься на Лілці! Якщо ви зробите зміни в коді, ви можете просто натиснути «Send to Serial Monitor» -> «Send Entire File» знову, і новий код запуститься на Лілці. Слід лише переконатись, що попередня версія вашої програми завершилася, перш ніж ви надсилати нову версію.

Інтерактивна консоль Lua (REPL)

REPL означає «Read-Eval-Print Loop». Це - інтерактивне середовище, яка дозволяє вам друкувати код на клавіатурі та виконувати його на Лілці прямо з вашого комп’ютера через USB-кабель, по одному рядку коду за раз.

Це зручно для тестування функцій, вивчення API, відлагодження тощо.

Для запуску Lua REPL вам потрібно відкрити на Лілці меню «Розробка» -> «Lua REPL». Лілка перейде в режим «Lua REPL» та очікуватиме команди через USB-порт.

Для цього відкрийте вкладку «Serial Monitor» у VS Code, оберіть COM-порт, на якому підключена Лілка, натисніть «Start Monitoring» і почніть вводити код Lua. Після кожної команди тисніть Enter. Вона виконається на Лілці, і ви побачите результат в консолі Visual Studio Code.

Спробуйте ввести, наприклад, ось такий код:

print(3 + 4)

Після введення цього рядка ви маєте побачити в консолі результат виразу 3 + 4, тобто число 7.

Тепер спробуйте ввести цей код:

display.fill_screen(display.color565(255, 0, 0))

Після введення другого рядка та натиску на клавішу Enter, екран Лілки має забарвитися червоним кольором.

Щоб вийти з режиму REPL, натисніть на Лілці кнопку A.