Emil_Shanaty/Faset_Engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Archive P1 iteration workflow and manual checkpoint

Browse Source
This commit is contained in:
Emil
2026-09-24 03:45:18 +03:00
parent d7a7a7c3a4
commit 822b44f1d7
201 changed files with 100058 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/manual/editor/export.md
+20 -2
View File
@@ -9,8 +9,10 @@ Player process. **Stop** leaves the authoring document unchanged.
1. Edit `Scripts/Gameplay.cpp` and its explicit schema declarations.
2. Stop the running Player.
3. Choose **Build C++**. The compiler and SchemaExporter run outside the Editor.
4. Read compiler errors in the Console. A failed build retains the previous schema
3. Choose **Build**. CMake/Ninja build native gameplay and the separate
SchemaExporter refreshes the Inspector schema when inputs changed.
4. Read compiler errors in the Console. Select a project-source diagnostic to open
its line in your external editor. A failed build retains the previous schema
and binary; the schema status reports that it is stale.
5. After a successful build, edit the behavior's exposed fields in the Inspector.
6. Choose **Play**. It builds if necessary and launches the captured scene.
@@ -23,6 +25,22 @@ The Player supports pause and single-step. Editor controls use a private session
control file; they do not expose runtime entity queries through MCP. Closing the
Player is observed by the Editor, which keeps its logs and authoring state.
An unchanged second build still asks CMake/Ninja to verify their dependency graph.
When the native outputs, gameplay sources, toolchain, shaders and runtime inputs
match the validated package, **Jobs** reports `schema_cache_hit` and
`generation_reused` as true and returns the same immutable generation without a
second SchemaExporter run or package copy. A changed `.cpp`, header, Lua declaration,
build recipe or relevant tool invalidates that reuse. A damaged cached package is
not treated as a hit. The job also exposes elapsed phases and a build fingerprint;
see [Developer diagnostics](diagnostics.md) for structured errors and raw logs.
If a build fails, correct the listed source and build again. The prior playable
generation remains available, but stale Inspector metadata is not evidence that
the failed edit built successfully. Save the scene separately: named dirty scenes
autosave after two idle seconds by default, while an unnamed scene needs **Save As**.
External file changes produce a visible conflict instead of an overwrite; the
[workspace guide](workspace.md#create-and-save-a-scene) explains recovery.
## Export a standalone game
Use **Export** in the Editor for the current scene. Resolve template conflicts and
docs/manual/editor/profiling.md
+40 -11
View File
@@ -39,29 +39,58 @@ Use `--debug-physics` or press **F3** to show current physics box colliders. Deb
geometry increases draw count, so record whether it was enabled. The collider view
uses simulation poses; normal visuals can use interpolated poses.
## Measure Editor and C++ workflows
## Measure Editor, C++ and Lua iteration
From the engine repository:
```sh
cmake --build --preset linux-debug --target faset_editor faset_editor_ui_latency --parallel 2
python3 tools/measure_workflows.py \
--editor build/linux-debug/faset_editor \
--project examples/projects/collect-3d \
--output .cache/my-workflow-measurement
--output /tmp/faset-workflow-measurement
```
Use a new output directory. The tool copies the project, preserving your original,
and records command startup, two-frame GUI startup/shutdown, first/cached Blender
bundle import, initial/no-change/changed Debug builds and a subsequent Player frame.
It checks that editing gameplay makes the schema stale and successful building
clears that state. The initial build uses available dependency archives and OS
caches; it is not a measurement of internet download speed.
The UI probe must be built beside the Editor first. The default Lua input is
`examples/lua`; use `--lua-project` to select another declared Lua project and
`--ui-latency-binary` when the probe is elsewhere. Use a **new** output directory;
the tool refuses to overwrite evidence. It copies both projects and never edits
the checked-in examples.
`report.json` version 2 separates the initial cold project configure/build,
unchanged builds, changed `.cpp` builds, changed-header builds, deliberate compile
failure/recovery, Lua edit-to-reload, first offscreen Player frame and synthetic
Editor input-to-visible-state. Each warm/changed case has one warm-up and five
measured repetitions. Each sample remains in `raw/` with command, stdout/stderr,
duration and, on Linux, peak RSS; the report includes median and nearest-rank p95.
The file hashes identify every changed source variant. Five unchanged builds must
return a verified schema/package cache hit. The cold case begins with empty project
`.faset` caches, **not** a cold OS file cache, newly downloaded dependencies or a
fresh engine toolchain. It is a development `Debug` workflow.
The first-frame value comes from the Player's `main_to_first_frame` profile after
five one-frame offscreen runs. It excludes OS process loading and says nothing about
window presentation latency. The separate UI probe applies keyboard input through
the retained Editor UI, then measures 100 post-warm-up offscreen frames; it is not
native desktop input-to-photon latency. A watched Lua Player records five
edit-to-successful-reload times, including its polling and log notification. A
3,000-frame Player profile compares explicit Vulkan allocation and texture maxima
in frames 101–200 with frames 2901–3000. Zero growth over that interval is useful
but does not prove the absence of all leaks. The tool also adds 512 deterministic
objects to a disposable scene and profiles 240 frames; this stresses scene
simulation/snapshot work, not representative game content.
On Linux, GNU `time` records peak RSS for each command and its waited-for children.
This is a maximum, not the sum of simultaneous compiler processes. Other platforms
report this field as null unless equivalent measurement support is added. The tool
keeps raw stdout/stderr, durations, hardware and revision information alongside its
report. A dirty source checkout is explicitly identified.
report this field as null unless equivalent measurement support is added. The report
keeps raw stdout/stderr, profiles, hardware, driver, build setting, source hashes,
Git revision and dirty-tree state. New runs also hash the exact CMake, Ninja, C/C++
compiler, Slang, Editor and UI-probe binaries selected by the disposable project's
`CMakeCache.txt`. Compare profiles only with the same scene, configuration,
resolution, validation/readback settings and hardware class. The
[dated P1 workflow record](https://github.com/emil28092005/Faset_Engine/blob/main/docs/validation/p1-iteration-2026-09-24/README.md)
retains a successful Debug run and its exact raw files. Its post-run binary
provenance supplement is explicitly separate from the original report.
`tools/verify_playable_exports.py` separately verifies the two sample games in
relocated Release packages and records their Player profiles. Its assertions test
docs/manual/editor/workspace.md
+8 -1
View File
@@ -14,7 +14,8 @@ process; stopping it leaves the authoring scene unchanged.
Launch `faset_editor` without arguments to open the project launcher.
1. Choose **Create project**, enter a name and a new or empty project directory,
then select **2D** or **3D** for the initial scene.
then select **C++** or **Lua** and **2D** or **3D**. Each combination creates a
runnable start scene and a small behavior for that language.
2. Choose **Create project** to create the project files and open the Editor.
3. To return later, choose **Open project**, select its directory with **Browse**,
and confirm **Open project**. The directory must contain `project.faset.json`.
@@ -33,6 +34,12 @@ was launched in MCP mode so the connection keeps a single project context.
For a direct launch, use `faset_editor --project /path/to/MyGame` on Linux or
`faset_editor.exe --project C:\Projects\MyGame` on Windows.
For scripted project creation, pass `--new MyGame --dimension 2|3
--language cpp|lua` with `--project` pointing to the new directory. Omitting
`--language` retains the earlier C++ scaffold without a runnable start scene;
select a language explicitly for a complete starter.
The [C++ first behavior](../scripting/first-behavior.md) and
[Lua gameplay](../scripting/lua.md) guides show the first editing steps.
## Create and save a scene
docs/manual/scripting/first-behavior.md
+14 -2
View File
@@ -56,14 +56,26 @@ The example scene is a complete, loadable document:
The sprite is visible because it has `faset.sprite`. It moves because it also has `tutorial.move_x`. The configuration field is `speed`; the type string must match the registration exactly. `rotation` uses radians, and the default coordinate system is Y-up.
After **Build C++** succeeds in the Editor, choose **Add component** in the Inspector
After **Build** succeeds in the Editor, choose **Add component** in the Inspector
and select the registered type. Its schema supplies editable fields, defaults and
constraints. The direct Player command above is useful for testing the same behavior
independently of an editor session.
## Make a change and verify it
Change the scene's `speed` to `-2`: the object moves left. Change the C++ callback or schema: stop the Player, rebuild, regenerate the schema, then launch a new session. There is no automatic C++ hot reload.
Change the scene's `speed` to `-2`: the object moves left. Change the C++ callback
or schema: stop the Player, choose **Build**, then launch a new Play session. The
Build job regenerates metadata when its inputs changed; an unchanged second build
can reuse the verified schema/package generation. It still asks CMake/Ninja to check
the native dependency graph. There is no automatic C++ hot reload.
To try compiler navigation in a project opened by the Editor, add
`#error Check navigation` to its `Scripts/Gameplay.cpp`, choose **Build**, and
select the resulting Console diagnostic. **Open source** passes the file and
one-based location to the configured external editor. Remove the line and build
again; the failed attempt keeps the previous valid generation. See
[Developer diagnostics](../editor/diagnostics.md) for editor command setup and
[Build, Play, and export](../editor/export.md) for the full iteration loop.
The `tutorial_moving` CTest checks that both 30 Hz and 60 Hz frame sequences move the object two metres in one second. It checks the resulting pose, rather than only checking that the program starts.
docs/manual/scripting/lua.md
+22 -6
View File
@@ -210,14 +210,18 @@ The Editor command palette exposes:
| `faset_lua_refresh` | Build if needed, extract schemas, refresh Inspector metadata |
| `faset_lua_reload` | Request a Lua reload in a development Player |
| `faset_lua_setup` | Install Faset LuaLS declarations/configuration |
| `faset_script_open` | Open a script in an external editor |
| `faset_source_open` | Open a C++, header or Lua source at a one-based line/column |
| `faset_script_open` | Lua-only compatibility alias for source opening |
The external-editor default is `zed`. Set `editor.script_editor` in
`project.faset.json` to an argument array such as `["code", "--goto", "{file}"]`,
or pass an `editor` argument array to `faset_script_open`. Exact `{file}` and
`{project}` arguments are substituted; a missing file argument is appended. The
command launches the executable directly, without a shell. The Assets panel lists
Lua sources under `Scripts` and provides **Open Script**.
`project.faset.json` to an argument array such as
`["zed", "{file}:{line}:{column}"]`, or pass an `editor` argument array to
`faset_source_open`. `{file}`, `{line}`, `{column}` and `{project}` are substituted
inside arguments; a missing file argument is appended. The command launches the
executable directly, without a shell. Only regular source files under this
project's `Scripts` can be opened. The Assets panel lists those files and the
Console's structured Lua error can open its source location. A missing external
editor is an actionable navigation error, not a failed gameplay build.
Development Play watches Lua changes. The Player's `--watch-lua` option enables this
for direct development runs. A candidate source generation is loaded and validated
@@ -226,6 +230,18 @@ Successful reload **restarts the scene**, invalidates old handles, and resets al
script state. This is not state-preserving hot swapping. C++ source changes still
require a rebuild and a new Player process.
For a short iteration, change `speed` in `Scripts/main.lua`, save it, and watch the
Console for **Lua reloaded**. The running development Player picks up a valid
snapshot without native recompilation. Change a field declaration or TypeId, then
choose **Refresh Lua** to validate metadata and update Inspector choices. If the
candidate has a syntax/schema error, the previous running generation remains in
place; use the structured diagnostic to return to the source, correct it and retry.
Lua module declaration, gameplay source, compiler/toolchain or shader changes can
invalidate a later build's verified schema/package cache. The **Jobs** result
distinguishes `schema_cache_hit` and `generation_reused`; those flags do not imply
that the native build graph was skipped. See the [build loop](../editor/export.md)
and [profiling guide](../editor/profiling.md).
Export captures the declared entry list and Lua modules with the game. The exported
Player runs without the Editor or a separate Lua installation; development watching
is not enabled by ordinary exported-game launch. Exported Lua remains readable source,