Archive P1 iteration workflow and manual checkpoint

2026-09-24 03:45:18 +03:00
parent d7a7a7c3a4
commit 822b44f1d7
201 changed files with 100058 additions and 29 deletions
@@ -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.

@@ -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,