Checkpoint 1: implement native subsystems and begin the gameplay manual
This commit is contained in:
Emil
@@ -1,8 +1,8 @@
|
||||
# Faset Engine — архитектура
|
||||
|
||||
Редакция 1.1 · 18 сентября 2026 · **принятый проект, реализация ещё не начата**.
|
||||
Редакция 1.1 · 18 сентября 2026 · **принятый проект, реализация MVP в процессе**.
|
||||
|
||||
Этот файл фиксирует решения пользователя. **Принято** означает выбранное направление реализации, а не существующую или проверенную возможность движка. Код Faset Engine ещё не создан, тесты и измерения движка не проводились. Этапы до MVP и после него, зависимости работ и критерии готовности находятся в [PLAN.md](../PLAN.md).
|
||||
Этот файл фиксирует решения пользователя. **Принято** означает выбранное направление реализации, а не автоматически завершённую возможность движка. Работающий код, выполненные проверки и текущие ограничения перечислены в [журнале реализации](IMPLEMENTATION.md). Этапы до MVP и после него, зависимости работ и критерии готовности находятся в [PLAN.md](../PLAN.md).
|
||||
|
||||
Исследовательская база: [Unreal Engine, Godot, Unity и Blender](studies/README.md). Исторические сравнения не отменяют принятые здесь решения. Подробности: [ECS](studies/11-ecs-and-ergonomics.md), [MCP и Blender](studies/12-mcp-and-blender-integration.md), [стек и экспорт](studies/13-build-pipeline-and-stack.md), [renderer](studies/15-renderer-implementation-notes.md), [метаданные](studies/16-native-gameplay-and-metadata.md), [импорт](studies/17-asset-pipeline-and-blender-roundtrip.md), [build/cook](studies/18-build-cook-and-delivery.md).
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Зависимости, инструменты и независимость
|
||||
|
||||
Обновлено 18.09.2026. Здесь перечислены **выбранные направления интеграции**, а не уже подключённые библиотеки движка. Точные версии закрепляются на [M0](../PLAN.md); commits [исследовательского манифеста](studies/source-manifest.json) не заменяют dependency lock.
|
||||
Обновлено 18.09.2026. Исходные зависимости реализации закреплены в [dependencies.lock.json](../dependencies.lock.json): URL, commit, лицензия и SHA-256 архива. Степень готовности интеграций и проверки отражены в [журнале реализации](IMPLEMENTATION.md); commits [исследовательского манифеста](studies/source-manifest.json) не заменяют dependency lock.
|
||||
|
||||
## Runtime и инструменты Faset
|
||||
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
# Implementation checkpoints
|
||||
|
||||
This log records working implementation and observed validation. It does not replace
|
||||
the acceptance criteria in `PLAN.md`. Incomplete platform or workflow checks remain open.
|
||||
|
||||
## Checkpoint 1 — native foundation and independent subsystems
|
||||
|
||||
Implemented:
|
||||
|
||||
- C++20 CMake presets, pinned dependency archives with SHA-256 verification, and separate targets.
|
||||
- Core persistent IDs, SHA-256, atomic file replacement, JSON IO, and project path boundaries.
|
||||
- Explicit schema registration, document transactions, revisions, retry keys, Undo/Redo,
|
||||
recovery records, unknown extension preservation, migrations, and nested template resolution.
|
||||
- EnTT runtime with real Box2D/Box3D, fixed ticks, deferred changes, checked handles,
|
||||
interpolation, and statically linked example behaviors.
|
||||
- GLB/glTF asset import, cooked mesh data, stable source identity, cache generations,
|
||||
reimport conflicts, cancellation, and the optional Blender export add-on.
|
||||
- Direct Vulkan renderer, Slang shaders, sprites/meshes, basic PBR and directional
|
||||
shadows, texture upload, resize, capture, and SDL input.
|
||||
- English MkDocs/Material manual and an image prototype for the future retained editor UI.
|
||||
|
||||
Observed validation on Linux:
|
||||
|
||||
- Integrated headless CTest: authoring, runtime, asset pipeline, Blender bundle, core — 5/5 passed.
|
||||
- Integrated Clang 21.1.8/Ninja build with Vulkan: 7/7 tests passed, including offscreen GPU rendering.
|
||||
- Independent runtime and asset AddressSanitizer/UndefinedBehaviorSanitizer checks passed.
|
||||
- Renderer offscreen/visible tests exercised NVIDIA RTX 2080 Ti with Vulkan validation.
|
||||
- MkDocs strict build passed with MkDocs 1.6.1 and Material 9.7.7.
|
||||
|
||||
The full editor, user-project build pipeline, MCP integration, standalone exports,
|
||||
and Windows acceptance are still being implemented. This checkpoint is not the MVP release.
|
||||
|
||||
Known intermediate constraints include box-only physics colliders, root-level physics
|
||||
objects, static glTF triangles/UV0, a conservative serial renderer, and unfinished
|
||||
world-preserving authoring reparent operations. These remain implementation work or
|
||||
explicit profile limits to review during final acceptance.
|
||||
+3
-1
@@ -1,9 +1,11 @@
|
||||
# Документация Faset Engine
|
||||
|
||||
Актуализировано 18.09.2026 по принятым решениям. Репозиторий пока содержит проектирование и исследования, а не реализацию движка.
|
||||
Актуализировано 18.09.2026 по принятым решениям. Реализация MVP ведётся параллельно с проверками и пользовательским руководством.
|
||||
|
||||
## Канонические документы
|
||||
|
||||
- [Manual](manual/index.md) — пользовательское руководство на английском, с приоритетом C++ gameplay и работающих примеров.
|
||||
- [IMPLEMENTATION.md](IMPLEMENTATION.md) — результаты проверок и ограничения каждого checkpoint.
|
||||
- [PLAN.md](../PLAN.md) — порядок реализации, критерии приёмки MVP и развитие после него; здесь ведётся статус работ.
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) — принятый стек, контракты и владение данными.
|
||||
- [DEPENDENCIES.md](DEPENDENCIES.md) — независимость, выбранные зависимости и версии.
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# Keep the manual executable
|
||||
|
||||
Document user tasks and actual APIs in English. Explain what each argument means,
|
||||
which callback it belongs in, and what happens when an object or resource is missing.
|
||||
|
||||
Prioritize complete small gameplay examples over isolated declarations. Link examples
|
||||
to their source files and include them in build or integration checks. When an API
|
||||
changes, update its examples in the same change.
|
||||
|
||||
Mark planned capabilities explicitly. Do not describe a prototype image as a running
|
||||
editor, a Linux test as Windows validation, or a planned feature as implemented.
|
||||
|
||||
Build with strict documentation validation before publishing:
|
||||
|
||||
```sh
|
||||
.cache/docs-venv/bin/python -m mkdocs build --strict
|
||||
```
|
||||
|
||||
Generated output goes to `build/manual`; source Markdown and configuration are tracked
|
||||
in Git. Research and architecture documents remain separate from this user manual.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Build from source
|
||||
|
||||
!!! warning "Foundation checkpoint"
|
||||
These instructions initially cover the build foundation. The integrated editor,
|
||||
sample projects, and packaging steps are being added and verified during MVP implementation.
|
||||
|
||||
## Linux prerequisites
|
||||
|
||||
The selected toolchain is C++20, CMake 3.25 or later, Ninja, and Clang.
|
||||
Graphical builds need Vulkan 1.3 headers/loader and a compatible driver.
|
||||
SDL3 is built from a pinned source archive.
|
||||
|
||||
On Ubuntu, install the native build tools before configuring:
|
||||
|
||||
```sh
|
||||
sudo apt install clang ninja-build cmake python3 python3-venv pkg-config \
|
||||
libvulkan-dev vulkan-validationlayers libx11-dev libxext-dev libxrandr-dev \
|
||||
libxcursor-dev libxi-dev libxfixes-dev libxkbcommon-dev libwayland-dev \
|
||||
libfreetype-dev libharfbuzz-dev xvfb
|
||||
```
|
||||
|
||||
`xvfb` is used for automated window tests. A normal desktop session does not need it.
|
||||
|
||||
## Configure, build, test
|
||||
|
||||
```sh
|
||||
python3 tools/fetch_slang.py
|
||||
cmake --preset linux-debug
|
||||
cmake --build --preset linux-debug --parallel
|
||||
ctest --preset linux-debug
|
||||
```
|
||||
|
||||
For an optimized build use `linux-release`. The `linux-sanitize` preset enables
|
||||
AddressSanitizer and UndefinedBehaviorSanitizer for tests without the graphics backend.
|
||||
|
||||
## Dependencies and offline builds
|
||||
|
||||
Dependency source URLs, commits, and archive SHA-256 values are stored in
|
||||
`dependencies.lock.json`. CMake downloads them on the first configuration.
|
||||
To prefetch them for later offline use:
|
||||
|
||||
```sh
|
||||
python3 tools/fetch_dependencies.py
|
||||
python3 tools/fetch_dependencies.py --verify-only
|
||||
```
|
||||
|
||||
Cached archives live in `.cache/downloads` and are not committed. Local compilers,
|
||||
system development libraries, and the Slang compiler must also be available before
|
||||
disconnecting. Prefetching source archives alone is not a complete offline SDK.
|
||||
|
||||
## Windows prerequisites
|
||||
|
||||
Use an x64 Visual Studio Developer shell with the Windows SDK, MSVC runtime libraries,
|
||||
LLVM `clang-cl`, Ninja, CMake, and the Vulkan SDK available. Then use the
|
||||
`windows-debug` or `windows-release` presets.
|
||||
|
||||
```powershell
|
||||
py tools/fetch_slang.py
|
||||
cmake --preset windows-debug
|
||||
cmake --build --preset windows-debug --parallel
|
||||
ctest --preset windows-debug
|
||||
```
|
||||
|
||||
Windows acceptance is tracked separately from Linux; a successful Linux build does
|
||||
not verify a Windows build.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Faset Engine Manual
|
||||
|
||||
Faset is a C++ engine for desktop 2D and 3D games on Linux and Windows.
|
||||
This manual focuses on writing gameplay: small working examples, the functions they use,
|
||||
and how those functions interact with scenes, physics, and the editor.
|
||||
|
||||
!!! warning "Development status"
|
||||
MVP implementation is in progress. A planned feature is not a working feature.
|
||||
Individual guides state their prerequisites and validation status. The current
|
||||
foundation can be built and tested; a complete editor and game export are not yet available.
|
||||
|
||||
Start with [how C++ gameplay works](scripting/index.md), then read
|
||||
[frame and physics updates](scripting/lifecycle.md). See
|
||||
[Build from source](getting-started/build.md) for the toolchain and build commands.
|
||||
|
||||
The engine, editor, built-in diagnostics, and API identifiers use English.
|
||||
Your game content and project text can use other languages.
|
||||
|
||||
## Learning path
|
||||
|
||||
The manual grows alongside tested engine capabilities, in this order:
|
||||
|
||||
1. Build and run an example game.
|
||||
2. Create a C++ behavior and expose a property in the Inspector.
|
||||
3. Handle input and move a character.
|
||||
4. Use physics, collision events, and deferred object creation.
|
||||
5. Work with scene templates, assets, and references.
|
||||
6. Import from Blender and export a standalone game.
|
||||
|
||||
Lua is planned after the C++ foundation. It is not a current scripting option.
|
||||
|
||||
## Preview this manual
|
||||
|
||||
From the repository root, create a Python virtual environment and install the pinned documentation tools:
|
||||
|
||||
```sh
|
||||
python3 -m venv .cache/docs-venv
|
||||
.cache/docs-venv/bin/python -m pip install -r docs/requirements.txt
|
||||
.cache/docs-venv/bin/python -m mkdocs serve
|
||||
```
|
||||
|
||||
On Windows, use `py -m venv .cache/docs-venv` and
|
||||
`.cache/docs-venv/Scripts/python.exe` in place of the Unix interpreter path.
|
||||
The manual also remains readable directly as Markdown in the repository.
|
||||
@@ -0,0 +1,41 @@
|
||||
# C++ gameplay
|
||||
|
||||
In the first version of Faset, a "script" is C++ gameplay code compiled into your game.
|
||||
It is not an interpreted text file. The gameplay library is statically linked into
|
||||
a separate Player executable.
|
||||
|
||||
The intended iteration cycle is:
|
||||
|
||||
1. Stop Play.
|
||||
2. Edit your C++ behavior or system.
|
||||
3. Build the changed code and export its property schema.
|
||||
4. Start a new Player session.
|
||||
|
||||
The Editor reads a schema generated by a separate SchemaExporter. It does not load
|
||||
your gameplay library into its own process. A gameplay crash therefore does not
|
||||
automatically crash the Editor. Editor native extensions have a different lifecycle
|
||||
and run inside the Editor process.
|
||||
|
||||
!!! note "API examples are added with implementation"
|
||||
This page describes the accepted execution model. Exact function signatures and
|
||||
complete examples will be documented alongside compiling runtime examples, rather
|
||||
than presenting proposed APIs as available functions.
|
||||
|
||||
## Behaviors and systems
|
||||
|
||||
A behavior gives an individual object lifecycle callbacks. A system operates on a
|
||||
set of objects with matching components. Both use the same runtime state; the visual
|
||||
scene and Inspector are the authoring view of that state.
|
||||
|
||||
Persistent scene IDs and runtime handles are different. A scene ID survives saving
|
||||
and reopening. A runtime handle belongs to a particular world/session and can become
|
||||
invalid after an object is removed. Do not store raw component pointers across
|
||||
structural changes or treat a runtime handle as a save-file ID.
|
||||
|
||||
## Physics ownership
|
||||
|
||||
Physics owns the position of a dynamic rigid body. Move it with the supported physics
|
||||
commands instead of writing its presentation transform. A camera or other visual-only
|
||||
object can follow the interpolated result without modifying the simulation.
|
||||
|
||||
Continue with [Frame and physics updates](lifecycle.md).
|
||||
@@ -0,0 +1,47 @@
|
||||
# Frame and physics updates
|
||||
|
||||
!!! note "Execution contract"
|
||||
This page describes the accepted runtime contract. The runnable callback examples
|
||||
and test results are added as the runtime implementation becomes available.
|
||||
|
||||
## Choose the right callback
|
||||
|
||||
- `OnStart`: initialize a behavior once its object and components exist.
|
||||
- `FixedUpdate`: update simulation logic before a physics step.
|
||||
- `Update`: run frame-based gameplay once per rendered frame.
|
||||
- `LateUpdate`: update cameras and dependent visual objects after presentation interpolation.
|
||||
- `OnDestroy`: release subscriptions and other behavior-owned state before its handle is invalidated.
|
||||
|
||||
The default simulation interval is 1/60 second. A rendered frame may contain zero,
|
||||
one, or several fixed ticks. Frame rate and physics rate are not the same quantity.
|
||||
|
||||
## Fixed tick order
|
||||
|
||||
1. Apply structural commands queued by earlier work.
|
||||
2. Deliver tick input and call `FixedUpdate`.
|
||||
3. Apply physics commands and step the 2D and 3D worlds.
|
||||
4. Read back transforms and queue collision events.
|
||||
5. Run reactions after physics.
|
||||
|
||||
Object creation/removal and component addition/removal are deferred to the beginning
|
||||
of the next fixed tick. This prevents a callback from invalidating the collection
|
||||
currently being processed. New objects follow the same initialization rules as objects
|
||||
loaded from a scene.
|
||||
|
||||
After the fixed ticks, the frame runs `Update`, prepares interpolated presentation
|
||||
transforms, calls `LateUpdate`, and produces the render snapshot.
|
||||
|
||||
## Avoid frame-rate-dependent movement
|
||||
|
||||
A speed is a distance per second. Multiply it by the callback's elapsed seconds when
|
||||
calculating a displacement. Do not multiply a velocity by elapsed time before assigning
|
||||
it to a physics velocity API; the physics step performs that integration.
|
||||
|
||||
## Overload and pause
|
||||
|
||||
The initial catch-up limit is four fixed ticks per frame. Excess whole intervals are
|
||||
dropped with a diagnostic rather than making the physics step arbitrarily large.
|
||||
This is a local-game policy, not a guarantee of deterministic network simulation.
|
||||
|
||||
Pausing clears accumulated time. Single-step advances exactly one simulation tick.
|
||||
Interpolation history is reset for a new session, spawn, or teleport.
|
||||
@@ -0,0 +1,2 @@
|
||||
mkdocs==1.6.1
|
||||
mkdocs-material==9.7.7
|
||||
Reference in New Issue
Block a user