Сегодня мы перепишем на $mol эту демку почти пиксель в пиксель и напишем несколько тестов.

Демка представляет собой игру, в которой перемещаются разноцветные шарики между трубками, цель игры - отсортировать шарики по цветам за наименьшее количество шагов.

Изначально она была реализована на эффекторе + react, недавно несколько человек реализовали ее

• на реатоме + react исходники,

• на vue исходники

• и две независимых версии на моле

  • первая

  • моя, о ней пойдет речь

Там где не указана ссылка на исходники отдельно, она есть в самой демке

Постановка задачи

Экраны

• Start - стартовый экран на котором отображается заголовок, кнопка для запуска игры, и подвал с cсылками

• Game - при клике на кнопку запуска, открывается экран с игрой, на котором необходимо сортировать шарики. В хедере находятся кнопки возврата на стартовый экран и рестарта игры, а также счетчик числа сделаyных шагов. В центре трубки с шарами. В подвале те же ссылки что и на первом экране.

• Finish - когда шарики отсортированы, поверх второго экрана отображается третий экран. На нем находится заголовок "You won!", количество сделанных шагов, и кнопка "New game" которая открывает стартовый экран.

Механика игры

1. Рисуются 6 трубок, четыре и них заполнены шарами и две пустые

2. В заполненных трубках находятся по 4 шара, четырех разных цветов

3. При клике на непустую трубку, она переходит в активное состояние

   • В активном состоянии верхний шар в трубке переносится на ее крышку

4. Повторный клик по активной трубке дезактивирует ее, шар переносится обратно в нее

5. После активации трубки, клик по другой трубке переносит шар с крышки в другую трубку при условии, что другая трубка пуста или верхний шар другой трубки такого же цвета как шар на крышке активной трубке

6. Когда в одной и трубок все 4 шара одного цвета она переходит в статус готово, после этого шары в нее/из нее перемещать нельзя.

7. Игра закончится, когда 4 трубки перейдут в статус готово.

Подготовка

Начнем с самого начала, а именно с разворачивания мола и создания репозитория под проект.

Установка MAM-окружения

Можно использовать gitpod.io, окружение установится автоматически, согласитесь установить плагины. Или можно установить все локально:

1. Обновите NodeJS до LTS версии

2. Загрузите репозиторий MAM

git clone https://github.com/hyoo-ru/mam.git ./mam && cd mam

3. Установите зависимости, вашим пакетным менеджером

npm install

4. Установите плагины для VSCode EditorConfig vscode-language-tree

MAM-окружение достаточно установить один раз и использовать для всех проектов!

Создание и настройка репозитория

1. Идем сюда и нажимаем "Use this template" => "Create a new repository"

2. Выбираем владельца, указываем имя репозитория "ballsort", опционально заполняем описание, тип репозитория ставим публичным и нажимаем "Create repository from template"

3. Откройте настройки созданного репозитория нажав на "Settings"

4. В левом меню нажмите на "Actions" => "General", в разделе "Workflow permissions" отметьте чекбокс "Read and Write permissions" и нажмите "Save". Это нужно чтобы экшен деплоя на "github pages" мог задеплоить приложение.

В качестве неймспейса будем использовать имя "hype" и опустим создание репозитория под неймспейс.

5. Копируем ссылку на репозиторий и клонируем его в директорию mam/hype/ballsort

cd mam
# Только подставьте вашу ссылку
git clone https://github.com/PavelZubkov/ballsort.git hype/ballsort

Минималное приложение

1. Запускаем дев-сервер следующей командой

yarn start

2. Открываем в браузере http://127.0.0.1:9080

3. Вы увидите список файлов и директорий, расположенных в директории mam. Нажмите на "hyoo", затем на "ballsort", затем на "app" - откроется белый экран, это ок т.к. в app присутствует только файл index.html.

4. Откройте файл hype/ballsort/app/index.html и укажите имя модуля который будет монтироваться в атрибуте mol_view_root

<div mol_view_root="$hype_ballsort_app"></div>

5. В директории app создайте файл app.view.tree с содержимым ниже и сохраните его.

$hype_ballsort_app $mol_view
	sub / \Hello

6. Вернитесь в браузер и если все верно вы увидите приветствие

Деплой на github

В readme.md есть чек лист для настройки шаблонного репозитория

