feat: expand native math kernels and interop docs

Author: S1mplector

README.md

@@ -20,6 +20,13 @@ Prereqs: JDK 17+, Gradle (wrapper included).
 ./gradlew :editor:run
 ```
 
+## Docs
+
+- VNS: `docs/VNS Scripting/VNS Scripting.md`
+- JES: `docs/JES Scripting/JES Scripting.md`
+- Interop: `docs/Interop.md`
+- Performance: `docs/Performance.md`
+
 ## Modules
 
 - `core`: scene graph (`Scene2DBase`, `Entity2D`), components (`Panel2D`, `Label2D`, `Sprite2D`), physics (`RigidBody2D`, `PhysicsWorld2D`)

core/src/main/java/com/jvn/core/nativebridge/NativeMathBridge.java

@@ -26,8 +26,40 @@ public static double[] matMul(double[] a, double[] b, int m, int n, int p) {
     }
   }
 
+  public static double[] matVec(double[] a, double[] x, int m, int n) {
+    if (!LOADED) return matVecJava(a, x, m, n);
+    try {
+      return matVecNative(a, x, m, n);
+    } catch (UnsatisfiedLinkError e) {
+      return matVecJava(a, x, m, n);
+    }
+  }
+
+  public static double[] matMulBlocked(double[] a, double[] b, int m, int n, int p, int blockSize) {
+    if (!LOADED) return matMulBlockedJava(a, b, m, n, p, blockSize);
+    try {
+      return matMulBlockedNative(a, b, m, n, p, blockSize);
+    } catch (UnsatisfiedLinkError e) {
+      return matMulBlockedJava(a, b, m, n, p, blockSize);
+    }
+  }
+
+  public static double[] conv2d(double[] input, int width, int height,
+                                double[] kernel, int kWidth, int kHeight) {
+    if (!LOADED) return conv2dJava(input, width, height, kernel, kWidth, kHeight);
+    try {
+      return conv2dNative(input, width, height, kernel, kWidth, kHeight);
+    } catch (UnsatisfiedLinkError e) {
+      return conv2dJava(input, width, height, kernel, kWidth, kHeight);
+    }
+  }
+
   private static native double dotProductNative(double[] a, double[] b);
   private static native double[] matMulNative(double[] a, double[] b, int m, int n, int p);
+  private static native double[] matVecNative(double[] a, double[] x, int m, int n);
+  private static native double[] matMulBlockedNative(double[] a, double[] b, int m, int n, int p, int blockSize);
+  private static native double[] conv2dNative(double[] input, int width, int height,
+                                              double[] kernel, int kWidth, int kHeight);
 
   private static double dotProductJava(double[] a, double[] b) {
     if (a == null || b == null) return 0.0;
@@ -56,4 +88,77 @@ private static double[] matMulJava(double[] a, double[] b, int m, int n, int p)
     }
     return out;
   }
+
+  private static double[] matVecJava(double[] a, double[] x, int m, int n) {
+    if (a == null || x == null || m <= 0 || n <= 0) return new double[0];
+    if (a.length < m * n || x.length < n) return new double[0];
+    double[] out = new double[m];
+    for (int i = 0; i < m; i++) {
+      int aRow = i * n;
+      double sum = 0.0;
+      for (int k = 0; k < n; k++) {
+        sum += a[aRow + k] * x[k];
+      }
+      out[i] = sum;
+    }
+    return out;
+  }
+
+  private static double[] matMulBlockedJava(double[] a, double[] b, int m, int n, int p, int blockSize) {
+    if (a == null || b == null || m <= 0 || n <= 0 || p <= 0) return new double[0];
+    if (a.length < m * n || b.length < n * p) return new double[0];
+    int bs = blockSize <= 0 ? 32 : blockSize;
+    double[] out = new double[m * p];
+    for (int ii = 0; ii < m; ii += bs) {
+      int iMax = Math.min(m, ii + bs);
+      for (int kk = 0; kk < n; kk += bs) {
+        int kMax = Math.min(n, kk + bs);
+        for (int jj = 0; jj < p; jj += bs) {
+          int jMax = Math.min(p, jj + bs);
+          for (int i = ii; i < iMax; i++) {
+            int aRow = i * n;
+            int cRow = i * p;
+            for (int k = kk; k < kMax; k++) {
+              double aval = a[aRow + k];
+              int bRow = k * p;
+              for (int j = jj; j < jMax; j++) {
+                out[cRow + j] += aval * b[bRow + j];
+              }
+            }
+          }
+        }
+      }
+    }
+    return out;
+  }
+
+  private static double[] conv2dJava(double[] input, int width, int height,
+                                     double[] kernel, int kWidth, int kHeight) {
+    if (input == null || kernel == null || width <= 0 || height <= 0 || kWidth <= 0 || kHeight <= 0) {
+      return new double[0];
+    }
+    if (input.length < width * height || kernel.length < kWidth * kHeight) return new double[0];
+    double[] out = new double[width * height];
+    int kCenterX = kWidth / 2;
+    int kCenterY = kHeight / 2;
+    for (int y = 0; y < height; y++) {
+      int row = y * width;
+      for (int x = 0; x < width; x++) {
+        double sum = 0.0;
+        for (int ky = 0; ky < kHeight; ky++) {
+          int iy = y + ky - kCenterY;
+          if (iy < 0 || iy >= height) continue;
+          int iRow = iy * width;
+          int kRow = ky * kWidth;
+          for (int kx = 0; kx < kWidth; kx++) {
+            int ix = x + kx - kCenterX;
+            if (ix < 0 || ix >= width) continue;
+            sum += input[iRow + ix] * kernel[kRow + kx];
+          }
+        }
+        out[row + x] = sum;
+      }
+    }
+    return out;
+  }
 }

core/src/test/java/com/jvn/core/nativebridge/NativeMathBridgeTest.java

@@ -0,0 +1,77 @@
+package com.jvn.core.nativebridge;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+public class NativeMathBridgeTest {
+  @Test
+  void dotProductMatches() {
+    double[] a = {1, 2, 3};
+    double[] b = {4, 5, 6};
+    double res = NativeMathBridge.dotProduct(a, b);
+    assertEquals(32.0, res, 1e-9);
+  }
+
+  @Test
+  void matMulMatches() {
+    double[] a = {
+      1, 2, 3,
+      4, 5, 6
+    };
+    double[] b = {
+      7, 8,
+      9, 10,
+      11, 12
+    };
+    double[] out = NativeMathBridge.matMul(a, b, 2, 3, 2);
+    assertArrayEquals(new double[] {58, 64, 139, 154}, out, 1e-9);
+  }
+
+  @Test
+  void matVecMatches() {
+    double[] a = {
+      1, 2, 3,
+      4, 5, 6
+    };
+    double[] x = {2, 3, 4};
+    double[] out = NativeMathBridge.matVec(a, x, 2, 3);
+    assertArrayEquals(new double[] {20, 47}, out, 1e-9);
+  }
+
+  @Test
+  void matMulBlockedMatches() {
+    double[] a = {
+      1, 2, 3,
+      4, 5, 6
+    };
+    double[] b = {
+      7, 8,
+      9, 10,
+      11, 12
+    };
+    double[] out = NativeMathBridge.matMulBlocked(a, b, 2, 3, 2, 2);
+    assertArrayEquals(new double[] {58, 64, 139, 154}, out, 1e-9);
+  }
+
+  @Test
+  void conv2dMatches() {
+    double[] input = {
+      1, 2, 1,
+      0, 1, 0,
+      2, 1, 2
+    };
+    double[] kernel = {
+      0, 1, 0,
+      1, -4, 1,
+      0, 1, 0
+    };
+    double[] out = NativeMathBridge.conv2d(input, 3, 3, kernel, 3, 3);
+    assertArrayEquals(new double[] {
+      -2, -5, -2,
+      4, -1, 4,
+      -7, 1, -7
+    }, out, 1e-9);
+  }
+}

docs/Interop.md

@@ -0,0 +1,69 @@
+# Interop Guide
+
+This document describes how VNS, JES, and runtime code talk to each other.
+
+## VNS → Runtime
+
+VNS `[command ...]` lines are parsed into `VnExternalCommand` entries. The runtime handles them through `VnInterop`:
+
+- `core/src/main/java/com/jvn/core/vn/DefaultVnInterop.java`
+- `runtime/src/main/java/com/jvn/runtime/RuntimeVnInterop.java`
+
+### Default providers (engine-wide)
+
+- `hud <msg>` → temporary HUD toast.
+- `java <Class#method args...>` → invoke a public static Java method.
+- `var set|inc|dec|flag|unflag|clear ...` → set VN variables.
+- `cond if <expr>` → conditional jump logic (used by choices).
+- `settings` / `mode` / `ui` / `history` → player settings & overlays.
+- `audio pause|resume|seek|crossfade ...`
+- `screen shake|flash ...`
+- `save` (quick save/load helpers).
+
+### Runtime providers
+
+- `jes push|replace|pop|call ...`
+- `vns push|replace|goto ...`
+- `menu settings|save|load|main ...`
+
+These are implemented by `RuntimeVnInterop` and only available in the runtime module.
+
+## VNS ↔ JES
+
+From VNS:
+
+- `[jes push <script.jes> label <returnLabel> with k=v ...]`
+- `[jes replace <script.jes> ...]`
+- `[jes pop]`
+- `[jes call <name> k=v ...]`
+
+From JES:
+
+- `call "return" { label: "after_game", score: 123 }`
+  - Pops the JES scene.
+  - Copies props into VN variables (except `label`/`goto`).
+  - Jumps to the return label (prop wins, else VNS `label` argument).
+- `call "vns"` is an alias of `return`.
+- `call "hud" { msg: "Saved!" }` shows a VN toast.
+- `call "pop" {}` pops without jumping.
+
+## JES Call Handlers
+
+If you load JES from Java, you can attach handlers:
+
+```java
+JesScene2D scene = JesLoader.load(in);
+scene.registerCall("spawnWave", props -> { /* ... */ });
+scene.setActionHandler((name, props) -> { /* fallback */ });
+```
+
+Handlers are invoked for `call "name" { ... }` statements or trigger volumes.
+
+## Data Types
+
+Interop props are parsed as:
+- `true/false` → boolean
+- numbers with `.` → double, integers otherwise
+- everything else → string
+
+Avoid spaces in values (`difficulty=hard`, `title=Hello_World`).

