101 lines
7.0 KiB
Markdown
101 lines
7.0 KiB
Markdown
# 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.
|
|
|
|
|
|
|
|
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).
|