@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/modules/html-ui/src/protocol.ts

@@ -12,8 +12,18 @@ export type DocMutation =
   | { op: "rattr"; node?: number; sel?: string; name: string }
   | { op: "style"; node?: number; sel?: string; prop: string; value: string }
   | { op: "innerHtml"; node?: number; sel?: string; html: string }
+  /** Append parsed HTML as the node's last children — `innerHTML +=`
+   *  semantics; existing children survive. Requires a cdylib with
+   *  dd_osr_append_html — check the `ready` message's caps first. */
+  | { op: "appendHtml"; node?: number; sel?: string; html: string }
+  /** Drop all but the last `keep` children — bounds streaming lists
+   *  (console logs) without an innerHTML rebuild. Same caps caveat. */
+  | { op: "trimChildren"; node?: number; sel?: string; keep: number }
   | { op: "focus"; node?: number; sel?: string }
   | { op: "scrollIntoView"; node?: number; sel?: string; smooth?: boolean; vertical?: "start" | "center" | "end" | "nearest"; horizontal?: "start" | "center" | "end" | "nearest" }
+  /** Absolute scroll offsets on a scroll container — reaches nested
+   *  scrollports (scrollIntoView only moves the root viewport). */
+  | { op: "scrollTo"; node?: number; sel?: string; x: number; y: number; smooth?: boolean }
   /** Synthetic click at the node's rect center — drives the real
    *  pointer/click event pipeline (data-action handlers included). */
   | { op: "click"; node?: number; sel?: string };
@@ -62,21 +72,58 @@ export type UiToWorker =
    *  enclosing data-nav-zone id, disabled and editable state. */
   | { type: "navSnapshot"; reqId: number; id: string; sel: string }
   /** Host detected a torn SAB frame read — re-emit the current pixels. */
-  | { type: "refresh"; id: string };
+  | { type: "refresh"; id: string }
+  /** Attach the engine ProfilingSAB — the worker claims a metrics slot so the
+   *  devtools perf tab can see it. Best-effort; ignored when profiling is off. */
+  | { type: "profilingAttach"; sab: SharedArrayBuffer; workerTag: string; layout?: { maxSlots: number; iopsRingCap: number; warningRingCap: number; stringTableCap: number } }
+  /**
+   * Attach to the host's shared wgpu device (native only). `gpu` is the
+   * GpuDeviceHandle from the host's GpuShareBroker — declared structurally
+   * here because platform-native is an optional peer. Once attached, the
+   * worker uploads panel frames straight into bound textures via
+   * queue.writeTexture instead of emitting pixels/SAB headers.
+   */
+  | { type: "gpuAttach"; gpu: { devicePtr: number | bigint; instancePtr: number | bigint; queuePtr: number | bigint; generation: number }; cells: SharedArrayBuffer }
+  /** Detach the shared-device view — sent before the host terminates the
+   *  worker so the broker's retire() doesn't stall on a stuck attach count. */
+  | { type: "gpuDetach" }
+  /**
+   * Bind a doc's upload target. The host owns the texture (created on the
+   * main thread); the worker wraps `texPtr` non-owningly (borrowGpuTexture)
+   * and queue.writeTextures dirty rects into it. Sent at mount, again after
+   * every resize (rebind), and never on the SAB fallback path.
+   */
+  | { type: "texBind"; id: string; texPtr: number | bigint; w: number; h: number; format: string };
 
 /** Backend → host */
 export type WorkerToUi =
-  | { type: "ready" }
+  | { type: "ready"; caps?: { incrementalDom?: boolean } }
   /**
-   * A frame is ready. Two shapes:
+   * A frame is ready. Three shapes:
    *  - pixel-carrying (`pixels` present): `w*h*4` tightly-packed RGBA bytes to
    *    upload at (x, y). Used when no SharedArrayBuffer channel is bound.
    *  - SAB (`seq` present): the backend wrote the dirty rect into the bound
    *    buffer at `stride`-aligned rows — the host reads pixels itself.
+   *  - GPU-direct (`gpu: true`): the worker already queue.writeTextured the
+   *    dirty rect into the bound panel texture — stats/bookkeeping only.
+   */
+  | { type: "frame"; id: string; x: number; y: number; w: number; h: number; pw: number; ph: number; pixels?: ArrayBuffer; seq?: number; stride?: number; gpu?: boolean; texPtr?: number | bigint }
+  /** Bind/rebind the per-doc SAB frame staging buffer. Always emitted on
+   *  (re)bind so the host's copy stays current — `gpuFallback: true` marks
+   *  the "worker dropped GPU-direct" emits where the host must also resume
+   *  its own uploads; plain binds are informational (GPU mode unaffected). */
+  | { type: "bind"; id: string; buf: SharedArrayBuffer; gpuFallback?: boolean }
+  /** Result of a gpuAttach attempt — ok:false keeps the SAB path. */
+  | { type: "gpuReady"; ok: boolean }
+  /** Ack of gpuDetach — the host may now terminate the worker. */
+  | { type: "gpuDetached" }
+  /**
+   * The worker dropped its borrowed wrapper for `texPtr` — sent when a
+   * texBind replaces the previous target or a doc is destroyed. The host
+   * defers destroying a bound texture until this ack (or a fallback timer)
+   * so a writeTexture can't be in flight on the freed handle.
    */