1. Переименуйте файл hype/ballsort/hyoo_template_app.yml в hype/ballsort/hype_ballsort_app.yml и откройте его

2. Измените имя на 3 строке

name: $hype_ballsort_app

3. На 19 строке укажите какой модуль будет собираться

	- uses: hyoo-ru/mam_build@master2
	with:
		package: 'hype/ballsort'
		modules: 'app'

4. Удалите блок деплоя в NPM, он начинается на 26 строке и заканчивается на 30 строке

5. В блоке деплоя на Github Pages измените путь до директории с бандлами

	- uses: hyoo-ru/gh-deploy@v4.4.1
	if: github.ref == 'refs/heads/master'
	with:
	folder: 'hype/ballsort/app/-'

6. Сделайте коммит и отправьте изменения в репозиторий на github

7. Возвращаемся в гитхаб, в разделе "Actions" ждем когда завершиться action "$hyoo_ballsort_app", и после него запуститься экшен "pages build and deployment"

8. Если второй экшен упадет, то открываем "Settings" => "Pages", в разделе "Branch" указываем ветку для деплоя "gh-pages" и нажимаем "Save". После этого второй экшен запуститься повторно, а после его завершения в разделе настроек "Pages" будет находится ссылка на приложение.

9. Если будут проблемы можете написать тут

Модель

Сначала напишем модель игры независимо от ее view-представления, а уже после отрисуем ее.

Я разделил игру на три модуля:

• game - основная логика

• ball - шар, тут только хранение цвета шаром

• tube - логика трубы

Начнем с ball

1. Создайте директорию ball и ts-файл в ней mam/hype/ballsort/ball/ball.ts

2. Для VSCode в MAM-окружении доступно несколько сниппетов

   • class - шаблон для файла с классом

   • logic - шаблон для создания класса с логикой для view-компонента

   • styles - шаблон для css.ts-файла со стилями

   • tests - шаблон для файла с тестами

3. Введите слово class, выберите "MAM class definition" и нажмите TAB или ENTER

4. Введите имя класса $hype_ballsort_ball и он должен наследоваться от $mol_object

$mol_object - это базовый класс с общей логикой, можете посмотреть его исходники самостоятельно. Т.к. имя сущности соответствует расположению сущности в исходном коде, то сможете без труда найти его. Репозиторий mol загрузился в MAM-окружение при установке сборщика. Можно просто нажать CTRL+P, ввести mol/object и нажать ENTER.

Сейчас у вас есть пустой класс:

	namespace $ {
		export class $hoop_ballsort_ball extends $mol_object {
	
		}
	}

ball будет хранить одно состояние - цвет шара, создадим свойство для него

	namespace $ {
		export class $hype_ballsort_ball extends $mol_object {
			
			@ $mol_mem
			color(next?: number) {
				return next ?? 0
			}	
			
		}
	}

В качестве значения цвета, мы будем использовать целые числа по порядку с 0 и далее. А при отображении view-компонент сам определит для какого числа какой цвет использовать.

Как это работает

При вызове метода без аргументов, он работает как геттер. При вызове с аргументом как сеттер.

Декоратор кеширует возвращенное значение из метода при первом вызове, а при повторном уже не запускает код метода, а просто возвращает значение из кеша.

Вновь код метода будет запущен только в двух случаях:

• если передали в него новое значение

• если код метода использует другие методы с декоратором, то в случае изменения их значения, декоратор поймет, что закешированное значение уже неактуально и при следующем вызове запустит код метода, чтобы получить актуальное значение

	const obj = new $hype_ballsort_ball
	obj.color() // 0
	obj.color(1) // 1
	obj.color() // 1

tube

Создайте директорию tube и ts-файл в ней mam/hype/ballsort/tube/tube.ts

За что будет отвечать трубка

• хранить массив шаров помещенных в нее

• определять находится ли она в состоянии готово

• выдавать нам верхний шар

• принимать от нас шар и класть наверх

Создайте класс, назовите его $hype_ballsort_tube и отнаследуйте от $mol_object.

	namespace $ {
		export class $hype_ballsort_tube extends $mol_object {
			
		}
	}

