Mysh

🧠 ECS-фреймворк на TypeScript для архитектурно чистых и масштабируемых игр.

📖 Оглавление

• Введение
• Установка
• Быстрый старт
• Когда использовать Mysh
• Не подходит, если...
• Основы архитектуры ECS
  • Entity
  • Component
  • System
• Управление потоком (Flow)
• Группы систем (SystemGroup)
• Состояния (FSM)
• Дополнительные возможности
  • Сервисы
  • Store
• Лицензия

🧠 Введение

Mysh — это ECS-фреймворк (Entity Component System) на TypeScript, спроектированный для масштабируемой, модульной и легко тестируемой архитектуры. Он не содержит графических или рендеринговых решений, предоставляя разработчику полный контроль над структурой и логикой игры.

📦 Установка

npm install myshengine-core

🚀 Быстрый старт

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

const handlers: ISignalConfig[] = [
    {
        signal: OnUpdateSignal,
        executions: [{ group: OnUpdateGroup }],
    },
];

const mysh = new MyshApp();
mysh.init();
mysh.listen(handlers);

🧭 Когда использовать Mysh

Используйте Mysh, если вы:

• Строите масштабируемую архитектуру с низкой связанностью
• Используете рендерер (PixiJS, Cocos, WebGL и пр.) и хотите ECS-ядро
• Предпочитаете event-driven или гибридный подход
• Хотите изолировать игровую логику от рендера
• Работаете с FSM, DI и Store
• Разрабатываете движок или расширяемый фреймворк

🚫 Не подходит, если...

Mysh не подойдёт, если вы:

• Ожидаете встроенный движок с графикой и UI
• Хотите визуальную среду разработки
• Не знакомы с ECS или DI
• Ищете комплексное решение с ассет-менеджментом и анимацией

🧱 Основы архитектуры ECS

Entity

Entity — логическое представление игрового объекта. Оно содержит компоненты и предоставляет API для их управления.

const entity = new Entity('player');
entity.addComponent(new HealthComponent());
entity.removeComponent(HealthComponent);
entity.hasComponents([HealthComponent]);

Component

В качестве компонента может выступать любой класс. Это могут быть как простые структуры данных, так и классы с логикой (если это оправдано архитектурно).

class HealthComponent {
    public value = 100;
}

System

Системы реализуют игровую логику. Они независимы друг от друга и работают с сущностями, отфильтрованными по нужным компонентам.

class DamageSystem extends System {
    public execute(): void {
        const entities = this.filter({ includes: [HealthComponent] });

        entities.forEach((entity) => {
            const health = entity.getComponent(HealthComponent);
            health.value -= 10;
        });
    }
}

🔄 Управление потоком (Flow)

Mysh поддерживает два подхода:

• Update-driven: классическое выполнение систем каждый кадр (в Update Loop).
• Event-driven: системы выполняются только при необходимости, реагируя на события.

Оба подхода можно свободно комбинировать в рамках одного проекта.

📚 Группы систем (SystemGroup)

Группы систем позволяют задать точный порядок их выполнения.

class GameLoopGroup extends SystemGroup {
    public setup(): IGroupOption[] {
        return [
            { instance: this.provide(InputSystem, null) },
            { instance: this.provide(PhysicsSystem, null) },
            { instance: this.provide(RenderSystem, null) },
        ];
    }
}

🧠 Состояния (FSM)

FSM в Mysh — это мощный инструмент для управления игровым потоком. Поддерживаются вложенные состояния, переходы с проверками, глобальное хранилище (Store), события входа/выхода и многое другое.

const fsm = new FSM({
    name: 'mainFlow',
    initialState: 'boot',
    states: [
        {
            name: 'boot',
            transitions: { init: 'loading' },
            onEnter: [BootGroup],
        },
        {
            name: 'loading',
            transitions: { done: 'play' },
            onEnter: [LoadAssetsGroup],
        },
        {
            name: 'play',
            transitions: { error: 'error' },
        },
    ],
});

🛠 Дополнительные возможности

Сервисы

Сервисы — это классы с общей логикой, доступные во всех системах и группах через Dependency Injection.

class LoggerService {
    log(msg: string) {
        console.log(msg);
    }
}

const LOGGER = Symbol('LOGGER');

class MySystem extends System {
    @Inject(LOGGER) private logger!: LoggerService;

    public execute() {
        this.logger.log('System executed');
    }
}

class MyGroup extends SystemGroup {
    public setupDependencies(): Provider[] {
        return [{ provide: LOGGER, useClass: LoggerService }];
    }
}

Store

Store — глобальное иммутабельное хранилище данных, интегрируемое в FSM и Системы.

const store = new Store<{ score: number }>({ score: 0 });

store.setState((state) => ({
    score: state.score + 10,
}));

📄 Лицензия

MIT License © 2025 Daniil Stolpnik