docs/JES Scripting/JES Scripting.md

@@ -22,7 +22,7 @@ JES (JVN Engine Script) is a small DSL for scenes, entities, components, input,
   ```jes
   call "return" { label: "after_game" score: 123 }
   ```
-- See also: `docs/VNS Scripting.md` (calling JES) and `docs/Timeline Scripting.md` (narrative flow).
+- See also: `docs/VNS Scripting/VNS Scripting.md` (calling JES), `docs/Timeline Scripting/Timeline Scripting.md` (narrative flow), and `docs/Interop.md`.
 
 ## Example
 
@@ -106,6 +106,27 @@ call "return" { label: "after_game" score: 12345 }
 
 See also: docs/VNS Scripting.md → "JES interop from VNS".
 
+## Runtime hooks (Java)
+
+If you load JES from Java, you can register handlers to respond to `call` statements, input events, or triggers.
+
+```java
+JesScene2D scene = JesLoader.load(in);
+
+scene.registerCall("spawnWave", props -> {
+  // Use props like { count: 5, speed: 120 }
+});
+
+scene.setActionHandler((name, props) -> {
+  // Fallback for any call not explicitly registered
+});
+```
+
+Notes:
+- `registerCall` attaches specific handlers by name.
+- `setActionHandler` is a catch-all callback used if no handler matches.
+- Built-in `call` names like `warpMap` or `attack` are handled internally before handlers run.
+
 ## Easing Types
 Optional easing property for timeline actions:
 - linear (default)