Добавим свойство для хранения шаров. Тут все точно также, как и у свойства color у шара, только в качестве значения используется массив, в котором хранятся объекты - инстансы класса $hype_ballsort_ball. По умолчанию возвращается пустой массив.

	namespace $ {
		export class $hype_ballsort_tube extends $mol_object {
			
			@ $mol_mem
			balls( next?: $hype_ballsort_ball[] ) {
				return next ?? []
			}
			
		}
	}

Чтобы отформатировать код также как у меня, нажмите CTRL+SHIFT+P, введите "Format" и выберите команду "Format document" :)

Теперь добавим свойство для определения состояния готово. Ему нужно знать сколько шаров одного цвета должно быть в трубке для перехода в готово, для этого добавим свойство size, без декоратора, оно будет переопределяется при инстанцировании класса.

	namespace $ {
		export class $hype_ballsort_tube extends $mol_object {
			//...

			size() {
				return 0
			}

			@ $mol_mem
			complete() {
				const [ ball, ...balls ] = this.balls()
				return this.balls().length === this.size() && balls.every( obj => obj.color() === ball.color() )
			}
			
		}
	}

Тут мы просто отделяем первый шар от остальных, и проверяем что цвет первого шара равен цветам остальных шаров. А также проверяем что количество шаров равно нужно величине.

Декоратор тут тоже кеширует возвращаемое значение, но само свойство read-only, т.к. в нем не предусмотрена передача значения при вызове. Оно зависит от свойства balls и свойств color у шаров, когда они изменятся, оно сбросит кеш и вернет актуальное значение.

И нам осталось добавить только свойства для вытаскивания верхнего шара и для того чтобы положить шар наверх.

	namespace $ {
		export class $hype_ballsort_tube extends $mol_object {
			//...

			@ $mol_action
			take() {
				const next = this.balls().slice()
				const ball = next.pop()
				this.balls( next )
				return ball
			}

			@ $mol_action
			put( obj: $hype_ballsort_ball ) {
				this.balls( [ ...this.balls(), obj ] )
			}
			
		}
	}

• take

  • берет массив из свойства balls

  • создает его копию. Нельзя мутировать массив, который хранится в декораторе!

  • из копии вытаскивает верхний шар

  • записывает обратно в balls массив без верхнего шара

  • и возвращает шар

• put

  • принимает шар в качестве аргумента

  • записывает в свойство balls новый массив, который создается из старого плюс принятый шар

game

Переходим к основной логике игры.

1. Создайте директорию game и ts-файл в ней mam/hype/ballsort/game/game.ts

2. Создайте класс, назовите его $hype_ballsort_game и отнаследуйте от $mol_object

	namespace $ {
		export class $hype_ballsort_game extends $mol_object {
			
		}
	}

Мы не будем хардкодить сказанное в правилах, что заполненных трубок только четыре, что всего четыре цвета у шаров и т.д. Для начала создадим свойства в которых будут храниться эти константы

	namespace $ {
		export class $hype_ballsort_game extends $mol_object {
			
			color_count() { return 4 } // Количество цветов

			// Количество шаров одного цвета
			// которое надо собрать в трубке
			// для перехода в состоянии готово
			tube_size() { return 4 }

			// Количество пустых трубок
			tube_empty_count() { return 2 }

			// Общее количество трубок
			tube_count() { return this.color_count() + this.tube_empty_count() }

			// Общее количество шаров
			ball_count() { return this.tube_size() * this.color_count() }
			
		}
	}

Теперь нам нужно научиться инстанцировать шары и создать требуемое количество шаров.

	namespace $ {
		export class $hype_ballsort_game extends $mol_object {
			//...

			@ $mol_mem_key
			Ball( index: number ) {
				return new $hype_ballsort_ball
			}
			
		}
	}

Как это работает 2?

Декоратор $mol_mem_key работает точно также, как и декоратор $mol_mem, за одним исключением - первым аргументом он всегда принимает ключ. Ключ является обязательным параметром. В итоге у нас получает набор из произвольного количества состояний, с доступом к каждому по ключу.

В данном случае свойство Ball является read-only свойством, т.к. у него нет второго параметра next. Оно возвращает инстанс класс, т.е. это свойство-фабрика. А в качестве ключей будут использоваться индексы и у шаров и у трубок, но вообще можно использовать произвольный объект.

При вызове с любым индексом, оно вернет объект и запомнит его под этим индексом, и при следующих обращениях будет возвращать уже созданный объект из кеша.

