# Forma Engine

A browser-based 2D/3D editor, runtime and local MCP server for building interactive projects by hand or with an AI assistant. Built with TypeScript, React, Babylon.js and Rapier.

**Early prototype · 0.3.0.** This repository contains the engine, editor and build tools. User games and assets are not included; a small original 2D platformer template is bundled. The editor interface is currently in Russian.

![Forma Engine editor with a primitive scene, hierarchy and component inspector](docs/screenshots/editor.jpg)

The screenshot shows a temporary scene made with the editor's primitives. New projects start empty.

## Quick start

Requires **Node.js 22.13+**, npm and a desktop browser with WebGL. Linux is the primary development platform.

```bash
git clone https://github.com/emil28092005/forma-engine.git
cd forma-engine
npm ci
npm run build
npm start
```

Open **http://127.0.0.1:4318/**. The first run creates a blank project in `projects/MyGame`; subsequent runs reopen it. To choose a project folder or port:

```bash
npm start -- --project ./projects/MyProject --port 4320
```

Projects remain on your computer. Rendering, physics and scripts run in the browser; the local Node server handles files, MCP requests and optional application builds. No hosted account or AI API key is required to run the engine.

## Capabilities

- Scene hierarchy, component inspector, transform gizmos, command search and undo/redo.
- Multiple scenes, reusable prefabs, procedural meshes, extrusion and lathe tools.
- GLB, glTF resource bundles and ZIP import, PBR materials, skeletons, morph targets, cameras, lights and animation clips.
- Local Blender conversion with sampled procedural-material baking and animated material/UV properties. See the [compatibility matrix](docs/BLENDER.md).
- Independent Rapier2D/Rapier3D physics in one scene: sprites, atlas slicing, frame animation, Tilemap painting, 2D colliders/joints, platformer/top-down controllers and a pixel-perfect camera. See the [2D guide](docs/2D.md).
- 3D rigid bodies, colliders and a character controller; orbit and first-person cameras.
- JavaScript behaviours with editable properties, worker execution and runtime diagnostics.
- A shared document and revision-checked transactions for both the editor and MCP.
- Portable `.forma` projects, standalone web builds and optional Linux, Windows and Android application builds.

Create objects from the hierarchy, edit their components in the inspector and use **Play / Stop** to test a separate runtime copy. **Save** creates a portable project. **Сборка игры** opens the build panel. Imported models and project scripts belong to your project, not to the engine source tree.

## MCP and AI

The local service provides Streamable HTTP at `http://127.0.0.1:4318/mcp` and a stdio adapter. Tools cover scenes, geometry, scripts, history, runtime input/capture and builds. The same project changes appear in the editor.

Start the server first, then configure a compatible MCP client. Authentication uses the project's `.mcp-token` file. See [MCP setup and workflow](docs/MCP.md). An AI model and a remote authentication gateway are not included. Cloud clients cannot reach your computer's loopback address directly.

Procedural generation works without Blender: an assistant can call mesh and modelling tools. This is geometry generation through code, not a bundled text-to-3D neural model. See [Blender and asset import](docs/BLENDER.md).

## Builds

Web export produces a ZIP containing the player, project and resources. Extract it and serve it with any static HTTP server:

```bash
python3 -m http.server 8080
```

Optional application targets are Linux x64 AppImage, Windows x64 portable EXE and Android APK. Desktop uses Electron; Android uses a WebView wrapper. These packages run the web runtime and do not compile project JavaScript ahead of time into machine code. Platform toolchains are installed separately. See [build instructions](docs/BUILDS.md).

## Development

```bash
npm ci
npm run build
npm run typecheck
npm test
```

GitHub Actions runs the same checks on Node.js 22 for pushes and pull requests. Build before running the integration tests; they exercise the generated editor and player bundles.

`npm run dev` builds and starts the local server. After editing the editor or runtime, rebuild and refresh the browser; project scripts do not need an engine rebuild. Generated browser bundles and local projects are excluded from Git.

[Architecture](docs/ARCHITECTURE.md) · [Command reference](docs/COMMANDS.json) · [Script API](docs/SCRIPT_API.json) · [Third-party dependencies](docs/THIRD_PARTY.md)

This is an early engine for prototyping and small projects. It does not yet provide animation graphs, retargeting, visual scripting, navigation/pathfinding, multiplayer, a dedicated audio system or terrain streaming. Device performance and platform compatibility need testing for each project. Scripts are trusted JavaScript; worker execution is not a security boundary for untrusted projects. No source-code license is designated yet; dependencies retain their own licenses.

## По-русски

**Forma** — браузерный 2D/3D-редактор, игровой runtime и локальный MCP-сервер. Репозиторий содержит движок, инструменты и небольшой пример 2D-платформера; пользовательские игры в него не включены. Интерфейс редактора — на русском.

Для запуска нужен Node.js **22.13+**:

```bash
git clone https://github.com/emil28092005/forma-engine.git
cd forma-engine
npm ci
npm run build
npm start
```

Открой **http://127.0.0.1:4318/**. Начальный проект пустой; изменения сохраняются в `projects/MyGame`. Для другой папки: `npm start -- --project ./projects/MyProject`.

Графика, физика и скрипты выполняются в браузере. Локальный сервер сохраняет файлы, принимает команды MCP и запускает сборщики. Можно создавать сцены вручную или поручать ИИ работу через MCP, импортировать GLB, создавать геометрию без Blender, сохранять `.forma` и собирать самостоятельные веб-проекты или приложения.

Это ранний прототип, а не замена всех возможностей зрелых движков. Подключение конкретного ИИ-клиента и проверка на целевых устройствах выполняются отдельно. Подробности: [MCP](docs/MCP.md), [сборки](docs/BUILDS.md), [импорт моделей](docs/BLENDER.md).

Для 2D: **Новый проект → 2D Платформер** или **Пустой 2D-проект**. [Нарезка спрайтов, Tilemap, физика и скрипты](docs/2D.md).