-  | { type: "frame"; id: string; x: number; y: number; w: number; h: number; pw: number; ph: number; pixels?: ArrayBuffer; seq?: number; stride?: number }
-  /** Bind/rebind the per-doc SAB frame staging buffer (sent before first frame). */
-  | { type: "bind"; id: string; buf: SharedArrayBuffer }
+  | { type: "texAck"; id: string; texPtr: number | bigint }
   | { type: "events"; id: string; events: OsrDomEvent[] }
   | { type: "attr"; reqId: number; value: string | null }
   | { type: "rect"; reqId: number; rect: { x: number; y: number; w: number; h: number } | null }

package/modules/mcp/README.md

@@ -15,4 +15,10 @@ bun add @downdraft/engine/modules/mcp
 - `McpServerTok`
 - `createMcpModule`
 
+`createMcpModule({ transport: "http" })` serves the editor toolset over HTTP on
+127.0.0.1 (`McpHttpTransport` direct mode), advertised via
+`~/.downdraft/port/<pid>.editor` — reach it with `draft mcp --editor` or
+`GameClient.connect({ endpoint: "editor" })`. The default `"stdio"` transport
+speaks newline-delimited JSON-RPC on the process's own stdin/stdout.
+
 See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/modules/mcp/src/index.ts

@@ -1,10 +1,37 @@
 import { resourceToken, type Module, type ModuleContext } from "@downdraft/engine";
 import { EngineContext, MCPServer, type EngineContextFromGameOptions } from "@downdraft/engine/mcp";
+import type { McpHttpTransport } from "@downdraft/engine/mcp/http-transport";
+import { createLogger } from "@downdraft/engine/util/logger";
+
+const log = createLogger("info");
 
 /** Token for the MCP server instance provided by the mcp plugin. */
 export const McpServerTok = resourceToken<MCPServer>("mcp:server");
 