Важно: инстанцировать объекты необходимо через свойства-фабрики!

	const obj = new $hype_ballsort_game
	const ball1 = obj.Ball(0) // возвращает объект - инстанс шара
	const ball2 = obj.Ball(1)
	ball1 === ball2 // false - это два разных инстанса

Теперь создадим свойство генерирующее шары

	namespace $ {
		export class $hoop_ballsort_game extends $mol_object {
			//...

			@$mol_mem_key
			Ball( index: number ) {
				return new $hype_ballsort_ball
			}

			@$mol_mem
			balls() {
				return Array.from( { length: this.ball_count() } ).map( ( _, index ) => {
					const obj = this.Ball( index )
					obj.color( index % this.tube_size() )
					return obj
				} )
			}
			
		}
	}

• Свойство balls при первом запуске создаст массив с шарами и вернет его, а декоратор закеширует этот массив. При последующих вызовах будет возвращать массив из кеша. Работает так:

1. Создаем массив через Array.from с указанным количеством элементов ball_count()

2. Для каждого индекса в массиве создаем шар через Ball и устанавливаем этому шару цвет

3. Возвращаем массив из свойства

Создаем трубки

Трубки создаются похожим образом

	namespace $ {
		export class $hoop_ballsort_game extends $mol_object {
			//...

			@ $mol_mem_key
			Tube( index: number ) {
				const obj = new $hype_ballsort_tube
				obj.size = () => this.tube_size()
				return obj
			}

			@ $mol_mem
			tubes() {
				const balls = $mol_array_shuffle( this.balls() )
				const size = this.tube_size()

				return Array.from( { length: this.tube_count() } ).map( ( _, index ) => {
					const obj = this.Tube( index )
					const list = index < this.color_count() ? balls.slice( index * size, index * size + size ) : []
					obj.balls( list )
					return obj
				} )
			}
			
		}
	}

• Свойство-фабрика Tube работает аналогичным образом, как и Ball, только оно после создания объекта устанавливает ему size, мы говорили про это выше - оно нужно трубке чтобы определить готовность.

• Свойство tubes

  1. Получает шары и перемешивает их через $mol_array_shuffle

  2. Кладет в переменную size, для более короткой записи при использовании

  3. Через Array.from создает массив, длина которого сразу учитывает и пустые трубки

  4. Для каждого элемента мы создаем трубку

  5. Устанавливаем шары для не пустой трубке или пустой массив если трубка должна быть пустой

  6. И возвращаем полученный массив трубок

Дело за малым

Нам потребуется свойства moves в котором будем хранить число шагов и увеличивать с каждым ходом.

	namespace $ {
		export class $hoop_ballsort_game extends $mol_object {
			//...

			@$mol_mem
			moves( next?: number ) {
				return next ?? 0
			}
			
		}
	}

Нам понадобится свойство для хранения активной трубки. Напомню: при клике пользователя по трубке, она становится активной.

	namespace $ {
		export class $hoop_ballsort_game extends $mol_object {
			//...
			
			@ $mol_mem
			tube_active( next?: $hype_ballsort_tube | null ) {
				if (next?.balls().length === 0) return null
				if (next?.complete()) return null
				return next ?? null
			}
			
		}
	}

Это изменяемое свойство - у него есть параметр next, хранит оно объект активной трубки. А также оно принимает значение null, оно туда будет передаваться, когда необходимо дезактивировать трубку.

А также

• Если в трубке шаров нет - то ее нельзя активировать

• Если трубка уже в состоянии готово - ее тоже нельзя активировать

Теперь напишем свойство, которое будет переносить шар из активной трубки from, в нужную to.

	namespace $ {
		export class $hoop_ballsort_game extends $mol_object {
			//...
			
			@ $mol_action
			ball_move( to: $hype_ballsort_tube ) {
				const from = this.tube_active()

				if (to === from || !from) return this.tube_active(null)

				const from_color = from?.balls().at(-1)?.color()
				const to_color = to.balls().at(-1)?.color()
				if (to.balls().length && from_color !== to_color) return

				const ball = from.take()!
				to.put( ball )

				this.moves( this.moves() + 1 )
				this.tube_active( null )
			}
			
		}
	}

1. На вход принимаем объект трубки, в которую будем переносить шар из активной трубки

