lecodes-cli 2.3.1 → 2.4.0

package/src/commands/app/shared.ts

@@ -100,14 +100,21 @@ export interface AppConfig {
     /** 3D buffer cap in px, e.g. [1920, 1080]: on a bigger window/monitor the 3D renders at most
      *  this size (aspect kept) — the per-machine answer to "fullscreen on a 4K display is slow". */
     maxRenderSize?: [number, number],
-    /** Frame-rate CAP for the host's render loop: `"display"` (default — follow the screen's refresh
-     *  rate, 120 on a ProMotion Mac) or a number, meaning "at most this many fps" (the screen's
-     *  maximum still wins when it is lower — vsync is the real ceiling, so this can never be a
-     *  target above it). For an app that wants to spend less: a UI-heavy app on a laptop, a game
-     *  whose feel is tuned for 60. `desktop run` forwards it as CREATOR_FRAME_RATE (a set env wins);
-     *  a built .app's host reads it from the staged app.json. Honoured by the macOS host
-     *  (2026-09-09); the Windows/Linux host is vsync-locked and ignores it for now. */
+    /** Frame-rate CAP the host starts with: a number = "at most this many fps", `0` or `"display"`
+     *  (the default) = no cap — the display's own rate, or, with vsync off, as fast as the host
+     *  renders. The app changes it at runtime with `device.setFrameRate()`; this is the value in
+     *  force before the bundle runs. For an app that wants to spend less: a UI-heavy app on a
+     *  laptop, a game whose feel is tuned for 60. `desktop run` / `dev --desktop` forward it as
+     *  CREATOR_FRAME_RATE (a set env wins); a built folder's host reads it from the staged app.json.
+     *  Headless render/test ignore it (their frames are app-time steps). */
     frameRate?: number | "display",
+    /** Vertical sync the host starts with (default true). `false` presents without waiting for the
+     *  display's refresh: the lowest input latency, tearing possible — and with no `frameRate` cap
+     *  the loop renders as fast as it can, so set one unless you are measuring. The app switches it
+     *  at runtime with `device.setVsync()`. Forwarded as CREATOR_VSYNC (a set env wins), read from
+     *  the staged app.json by a built folder's host. Windows (GL: the swap interval; Vulkan: the
+     *  immediate present mode); the macOS and Linux hosts ignore it for now. */
+    vsync?: boolean,
     /** The mouse button acts as a finger: a left click-drag scrolls + flings like touch (the wheel
      *  always scrolls, clicks are unaffected; a button inside a scrollable then gets the touch-style
      *  press feedback delay). For testing the touch experience without a touchscreen, or an app

package/src/commands/desktop.ts

@@ -93,8 +93,9 @@ const run = defineCommand({
       // from app.json only. Both are desktop-level (the machine/app), not window-level.
       renderScale: resolveRenderScale(flags["render-scale"], appCfg?.desktop?.renderScale),
       maxRenderSize: appCfg?.desktop?.maxRenderSize,
-      // Frame-rate cap (app.json only — like renderScale it is a property of the app, not of a run).
+      // Frame-rate cap + vsync (app.json only — like renderScale they are properties of the app, not of a run).
       frameRate: appCfg?.desktop?.frameRate,
+      vsync: appCfg?.desktop?.vsync,
       mouseEmulateTouch: appCfg?.desktop?.mouseEmulateTouch,
       virtualKeyboard: appCfg?.desktop?.virtualKeyboard,
       // --fps: the host's own corner counter. A flag and not app.json on purpose — it is something you

package/src/commands/dev.ts

@@ -300,6 +300,7 @@ export default defineCommand({
         scale: resolveScale(undefined, win?.scale),
         // The frame-rate cap is forwarded too: it changes how the game FEELS, and dev should match production.
         frameRate: appCfg?.desktop?.frameRate,
+        vsync: appCfg?.desktop?.vsync,
         fps: flags.fps,
       }).then(
         () => note("Desktop window closed — the dev server keeps running (Ctrl+C to stop)."),

package/src/hosts/desktopRenderer.ts

@@ -348,9 +348,13 @@ export type DesktopWindowOpts = {
    *  Filament's timer query, the CPU split, visible / total renderables, the view's switches — and the
    *  fps overlay's second row. docs/profiling.md in the core repo. */
   perf?: boolean
-  /** app.json desktop.frameRate — a CAP on the host's render loop, "display" or a number; forwarded
-   *  verbatim as CREATOR_FRAME_RATE (a set env wins). macOS host 2026-09-09; Windows ignores it. */
+  /** app.json desktop.frameRate — the CAP the host's loop starts with, "display" / 0 (none) or a
+   *  number; forwarded verbatim as CREATOR_FRAME_RATE (a set env wins). The app moves it with
+   *  device.setFrameRate(). */
   frameRate?: number | "display"
+  /** app.json desktop.vsync — whether the host starts with vertical sync (default true); forwarded
+   *  as CREATOR_VSYNC=1/0 (a set env wins). The app moves it with device.setVsync(). */
+  vsync?: boolean
   /** Multiplayer launch facts for the host (`--server --port N --max-clients N` / `--connect ip:port`);
    *  the SDK reads them through `Net.launch` and decides (docs/multiplayer-plan.md). */
   net?: { role: "server" | "client"; address?: string; port?: number; maxClients?: number }
@@ -388,6 +392,9 @@ const windowEnv = (opts: DesktopWindowOpts): Record<string, string> => {
   if (opts.frameRate !== undefined && process.env.CREATOR_FRAME_RATE === undefined) {
     env.CREATOR_FRAME_RATE = String(opts.frameRate)
   }
+  if (opts.vsync !== undefined && process.env.CREATOR_VSYNC === undefined) {
+    env.CREATOR_VSYNC = opts.vsync ? "1" : "0"
+  }
   if (opts.mouseEmulateTouch !== undefined && process.env.CREATOR_MOUSE_TOUCH === undefined) {
     env.CREATOR_MOUSE_TOUCH = opts.mouseEmulateTouch ? "1" : "0"
   }