Forma Engine

A browser-based 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. Games and game assets are not included. The editor interface is currently in Russian.

Forma Engine editor with a primitive scene, hierarchy and component inspector

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.

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:

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 and self-contained glTF import, PBR materials, skeletons and animation clips.
Rapier 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. 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.

Builds

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

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.

Development

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 · Command reference · Script API · Third-party dependencies

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 — браузерный 3D-редактор, игровой runtime и локальный MCP-сервер. Этот репозиторий содержит только движок и инструменты: готовые игры и их ресурсы не включены. Интерфейс редактора — на русском.

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

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, сборки, импорт моделей.