2. Если активной трубки нет или активная трубка и трубка, в которую переносим это одна трубка - снимаем с трубки активность и выходим

3. Проверяем что цвета верхних шаров в обоих трубках совпадают, т.к. друг на друга можно класть шары только одого цвета

4. Если все ок, то методами take и put достаем шар из одной и кладем в другую

5. Увеличиваем счетчик шагов moves

6. Дезактивируем трубку

Предпоследний штрих

Чтобы не сваливать на view-компонент задачу поочередного вызывания tube_active и ball_move, добавим свойство tube_click.

	namespace $ {
		export class $hoop_ballsort_game extends $mol_object {
			//...
			
			@ $mol_action
			tube_click( tube: $hype_ballsort_tube ) {
				const tube_active = this.tube_active()

				tube_active === null ? this.tube_active( tube ) : this.ball_move( tube )
			}
			
		}
	}

View-компонент будет вызывать этой свойство, передавая туда трубку по которой кликнул пользователь.
Логика проста:

• Если при клике активной трубки нет, то делаем активной переданную трубку

• Если активная трубка уже есть, то вызываем ball_move, что бы шар переместился из активной в переданную трубку

Последний штрих

Нам нужно свойство, которое будет сигнализировать о том, что игра закончена.

	namespace $ {
		export class $hoop_ballsort_game extends $mol_object {
			//...
			
			@ $mol_mem
			finished() {
				return this.tubes().every( tube => tube.complete() || tube.balls().length === 0 )
			}
			
		}
	}

Игра заканчивается, когда каждая трубка в статусе готово или у нее нет шаров.

Мы тут специально не обрабатываем некоторые случаи, например в активации трубы нет проверки на то что игра закончена, т.к. предполагаем что интерфейс не будет обрабатывать клики на трубки после окончания игры.

Время тестов

Создайте файл game.test.ts в директории hype/ballsort/game, и выполните сниппет tests.

	namespace $.$$ {
		$mol_test({
			
			""( $ ) {
				
			},
			
		})
	}

Как это работает 3?

Для описания тестов есть функция $mol_test, она принимает объект с тестами. Каждый тест - это метод на этом объекте. Имя метода - название теста, а код метода - это код теста. Так же в метод при запуске передается контекст, но это уже совсем другая история.

Сначала напишем простой демо-тест.

	namespace $.$$ {
		$mol_test({
			
			"Moves initially zero"() {
				const obj = new $hype_ballsort_game

				$mol_assert_equal(obj.moves(), 0)
			},
			
		})
	}

Чтобы запустить тесты, обычно ничего делать не надо, когда мы открываем в браузере какое-то приложение, dev-сервер собирает отдельный бандл с тестами, который содержит тесты всех модулей от которых зависит приложение.

Можно заметить, что в урле запрашивается файл test.html, в него сборщик добавляет загрузку бандла с тестами. Тесты прогоняются при каждой перезагрузке страницы.

Но у нас пока в приложении выводится только приветствие, мы можем попросить dev-сервер отдать нам test.html модуля game, он положит туда тест, который мы написали.

Откройте ссылку http://127.0.0.1:9080/hoop/ballsort/game/-/test.html - вы увидите белый экран, в game нет view-компонентов. Откройте консоль в девтулзах.

Зеленьким "All test passed" - ни один тест не упал. Число 92 - количество запущеных тестов, это тесты модулей от которых зависит наш код.

Сломайте тест, вместо 0 поставив 1, сохраните и загляните в консоль. Тест упал:

Можете удалить демо-тест.

Переход трубок в состояние готово

Для начала проверим что трубка корректно переходит в состояние готово.
Нам нужно:

1. Создать игру

2. Достать заполненную трубку

3. На всякий случай убедимся, что изначально нет трубок в состоянии готово

4. Установим всем шарам одинаковый цвет

5. Убедимся, что трубка перешла в состояние готово

	namespace $ {

		$mol_test( {

			'tube completing'() {

				const game = new $hype_ballsort_game // 1
				const tube = game.tubes().find( obj => obj.balls().length > 0 )! // 2
				$mol_assert_not( tube.complete() ) // 3

				tube.balls().forEach( ball => ball.color( 0 ) ) // 4

				$mol_assert_ok( tube.complete() ) //5

			}

		} )
	}