-export function createMcpModule(opts: EngineContextFromGameOptions): Module {
+export interface McpModuleOptions extends EngineContextFromGameOptions {
+  /**
+   * Transport for the MCP JSON-RPC surface:
+   *  - "stdio" (default): newline-delimited JSON-RPC on the process's own
+   *    stdin/stdout — classic spawn-as-an-MCP-process mode.
+   *  - "http": `McpHttpTransport` direct mode on 127.0.0.1 — a second loopback
+   *    endpoint alongside the game's automation endpoint, advertised via
+   *    `~/.downdraft/port/<pid>.editor` and reached with `draft mcp --editor`
+   *    or `GameClient.connect({ endpoint: "editor" })`.
+   */
+  transport?: "stdio" | "http";
+  /** HTTP port for transport:"http" (0 = ephemeral, the default).
+   *  MCP_EDITOR_PORT env overrides when `port` is unset. */
+  port?: number;
+  /** Require the bearer token on HTTP requests (default: MCP_AUTH=1 env). */
+  requireAuth?: boolean;
+  /** Root dir for GET /mcp/artifact/<path> downloads (transport:"http"). */
+  artifactDir?: string;
+  /** Write `~/.downdraft/port/<pid>.editor` (+ `.editor.token`) so PID-file
+   *  discovery finds this endpoint. Default true in http mode. */
+  advertise?: boolean;
+}
+
+export function createMcpModule(opts: McpModuleOptions): Module {
   let server: MCPServer | null = null;
 
   return {
@@ -15,9 +42,49 @@ export function createMcpModule(opts: EngineContextFromGameOptions): Module {
     register(ctx: ModuleContext) {
       const engineContext = EngineContext.fromGame(opts);
       server = new MCPServer({ engineContext });
-      server.start();
       ctx.provide(McpServerTok, server);
-      ctx.onDispose(() => server?.stop());
+
+      if (opts.transport !== "http") {
+        server.start();
+        ctx.onDispose(() => server?.stop());
+        return;
+      }
+
+      // HTTP transport — node:http and the PID-file dir are Node APIs, so
+      // they're dynamic-imported (keeps this module loadable in non-node
+      // contexts; same convention as createNodeFs in the editor module).
+      let disposed = false;
+      let transport: McpHttpTransport | null = null;
+      let removePidFile: (() => void) | null = null;
+      void (async () => {
+        const [{ McpHttpTransport }, { writeMcpPidFile }] = await Promise.all([
+          import("@downdraft/engine/mcp/http-transport"),
+          import("@downdraft/engine/app/shared/mcp-discovery"),
+        ]);
+        if (disposed || !server) return;
+        transport = new McpHttpTransport({
+          mcpServer: server,
+          port: opts.port ?? (Number(process.env.MCP_EDITOR_PORT) || 0),
+          requireAuth: opts.requireAuth,
+          artifactDir: opts.artifactDir,
+        });
+        await transport.start();
+        if (disposed) {
+          await transport.stop();
+          return;
+        }
+        if (opts.advertise !== false) {
+          removePidFile = writeMcpPidFile(transport.getPort(), transport.getAuthToken(), ".editor");
+        }
+        log.info("mcp", `Editor MCP server listening on 127.0.0.1:${transport.getPort()}`);
+      })().catch((e) => {
+        log.warn("mcp", `Editor MCP HTTP endpoint failed to start: ${(e as Error).message}`);
+      });
+      ctx.onDispose(() => {
+        disposed = true;
+        removePidFile?.();
+        void transport?.stop();
+      });
     },
   };
 }

package/modules/movement-3d/src/character-motor.ts

@@ -57,6 +57,20 @@ export interface CharacterMotor3DConfig {
     maxVertSpeed: number;
     /** Stop floating up this far below the water surface. Default: 0.3. */
     surfaceOffset?: number;
+    /** Launch speed for vaulting out of the liquid over the rim: while holding
+     *  jump in the shallow band near the surface and pressing a move key with
+     *  env.swimNearEdge set, the swimmer pops out instead of clamping at the
+     *  surface. Scaled per-tick by env.swimVaultMul (0 = this liquid can't be
+     *  climbed out of). Default 0 = vaulting disabled. */
+    vaultForce?: number;
+    /** How far below waterHeight the feet can be for a vault to trigger.
+     *  Must exceed the game's wet-probe depth or the env's inWater flag drops
+     *  before the vault window opens. Default: 0.55. */
+    vaultDepth?: number;
+    /** Min seconds between vaults — stops held keys from re-launching the
+     *  moment the swimmer falls back in (the "bouncing off the surface"
+     *  effect). Default: 0.5. */
+    vaultCooldown?: number;
   };
 }
 
@@ -84,6 +98,9 @@ export interface Motor3DState {
   grounded: boolean;
   /** Model yaw — eased toward the movement direction. */
   facing: number;
+  /** Internal: remaining seconds before another vault can launch. Managed by
+   *  the motor; callers should leave it alone. */
+  vaultCooldown?: number;
 }
 
 export interface Motor3DEnv {
@@ -96,6 +113,24 @@ export interface Motor3DEnv {
   /** Gate for ground-jump launches (e.g. disabled while piloting).
    *  Default: true. Does not affect swim-float. */
   jumpAllowed?: boolean;
+  /** Per-tick liquid modifiers — scale the swim config for thick/hazardous
+   *  liquids. All default to 1; a ~0 swimForceMul is a liquid the character
+   *  effectively can't swim in (quicksand). */
+  swimForceMul?: number;
+  /** Scales swim.sinkRate — quicksand-like liquids pull down fast. Default: 1. */
+  swimSinkMul?: number;
+  /** Scales swim.maxVertSpeed. Default: 1. */
+  swimVertMul?: number;
+  /** Scales swim.vaultForce; 0 = can't vault out of this liquid. Default: 1. */
+  swimVaultMul?: number;
+  /** Game-computed: close enough to the liquid body's edge to climb over the
+   *  rim. Suppresses mid-pool vaults. Default: true. */
+  swimNearEdge?: boolean;
+  /** Game-computed: unit XZ direction toward the nearest climbable edge. When
+   *  set, a vault only fires if the player's move input points at the edge
+   *  (dot > 0.35) — pressing away from the rim just bobs. When unset, any
+   *  horizontal input satisfies the check. */
+  swimEdgeDir?: [number, number];
 }
 
 export interface Motor3DDelta {
@@ -180,17 +215,55 @@ export function createCharacterMotor3D(cfg: CharacterMotor3DConfig): CharacterMo
     let dy = 0;
     if (inWater) {
       const swim = cfg.swim!;
-      if (isFloating) state.vy += swim.floatForce * dt;
-      else if (isDiving) state.vy -= swim.diveForce * dt;
-      else state.vy -= swim.sinkRate * dt;
-      state.vy *= swim.drag;
-      state.vy = Math.max(-swim.maxVertSpeed, Math.min(swim.maxVertSpeed, state.vy));
+      const forceMul = env.swimForceMul ?? 1;
+      const maxVert = swim.maxVertSpeed * (env.swimVertMul ?? 1);
+      state.vaultCooldown = Math.max(0, (state.vaultCooldown ?? 0) - dt);
+      if (Math.abs(state.vy) > maxVert) {
+        // Overspeed — a vault launch or a plunge from height. Decay
+        // ballistically back toward swim speeds; liquid forces re-engage once
+        // inside the cap, so a vault keeps its arc while still submerged
+        // instead of being crushed by drag on the next tick.
+        state.vy -= Math.sign(state.vy) * Math.min(Math.abs(state.vy) - maxVert, gravity * dt);
+      } else {
+        if (isFloating) state.vy += swim.floatForce * forceMul * dt;
+        else if (isDiving) state.vy -= swim.diveForce * forceMul * dt;
+        else state.vy -= swim.sinkRate * (env.swimSinkMul ?? 1) * dt;
+        state.vy *= swim.drag;
+        state.vy = Math.max(-maxVert, Math.min(maxVert, state.vy));
+      }
       dy = state.vy * dt;
-      // Stop at the water surface when floating up (don't launch out).
-      if (isFloating && env.waterHeight !== undefined && env.posY !== undefined
-          && env.posY + dy > env.waterHeight - surfaceOffset) {
-        dy = env.waterHeight - surfaceOffset - env.posY;
-        state.vy = 0;
+      if (env.waterHeight !== undefined && env.posY !== undefined) {
+        const vault = (swim.vaultForce ?? 0) * (env.swimVaultMul ?? 1);
+        const edgeDir = env.swimEdgeDir;
+        let towardEdge = input.fwd !== 0 || input.strafe !== 0;
+        if (edgeDir && towardEdge) {
+          const b = headingBasis(yaw);
+          const mvx = input.fwd * b.fwd[0] + input.strafe * b.right[0];
+          const mvz = input.fwd * b.fwd[1] + input.strafe * b.right[1];
+          towardEdge = mvx * edgeDir[0] + mvz * edgeDir[1] > 0.35;
+        }
+        // Vault out over the rim: holding jump in the shallow band while
+        // pressing toward the edge launches past the surface instead of
+        // clamping. vy>=0 + the cooldown stop a descending swimmer from
+        // re-triggering it; the env's inWater flag drops as the feet clear
+        // the surface, handing the launch to the ballistic branch.
+        if (isFloating && vault > 0 && (env.swimNearEdge ?? true) && towardEdge
+            && state.vy >= 0 && (state.vaultCooldown ?? 0) <= 0
+            && env.posY > env.waterHeight - (swim.vaultDepth ?? 0.55)) {
+          state.vy = vault;
+          state.vaultCooldown = swim.vaultCooldown ?? 0.5;
+          state.grounded = false;
+          dy = state.vy * dt;
+        } else if (isFloating) {
+          // Ease to a stop at the surface line — an asymptotic approach
+          // instead of overshooting into the dry branch every other tick
+          // (the old hard clamp made the swimmer bob visibly at the line).
+          const cap = Math.max(0, env.waterHeight - surfaceOffset - env.posY) * 6;
+          if (state.vy > cap) {
+            state.vy = cap;
+            dy = state.vy * dt;
+          }
+        }
       }
     } else {
       if (cfg.resetVyWhenGrounded && state.grounded) state.vy = 0;