Шаблон для написания своих скриптов в модульном стиле для mcgl9
- 3d движок, позволяющий выводить простые объекты!
- Автодополнение для всех объектов из документации (display, key, user, sound, ...) благодаря использованию typescript
- Более удобная работа с клавишами и другими перечислимыми типами (например, вместо числовых кодов клавиш можно писать
KeyCode.F
) - Добавлена поддержка базовых отсутствующих функций (например, setTimeout, setInterval)
- Поддержка Promise и async/await (см. примеры)
- Получаемый результат практически не содержит оверхеда по размеру кода (благодаря использованию сборщика rollup и минималистичной библиотеке модулей)
- Множество модулей, упрощающих работу с mcgl9. В конечный скрипт попадут только те, что действительно используются!
Подготовка шаблона (требует предустановленных nodejs и npm):
- Склонировать себе репозиторий в любую папку
git clone https://github.com/iassasin/mcgl9-script
- Перейти в папку:
cd mcgl9-script
- Установить зависимости для сборки
npm install
- Теперь можно писать и собирать скрипты
Скрипт пишется в файле script.ts
с использованием любых нужных вам импортов. Вы вольны разбивать свой код на модули как угодно. Типичный скрипт выглядит следующим образом:
import mcgl9 from './mcgl9';
import {setInterval} from './mcgl9/timers'; // используемые модули
display.size(1, 1);
setInterval(() => display.print('hello'), 1000);
Получить готовый скрипт можно следующим образом:
- Написать скрипт в script.ts
- Выполнить
npm run build-mini
(илиnpm run build
для не-минифицированного варианта) - Забрать готовый скрипт из
dist/script.js
- Вставить содержимое файла
dist/script.js
в блокнот в игре, блокнот в mcgl9 и в проектор.
При разработке также может быть удобно, чтобы скрипт пересобирался автоматически. Для этого вместо второго шага можно выполнить:
npm run watch
Тогда при любом изменении в dist/
будет всегда актуальный скрипт.
Базовый модуль, обеспечивающий работу других модулей, а также предоставляющий стандартные для mcgl9 функции:
import mcgl9 from './mcgl9';
// инициализация (аналог функции init() из документации MCGL)
mcgl9.onUpdate((time) => {
// аналог функции update(time) из документации MCGL
});
Модуль, предоставляющий функции работы с таймерами, аналогичными стандартным в javascript. У них есть только одно отличие: коллбекам таймера нельзя передавать аргументы, как в стандартных для js функциях.
Пример:
import {setTimeout, setInterval, clearTimeout, clearInterval} from './mcgl9/timers';
let to = setTimeout(() => display.log('timeout'), 100);
clearTimeout(to); // отменить таймаут
let iv = setInterval(() => display.log('interval'), 1000);
clearInterval(iv); // отменить интервал
Предоставляет более привычные методы console.log
, console.warn
, console.error
, console.info
, принимающие несколько аргументов (в отличие от display.log
)
Пример:
import console from './mcgl9/console';
console.log(1, 2, 3); // => 1,2,3
console.info(1, 2, 3); // => [INFO] 1,2,3
console.warn(1, 2, 3); // => [WARN] 1,2,3
console.error(1, 2, 3); // => [ERROR] 1,2,3
Предоставляет простую реализацию промисов для mcgl9 с поддержкой методов Promise.resolve
, Promise.reject
и Promise.all
Пример:
import './mcgl9/promise';
import console from './mcgl9/console';
Promise.resolve('Hello')
.then(hello => `${hello}, world!`)
.then(console.log); // Hello, world!
Упрощение работы с клавиатурными нажатиями.
Пример:
import keyboard from './mcgl9/keyboard';
keyboard.onKeyDown(KeyCode.G, (code: KeyCode) => {
// Вызывается один раз при нажатии на клавишу G
});
keyboard.onKeyUp(KeyCode.G, (code: KeyCode) => {
// Вызывается один раз при отпускании клавиши G
});
keyboard.onKeyHold(KeyCode.G, (code: KeyCode) => {
// Вызывается каждый тик onUpdate, пока клавиша G нажата
});
Реализация простейшего 3d движка, работающего на базе display.voxel
. Примеры использований можно найти в папке examples
.
Все объекты создаются из шаблонов модели и размещаются на некоторой сцене. Лучше всего это увидеть на примере:
файл examples/3d-rocket.ts
снабжен комментариями, поясняющими основной функционал движка.
Минимальной единицей вывода на экран является Voxel
. Это обертка над display.voxel
для работы в движке.
import {Voxel, vec3} from './mcgl9/3d';
let voxel = new Voxel();
voxel.position = vec3(x, y, z); // смещение по x, y, z от центра родительского объекта
voxel.color = color.rgb(r, g, b); // цвет вокселя
voxel.scale = 1; // Представляет собой размер вокселя. Менять с осторожностью, т.к. это может сломать модели.
При созданию вокселю можно передать необязательные аргументы:
new Voxel({
position: vec3(1, 2, 3),
color: color.rgb(255, 0, 0), // красный
size: 2,
});
Как вы могли заметить, используется функция vec3
- она создает простой объект-вектор, содержащий в себе три компоненты:
let vec = vec3(1, 2, 3);
vec.x // 1
vec.y // 2
vec.z // 3
Модели представлены объектами Mesh, который состоит из вокселей и имеет следующие свойства:
import {Mesh, vec3, colorMask} from './mcgl9/3d';
let mesh = new Mesh();
mesh.position = vec3(x, y, z); // смещение по x, y, z от центра родительского объекта
mesh.scale = vec3(x, y, z); // масштаб по каждой оси. Например, увеличить объект в 3 раза - vec3(3, 3, 3),
// отразить объект по вертикали (верх станет низом) - vec3(1, -1, 1).
mesh.rotation = vec3(x, y, z); // Углы поворотов вдоль каждой отдельной оси. Поворот происходит относительно своего центра (pivot)
mesh.pivot = vec3(x, y, z); // Устанавливает точку поворота, т.е. центр объекта. Обычно его не нужно задавать самостоятельно, он берется из шаблона
mesh.color = colorMask(r, g, b, a); // Устанавливает маску цвета, применяемого к подобъектам. Например, при маске (1,0,0,1) белый цвет станет красным.
Удобно создавать модель с помощью функции createMeshFromTemplate
:
import {createMeshFromTemplate} from './mcgl9/3d';
let model = `
+
+++
+
`;
let mesh = createMeshFromTemplate(model); // создался экземпляр модели.
Особое назначение имеет символ p
внутри шаблона. По нему можно указать точку поворота, т.е. центр модели.
Кроме того, функция createMeshFromTemplate
умеет принимать вторым аргументом другую функцию, в которой можно переопределить создаваемые воксели.
Например:
import {createMeshFromTemplate, Voxel} from './mcgl9/3d';
let model = `
+
+p+
+
`;
let mesh = createMeshFromTemplate(model, point => {
// point - это текущий обрабатываемый воксель из шаблона.
// В данном случае он может принимать значения ' ', 'p' и '+'
switch (point) {
case ' ': return; // пустота, не должно быть вокселя
case 'p': // для центра также возвращать воксель
case '+': return new Voxel(); // часть модели, создаем воксель
}
});
Движок также позволяет создавать кастомные объекты на основе базового класса Transform
или переопределять трансформации
над группами объектов с помощью фунции createCustomTransform
. Это требует знаний работы с матрицами трансформации
из линейной алгебры.
Также есть функции для работы с векторами: vec3
, vecInvert
, vecAddVec
, vecNormalize
, vecMultVal
.
Предлагаю ознакомиться с дополнительными возможностями самостоятельно из исходников движка (они небольшие): mcgl9/3d/*
.