Проверим что трубка в состоянии готово не активируется

	namespace $ {

		$mol_test( {
			//...

			'completed tube non activation'() {
				// Создаем игру и берем трубку с шарами
				const game = new $hype_ballsort_game
				const tube = game.tubes().find( obj => obj.balls().length > 0 )!

				$mol_assert_not(game.tube_active()) // Активных нет

				tube.balls().map(obj => obj.color(0)) // Красим шары 

				game.tube_click(tube) // Кликаем по трубке
				$mol_assert_not(game.tube_active()) // Активных трубок все еще нет
			},

		} )
	}

Проверим что пустая трубка не активируется

	namespace $ {

		$mol_test( {
			//...

			'empty tube non activation'() {
				const game = new $hype_ballsort_game
				// Берем пустую трубку
				const tube = game.tubes().find( obj => obj.balls().length === 0 )!

				$mol_assert_not(game.tube_active())

				// Кликаем и убеждаемся что активных трубок нет
				game.tube_click(tube)
				$mol_assert_not(game.tube_active())
			},

		} )
	}

Проверим активацию трубок

Для этого нам надо:

1. Создать инстанс игры

2. Взять из него трубку с шариками и пустую трубку

3. На всякий случай убедимся, что активных трубок нет

4. Кликнем по заполненной трубке, проверим что она активна

5. Кликнем по пустой трубке и проверим что активных трубок снова нет

6. Кликнем на трубку, в которую положили шар и убедимся, что она активировалась

	namespace $ {

		$mol_test( {
			//...

			'tube activation'() {
				const game = new $hype_ballsort_game
				const tube_filled = game.tubes().find( obj => obj.balls().length > 0 )!
				const tube_empty = game.tubes().find( obj => obj.balls().length === 0 )!

				$mol_assert_not(game.tube_active())

				game.tube_click(tube_filled)
				$mol_assert_equal(tube_filled, game.tube_active())

				game.tube_click(tube_empty)
				$mol_assert_not(game.tube_active())

				game.tube_click(tube_empty)
				$mol_assert_equal(tube_empty, game.tube_active())
			},

		} )
	}

Попробуем переместить шар

	namespace $ {

		$mol_test( {
			//...
			
			'ball moving'() {
				const game = new $hype_ballsort_game

				// Берем заполненную и пустую трубки, а также шар который будет перемещаться
				const tube_filled = game.tubes().find( obj => obj.balls().length > 0 )!
				const tube_empty = game.tubes().find( obj => obj.balls().length === 0 )!
				const ball_moving = tube_filled.balls().at( -1 )!

				// Кликаем на заполненую трубку и на пусую
				game.tube_click( tube_filled )
				game.tube_click( tube_empty )

				// Убеждаемся что именно этот шар убыл из одной трубки и прибыл в другую
				$mol_assert_equal( tube_filled.balls().length, game.tube_size() - 1 )
				$mol_assert_not( tube_filled.balls().includes( ball_moving ) )

				$mol_assert_equal( tube_empty.balls().length, 1 )
				$mol_assert_ok( tube_empty.balls().includes( ball_moving ) )
			},


		} )
	}

Проверим что счетчик увеличивается при перемещении шара

	namespace $ {

		$mol_test( {
			//...
			
			'moves increment'() {
				const game = new $hype_ballsort_game
				const tube_filled = game.tubes().find( obj => obj.balls().length > 0 )!
				const tube_empty = game.tubes().find( obj => obj.balls().length === 0 )!

				game.tube_click( tube_filled )
				game.tube_click( tube_empty )
				$mol_assert_equal( game.moves(), 1 )
			},


		} )
	}

Проверим что игра заканчивается

	namespace $ {

		$mol_test( {
			//...
			
			'game finish'() {
				const game = new $hype_ballsort_game

				$mol_assert_not( game.finished() )

				game.balls().forEach( ball => ball.color( 0 ) )
				$mol_assert_ok( game.finished() )
			},


		} )
	}

Что дальше?

Продолжение с pixel perfect версткой будет в следующей части. А также напишем тестов для проверки всего приложения.

А пока можете разобраться в моделях/view-моделях других реализация:

• Effector

• Reatom

• Vue

• $mol другая реализация

• Весь код из статьи в этом репозитории

Часть 2

По всем вопросам можно идти сюда.