docs/Overview.md

@@ -13,3 +13,10 @@ Key highlights:
 - Lightweight, pure-Java, JDK 17
 - Swing and JavaFX rendering backends
 - Extendable loader and components
+
+## Docs
+
+- `docs/VNS Scripting/VNS Scripting.md` - visual novel scripting
+- `docs/JES Scripting/JES Scripting.md` - scene DSL and runtime hooks
+- `docs/Interop.md` - VNS/JES/runtime interoperability
+- `docs/Performance.md` - lightweight build tips

docs/Performance.md

@@ -0,0 +1,30 @@
+# Lightweight Builds & Performance
+
+These tips help keep JVN shipped games small and fast.
+Quickly whipped up doc, I'll add more to it later. 
+
+## Assets
+- Favor smaller textures; target your runtime resolution to avoid scaling oversized art.
+- Use spritesheets to reduce file count and texture binds.
+- Prefer compressed audio (OGG/MP3) for BGM/SFX; avoid uncompressed WAV for long tracks.
+- Keep optional high-res assets in external packs and load via `--assets`.
+
+## VNS
+- Reuse backgrounds and character sprites across scenes.
+- Limit heavy transitions in rapid succession.
+- Avoid excessive HUD messages or screen effects during fast input sequences.
+
+## JES / Scene2D
+- Keep entity counts low per scene; reuse pooled entities where possible.
+- Minimize active physics bodies and sensors.
+- Disable debug overlays in production.
+- Prefer simple timeline actions over per-frame scripted logic.
+
+## Runtime
+- Use `ViewportScaler2D.fit` to render at a stable base resolution.
+- Cache assets using `AssetCatalog` and avoid reloading each frame.
+- Use the JavaFX backend only when needed; Swing remains a lighter option.
+
+## Native Bridge (Optional)
+- Native math kernels are optional. If the native library is missing, the Java fallback runs.
+- Bundle native libs only when a measurable win is needed on target hardware.