# Учебный движок для создания 2D-игр "GameStudy" # Учебный движок предназначен для быстрой и легкой разработки простейших 2D-игр с использованием спрайтов, анимаций, надписей, графических примитивов и звуковых эффектов. Сама игра реализуется как программа на диалекте JavaScript путем наполнения кодом трех функций - инициализации игры, рендера игры и обработки состоянии игры. ## Содержание ## 1. Структура движка 2. Создание игры 3. Простейший пример игры 4. Объекты движка и их функции 5. Приложение 1. Свойства и ограничения 6. Приложение 2. Список кодов клавиш ### Структура движка ### В корневом каталоге движка размещается файл GameStudy.exe, запуск которого загружает созданную игру. Все файлы .dll и подкаталог platforms - это библиотеки, необходимые для работы движка. Подкаталог scripts - содержит программу main.js на диалекте JavaScript (см. Приложение 1) с кодом игры. Остальные подкаталоги содержат ресурсы игры, которые загружаются в коде. - fonts - шрифты TTF - sounds - звуки - sprites - спрайты ### Создание игры ### Чтобы создать игру, нужно скопировать ресурсы разрабатываемой игры в соответствующие каталоги движка и наполнить функции в шаблонном файле main.js загрузкой ресурсов, рендером (выводом графики) и обработкой состояния игры. Предопределенные функции main.js: function Init() { } Функция вызывается один раз в момент старта игры, в ней нужно разместить все загрузки ресурсов и инициализацию переменных. Функция должна возвращать значение true. function Render() { } Функция вызывается каждый раз, когда движок перерисовывает игровое окно, в ней нужно выводить все спрайты и надписи. Функция должна возвращать значение true. function Frame(dt) { } Функция вызывается каждый раз, когда движок пересчитывает состояние игры, в ней нужно обновить состояние игровых объектов (позиции, счетчики и прочее). Параметр dt - время в секундах с момента последнего вызова функции Frame, число двойной точности. Функция должна возвращать значение true, возврат false означает остановку игры. ### Простейший пример игры ### В каталоге sprites размещаем файл player.png В файле main.js размещаем код // Переменную для спрайта нужно объявить в начале, чтобы её видели все функции var spr_player ; // То же для переменных координат спрайта var player_x ; var player_y ; // Функция инициализации function Init() { // Загрузка спрайта spr_player = game.loadSprite('player.png') ; // Установка координат для вывода player_x=400 ; player_y=300 ; return true ; } // Функция рендера function Render() { // Выводим спрайт в заданные координаты spr_player.renderTo(player_x,player_y) ; return true ; } // Функция фрейма function Frame(dt) { // Обрабатываем нажатия клавиш if (game.isKeyDown(KEY_LEFT)) player_x-=10 ; if (game.isKeyDown(KEY_RIGHT)) player_x+=10 ; if (game.isKeyDown(KEY_UP)) player_y-=10 ; if (game.isKeyDown(KEY_DOWN)) player_y+=10 ; return true ; } Данная игра выводит спрайт player.png и двигает его под действием клавиш-стрелок на клавиатуре. ### Объекты движка и их функции ### #### Глобальные объекты #### В движке определены несколько глобальных объектов, методы которых вызываются из кода игры. **Объект game** Содержит функции загрузки ресурсов, создания графических примитивов, обработки нажатия клавиш и мыши. Функции объекта game loadSprite(filename) Создает и возвращает объект спрайта. Параметр - имя файла из каталога sprites. loadAnimationFromFiles(filenames, fps) Создает и возвращает объект анимации из набора файлов. Параметры - массив имен файлов из каталога sprites, которые образуют отдельные кадры анимации, и FPS анимации. Пример вызова - loadAnimationFromFiles(['1.png','2.png','3.png',7) loadAnimation(filename, w, h, framecount, fps) Создает и возвращает объект анимации из одного файла, содержащего несколько кадров. Параметры - имя файла из каталога sprites, ширина и высота отдельного фрейма, число фреймов и FPS анимации. Фреймы считываются из файла слева направо, сверху вниз. loadText(fontname,text,size) Создает и возвращает объект надписи. Параметры - имя шрифта из каталога fonts (вместе с расширением, например, "Arial.ttf"), текст надписи, размер шрифта в надписи. loadSound(filename) Создает и возвращает объект звука. Параметр - имя файла из каталога sounds. createLine(r,g,b) Создает и возвращает объект линии. Параметры - компоненты цвета линии в RGB. isKeyDown(keycode) Проверяет, была ли нажата клавиша клавиатуры. Параметр - код клавиши (именованные константы клавиш приведены в Приложении 2) isLeftButtonClicked() Проверяет, была ли нажата левая кнопка мыши. isRightButtonClicked() Проверяет, была ли нажата правая кнопка мыши. getMousePos() Возвращает координаты мыши в игровом окне как объект с полями x и y. setGameTitle(title) Устанавливает заголовок окна с игрой. Параметр - строка заголовка. getTotalTime() Возвращает общее время с момента начала игры в секундах. resetTotalTime() Сбрасывает счет общего времени с момента начала игры в ноль. getFPS() Получает текущий FPS, усредненный за последнюю секунду. setBackgroundColor(r,g,b) Устанавливает цвет фона окна. Параметры - компоненты цвета текста в RGB **Объект system** Содержит функции вывода отладочного текста и отключения встроенного курсора мыши (это нужно, если игра реализует собственный курсор). Функции объекта system writeMessage(msg) Выводит в текстовое поле окна отладочное сообщение. Параметр - текст сообщения. showCursor(show) Позволяет включить или отключить показ системного курсора в окне игры. Параметр - значение true или false. saveObject(filename, value) Позволяет записать в файл JSON заданный объект или массив. Параметры - имя файла и объект. Пример - мы создаём объект var state1 = { x: 1, msg:«OK», q:true }, и записывая его в файл, получим содержимое { "msg": "OK", "q": true, "x": 1 } это позволяет сохранять данные из игры на диск. loadObject(filename) Считывает из файла JSON объект или массив и возвращает его. Параметр - имя файла. Работает как обратная функция для saveObject, восстанавливая объект или массив. Это позволяет как считывать ранее сохраненные данные, так и загружать в код данные из JSON-файлов, чтобы не перегружать код игры текстовыми значениями. #### Загружаемые объекты ресурсов #### Функции загрузки объектов создают объекты ресурсов, которые далее можно использовать в коде игры. **Объект спрайта** Содержит графический спрайт, создается методом loadSprite, может выводиться в заданное место на экране. Функции объекта спрайта renderTo(x,y) Выводит спрайт со всеми установленными параметрами в окно игры. Параметры - координаты вывода спрайта относительно его начальной точки (см. функцию setHotSpot) render() Выводит спрайт со всеми установленными параметрами в окно игры, используя текущее положение x и y. setXY(x,y) Устанавливает для спрайта положение на экране. Параметры - координаты вывода спрайта относительно его начальной точки (см. функцию setHotSpot) setScale(scale) Устанавливает масштаб спрайта. Параметр - масштаб объекта относительно исходного в процентах. setAngle(angle) Устанавливает поворот спрайта. Параметр - угол поворота спрайта вокруг его начальной точки (см. функцию setHotSpot) в радианах. setAlpha(alpha) Устанавливает прозрачность спрайта. Параметр - значение прозрачности от 0 до 255, где 0 - это полностью прозрачный объект, 255 - полностью непрозрачный. setHotSpot(x,y) Устанавливает начальную точку спрайта, относительно которой работают операции вывода спрайта на экран и поворота на угол. Параметры - координаты точки в пикселях от левого верхнего угла спрайта. По умолчанию, функция loadSprite устанавливает после загрузки спрайта его точку в геометрический центр, таким образом, поворот идет сразу вокруг центра. mirrorHorz(mirror) Устанавливает отражение спрайта по горизонтали. Параметр - true или false, если передано true, то объект разворачивается при выводе зеркально слева направо. mirrorVert(mirror) Устанавливает отражение спрайта по вертикали. Параметр - true или false, если передано true, то объект разворачивается при выводе зеркально сверху вниз. setBordered(bordered) Включает или отключает отображение белой рамки толщиной в один пиксель вокруг спрайта. Рамка при отображении учитывает все изменения спрайта, масштабы и повороты. setContactModelBox() Устанавливает прямоугольную модель проверки коллизии для спрайта. setContactModelCircle() Устанавливает эллиптическую модель проверки коллизии для спрайта. isContactWith(sprite) Возвращает наличие коллизии спрайта и спрайта, переданного как параметр. Модель проверки коллизии устанавливается процедурами setContactModelBox и setContactModelCircle, по умолчанию равна прямоугольной. При использовании прямоугольной модели - коллизия возникает, если прямоугольники спрайтов пересекаются. При использовании эллиптической модели - коллизия возникает, если расстояние между центрами спрайтов меньше, чем сумма условных радиусов эллипсов, в которые вписывается спрайт. Для спрайтов визуально круглой формы (шары) целесообразно использовать эллиптическую модель, для спрайтов квадратных (коробки) - лучше работает прямоугольная модель. Обе модели учитывают все изменения спрайтов, масштабы и повороты. isPointIn(x,y) Возвращает вхождение точки в спрайт, с учётом всех изменений спрайтов, масштабы и повороты. Параметры - координаты проверяемой точки. setTag(tagname,tagvalue) Устанавливает для спрайта тэг с именем tagname в значение tagvalue. tagname должен быть строкой, а tagvalue может быть любым, включая примитивы, массивы и объекты с полями. getTag(tagname) Возвращает тэг с именем tagname, заданный ранее. getWidth() Возвращает ширину спрайта. getHeight() Возвращает высоту спрайта. **Объект анимации** Содержит анимацию, создается методами loadAnimationFromFiles и loadAnimation. Он поддерживает все методы объекта-спрайта, а также несколько специфичных методов для анимации Функции объекта анимации play() Запускает бесконечный цикл анимации объекта. playOnce() Запускает однократный цикл анимации объекта, по завершении, анимация останавливается. stop() Останавливает цикл анимации объекта. **Объект надписи** Содержит надпись, создается методом loadText, может выводиться в заданное место на экране. Функции объекта надписи printTo(x,y) Выводит надпись со всеми установленными параметрами в окно игры. Параметры - координаты вывода текста относительно его левого верхнего угла. setText(text) Устанавливает текст надписи. Параметр - текст. Возможно использовать в тексте Escape-последовательность \n для установки переноса текста в надписи. setSize(size) Устанавливает размер текста надписи. Параметр - размер. setColor(r,g,b) Устанавливает цвет текста надписи. Параметры - компоненты цвета текста в RGB **Объект звука** Содержит звуковой эффект, создается методом loadSound, может воспроизводиться. Функции объекта звука play() Воспроизводит звуковой эффект от начала до конца, один раз. Не приводит к остановке выполнения программы на время воспроизведения, звук запускается в отдельном потоке! Также звуки могут накладываться друг на друга, если вызывать play() чаще, чем длина звука. stop() Останавливает воспроизведение звука. isPlayed() Возвращает логическое значение, соответствующее статусу звука - воспроизводится или нет в данный момент. setLoop(isloop) Устанавливает тип воспроизведения - если true, то звук будет крутиться в кольце. По умолчанию, звук воспроизводится только один раз. **Объект линии** Содержит линию толщиной в один пиксель, создается методом createLine, может выводиться в заданное место на экране. Функции объекта линии drawTo(x1,y1,x2,y2) Выводит линию со всеми установленными параметрами в окно игры. Параметры - координаты начала и конца линии. setColor(r,g,b) Устанавливает цвет линии. Параметры - компоненты цвета линии в RGB ### Приложение 1. Свойства и ограничения ### - Размер игрового окна: 800x600 пикселей. - Кодировка файла main.js: UTF-8 - Кодировка сохраняемых и загружаемых файлов JSON: UTF-8 - Для использования шрифта, его обязательно нужно скопировать из %WINDIR%/Fonts в каталог fonts. - Звуковые файлы должны иметь форматы WAV или OGG. MP3 не поддерживается, рекомендуется выполнить преобразование в несжатый WAV. - Файлы спрайтов могут иметь форматы JPG, PNG, GIF, BMP, TGA (формат GIF поддерживается как статичный - если загружаем анимированный спрайт, то будет выводиться только первый кадр) - Язык программирования файла main.js совместим с языком JavaScript, и выполняет стандарт ECMAScript (подробнее см. на [https://ru.wikipedia.org/wiki/ECMAScript](https://ru.wikipedia.org/wiki/ECMAScript)) ### Приложение 2. Список кодов клавиш ### Для удобства разработки игры, движок определяет набор констант кодов большинства клавиш. Их можно использовать в функции isKeyDown по имени константы, или указывая непосредственное числовое значение, если так удобнее. KEY_ESCAPE = 0x01000000 KEY_TAB = 0x01000001 KEY_ENTER = 0x01000005 KEY_LEFT = 0x01000012 KEY_UP = 0x01000013 KEY_RIGHT = 0x01000014 KEY_DOWN = 0x01000015 KEY_SHIFT = 0x01000020 KEY_CONTROL = 0x01000021 KEY_ALT = 0x01000023 KEY_F1 = 0x01000030 KEY_F2 = 0x01000031 KEY_F3 = 0x01000032 KEY_F4 = 0x01000033 KEY_F5 = 0x01000034 KEY_F6 = 0x01000035 KEY_F7 = 0x01000036 KEY_F8 = 0x01000037 KEY_F9 = 0x01000038 KEY_F10 = 0x01000039 KEY_F11 = 0x0100003a KEY_F12 = 0x0100003b KEY_SPACE = 0x20 KEY_PLUS = 0x2b KEY_MINUS = 0x2d KEY_0 = 0x30 KEY_1 = 0x31 KEY_2 = 0x32 KEY_3 = 0x33 KEY_4 = 0x34 KEY_5 = 0x35 KEY_6 = 0x36 KEY_7 = 0x37 KEY_8 = 0x38 KEY_9 = 0x39 KEY_A = 0x41 KEY_B = 0x42 KEY_C = 0x43 KEY_D = 0x44 KEY_E = 0x45 KEY_F = 0x46 KEY_G = 0x47 KEY_H = 0x48 KEY_I = 0x49 KEY_J = 0x4a KEY_K = 0x4b KEY_L = 0x4c KEY_M = 0x4d KEY_N = 0x4e KEY_O = 0x4f KEY_P = 0x50 KEY_Q = 0x51 KEY_R = 0x52 KEY_S = 0x53 KEY_T = 0x54 KEY_U = 0x55 KEY_V = 0x56 KEY_W = 0x57 KEY_X = 0x58 KEY_Y = 0x59 KEY_Z = 0x5a