perf(renderer3d): InstantiatePlane collapses identical plane primitives into one instanced draw (#679) (#685)

* perf(renderer3d): add InstantiatePlane to collapse identical plane primitives into one instanced draw (#679)

`CreatePlane` primitives previously bypassed the instancing path so a per-tile
terrain (40k planes / 9 materials) produced 11k+ draw calls. `InstantiatePlane`
mirrors `InstantiateModel` for primitives: every instance that shares the same
source plane renders through a single instanced draw call -- ~9 draws for a
9-material terrain regardless of tile count.

- New `instantiate_plane(source_plane_id) -> u32` engine method backed by a
  per-source-plane pool (`PlaneInstancePool`) over the existing
  `instanced_meshes` map. Pool grows with `next_power_of_two` capacity, dirty
  flush re-uploads once per frame.
- `set_object_position` / rotation / scale and `remove_object` dispatch to the
  pool first; `add_object_to_scene` resolves an instance handle to its source
  plane so the existing scene API works unchanged.
- Scene filtering for plane-instance pools: a pool only draws when its source
  plane is in the current scene.
- New FFI export `goud_renderer3d_instantiate_plane` and schema entry; codegen
  regenerated all 9 SDK wrappers.
- 4 new tests: 10k tiles collapse to 1 instanced draw; per-instance transforms
  + remove keep the pool dense; two source planes -> two draw calls; current
  scene gates the pool.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(renderer3d): cascade plane-instance pool teardown + skip avoidable clone (#679 review)

Addresses code-quality, security, and spec review feedback on the
InstantiatePlane PR:

- Removing the source plane via destroy_object now tears down its pool
  (frees GPU buffers, invalidates every instance handle) so a future
  object id reusing the same value cannot route into a stale pool.
- flush_dirty_plane_instance_pools no longer clones the live
  instances Vec on the steady-state in-place upload path; uses a
  split-borrow with a SAFETY-commented unsafe slice plus a persistent
  scratch buffer for the dirty-id list. Grow path uses mem::take/swap
  to pad without cloning.
- instantiate_plane drops the .expect() panic; lookup falls back
  to None gracefully and reserves the object id only after the
  pool lookup succeeds.
- New regression test test_remove_source_plane_cascades_pool_teardown
  asserts pool teardown + handle invalidation when the source plane
  is destroyed.
- FFI doc + schema doc explain interaction with set_static_batching_enabled,
  set_instancing_enabled, and set_min_instances_for_batching for primitives
  and InstantiatePlane (spec ask 3 of #679). All SDK wrappers regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(tests): split plane-instance tests into sibling file (#679 CI)

scripts/check-rs-line-limit.sh enforces a 500-line cap on .rs files. The
new plane-instance tests pushed renderer3d/tests.rs to 615 lines, which
made CI's `Rust File Line Limit` job fail. Moved the 5 plane-instance
tests into a sibling `tests_plane_instances.rs` so both files stay under
the cap. No test logic changed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ffi): re-export goud_renderer3d_instantiate_plane from renderer3d/mod.rs (#679 CI)

The Lua codegen imports `crate::ffi::renderer3d::goud_renderer3d_instantiate_plane`,
which requires it to be re-exported from `ffi/renderer3d/mod.rs` like its
sibling primitive exports. Added it to the `pub use primitives::{...}` list
so `cargo check --workspace --all-targets` (the Preflight CI gate) passes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: ignore .claude/scheduled_tasks.lock runtime artifact

This file is a per-machine lockfile created by Claude Code's ScheduleWakeup
runtime; it should not be tracked in git.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* perf(renderer3d): drop redundant clones + unsafe in plane-instance pool (#679 review)

Addresses Claude PR review warnings on #685:

- W1: source.vertices.clone() now happens only when creating a new pool
  (the else branch). Previously it ran on every instantiate_plane call,
  costing ~39_991 redundant Vec<f32> allocations during a 40k-tile setup
  over 9 source planes.
- W2: replace the unsafe split-borrow + raw pointer slice in
  flush_dirty_plane_instance_pools' in-place update path with a safe
  field-disjoint borrow. NLL proves self.instanced_meshes and self.backend
  don't overlap; the SAFETY comment is no longer needed.
- W3: FFI doc on goud_renderer3d_instantiate_plane now spells out that
  the source plane itself still costs one per-object draw on top of the
  instanced draw, and recommends frustum exclusion or first-tile reuse.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ts-web-sdk): add instantiatePlane stub to satisfy IGoudGame (#679 CI)

The web TypeScript SDK doesn't have a real backend for renderer3d, so
codegen/gen_ts_web.py emits hardcoded stubs returning 0/false for every
3D method. The IGoudGame interface requires instantiatePlane (added in
this PR), so the web GoudGame class needs a matching stub or TS2420
fails the wasm build.

Added the stub next to instantiateModel; regenerated all SDKs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: aram-devdocs

.gitignore

@@ -132,3 +132,4 @@ examples/go/*/sandbox
 # Coverage artifacts
 .coverage
 **/coverage/
+.claude/scheduled_tasks.lock

codegen/ffi_manifest.json

@@ -3695,6 +3695,15 @@
       "return_type": "i32",
       "is_unsafe": true
     },
+    "goud_renderer3d_instantiate_plane": {
+      "source_file": "ffi/renderer3d/primitives.rs",
+      "params": [
+        "context_id: GoudContextId",
+        "source_plane_id: u32"
+      ],
+      "return_type": "u32",
+      "is_unsafe": false
+    },
     "goud_renderer3d_is_animation_playing": {
       "source_file": "ffi/renderer3d/animation.rs",
       "params": [
@@ -6593,5 +6602,5 @@
       "is_unsafe": false
     }
   },
-  "total_count": 669
+  "total_count": 670
 }

codegen/ffi_mapping.json

@@ -636,6 +636,7 @@
     "renderer_3d": {
       "goud_renderer3d_create_cube": {},
       "goud_renderer3d_create_plane": {},
+      "goud_renderer3d_instantiate_plane": {},
       "goud_renderer3d_create_sphere": {},
       "goud_renderer3d_create_cylinder": {},
       "goud_renderer3d_set_object_position": {},

codegen/gen_ts_web.py

@@ -1162,6 +1162,7 @@ def gen_web_wrapper():
     lines.append("  loadModel(_path: string): number { return 0; }")
     lines.append("  destroyModel(_modelId: number): boolean { return false; }")
     lines.append("  instantiateModel(_sourceModelId: number): number { return 0; }")
+    lines.append("  instantiatePlane(_sourcePlaneId: number): number { return 0; }")
     lines.append("  setModelMaterial(_modelId: number, _meshIndex: number, _materialId: number): boolean { return false; }")
     lines.append("  getModelMeshCount(_modelId: number): number { return 0; }")
     lines.append("  getModelBoundingBox(_modelId: number): { minX: number; minY: number; minZ: number; maxX: number; maxY: number; maxZ: number } { return { minX: 0, minY: 0, minZ: 0, maxX: 0, maxY: 0, maxZ: 0 }; }")

codegen/generated/goud_engine.h

@@ -2728,6 +2728,11 @@ uint32_t goud_renderer3d_create_cube(struct GoudContextId context_id, uint32_t t
  */
 uint32_t goud_renderer3d_create_plane(struct GoudContextId context_id, uint32_t texture_id, float width, float depth);
 
+/**
+ * Creates an instance of a source plane primitive.
+ */
+uint32_t goud_renderer3d_instantiate_plane(struct GoudContextId context_id, uint32_t source_plane_id);
+
 /**
  * Creates a 3D sphere object.
  */

codegen/goud_sdk.schema.json

@@ -5055,6 +5055,17 @@
           ],
           "returns": "u32"
         },
+        {
+          "name": "instantiatePlane",
+          "doc": "Creates an instanced plane that shares geometry with a source plane (issue #679). All instances of the same source plane render through one instanced draw call regardless of setStaticBatchingEnabled / setInstancingEnabled / setMinInstancesForBatching (those flags govern non-instanced primitives and skinned models, not plane-instance pools). Use one source plane per material to draw multiple materials. Destroying the source plane cascades: the pool is freed and existing instance handles are invalidated.",
+          "params": [
+            {
+              "name": "sourcePlaneId",
+              "type": "u32"
+            }
+          ],
+          "returns": "u32"
+        },
         {
           "name": "createSphere",
           "doc": "Creates a 3D sphere",
@@ -13032,6 +13043,9 @@
         "createPlane": {
           "ffi": "goud_renderer3d_create_plane"
         },
+        "instantiatePlane": {
+          "ffi": "goud_renderer3d_instantiate_plane"
+        },
         "createSphere": {
           "ffi": "goud_renderer3d_create_sphere"
         },

goud_engine/src/ffi/renderer3d/mod.rs

@@ -62,8 +62,9 @@ pub use postprocess::{
 pub use primitives::{
     goud_renderer3d_create_cube, goud_renderer3d_create_cylinder, goud_renderer3d_create_plane,
     goud_renderer3d_create_sphere, goud_renderer3d_destroy_object,
-    goud_renderer3d_set_object_position, goud_renderer3d_set_object_rotation,
-    goud_renderer3d_set_object_scale, goud_renderer3d_set_object_static,
+    goud_renderer3d_instantiate_plane, goud_renderer3d_set_object_position,
+    goud_renderer3d_set_object_rotation, goud_renderer3d_set_object_scale,
+    goud_renderer3d_set_object_static,
 };
 pub use scene::{
     goud_renderer3d_add_light_to_scene, goud_renderer3d_add_model_to_scene,

goud_engine/src/ffi/renderer3d/primitives.rs

@@ -106,6 +106,92 @@ pub extern "C" fn goud_renderer3d_create_plane(
     .unwrap_or(GOUD_INVALID_OBJECT)
 }
 
+/// Creates an instance of a source plane primitive.
+///
+/// Mirrors `goud_renderer3d_instantiate_model` for primitives. Every instance
+/// of the same source plane renders through one instanced draw call, so a
+/// terrain of identical-geometry tiles collapses to one batch per source plane
+/// (issue #679).
+///
+/// The returned id behaves like an object id for transform updates
+/// (`set_object_position`, `set_object_rotation`, `set_object_scale`,
+/// `destroy_object`). Per-instance materials are not supported -- the source
+/// plane's material/texture is captured when the first instance is created.
+/// Use one source plane per material to draw multiple materials.
+///
+/// # Source plane visibility
+///
+/// The source plane is a regular `Object3D`, so it is also drawn by the
+/// per-object pass. Each pool therefore costs **one extra per-object draw on
+/// top of the instanced draw** (e.g., 9 source planes + 9 pools = 18 draws,
+/// not 9). The pool's draw call collapse is still the dominant win for
+/// large terrains, but if the source plane is camera-visible callers should
+/// either:
+///
+/// * Position the source plane outside the camera frustum / view region so
+///   frustum culling drops it (recommended for terrain templates), or
+/// * Use it as the first visible tile (place it where one of the pool's
+///   instances would have been) so the per-object draw is not "extra".
+///
+/// # Lifecycle
+///
+/// Destroying the source plane via `destroy_object` cascades: the underlying
+/// pool's GPU buffers are freed, every existing instance handle is invalidated,
+/// and subsequent calls to `instantiate_plane` with the same id return
+/// `GOUD_INVALID_OBJECT`. Adding the source plane to a scene via
+/// `add_object_to_scene` makes the entire pool visible in that scene; passing
+/// an instance handle to `add_object_to_scene` resolves to the source plane.
+///
+/// # Interaction with batching flags
+///
+/// Plane-instance pools always render through the instanced path. The
+/// renderer's batching flags do **not** gate them:
+///
+/// - `set_static_batching_enabled` controls the static-batch VBO that combines
+///   non-instanced primitives marked with `set_object_static`. It does **not**
+///   apply to plane-instance pools and does not need to be enabled to benefit
+///   from `instantiate_plane`.
+/// - `set_instancing_enabled` enables instanced rendering for skinned model
+///   instances above the `min_instances_for_batching` threshold. It does
+///   **not** apply to plane-instance pools, which always batch regardless of
+///   the flag or instance count.
+/// - `set_min_instances_for_batching` is the threshold for skinned model
+///   instancing. It is ignored by plane-instance pools.
+///
+/// Primitives created via `create_plane` (without `instantiate_plane`) still
+/// follow the legacy paths: `set_object_static` + `set_static_batching_enabled`
+/// places them in the static-batch VBO; otherwise they render via the
+/// per-object pass.
+///
+/// # Arguments
+/// * `context_id` - The windowed context
+/// * `source_plane_id` - Object id returned by `goud_renderer3d_create_plane`
+///
+/// # Returns
+/// Plane-instance handle on success, GOUD_INVALID_OBJECT on failure.
+#[no_mangle]
+pub extern "C" fn goud_renderer3d_instantiate_plane(
+    context_id: GoudContextId,
+    source_plane_id: u32,
+) -> u32 {
+    if context_id == GOUD_INVALID_CONTEXT_ID {
+        set_last_error(GoudError::InvalidContext);
+        return GOUD_INVALID_OBJECT;
+    }
+
+    if let Err(e) = ensure_renderer3d_state(context_id) {
+        set_last_error(e);
+        return GOUD_INVALID_OBJECT;
+    }
+
+    with_renderer(context_id, |renderer| {
+        renderer
+            .instantiate_plane(source_plane_id)
+            .unwrap_or(GOUD_INVALID_OBJECT)
+    })
+    .unwrap_or(GOUD_INVALID_OBJECT)
+}
+
 /// Creates a 3D sphere object.
 #[no_mangle]
 pub extern "C" fn goud_renderer3d_create_sphere(

goud_engine/src/jni/generated.rs

@@ -3242,6 +3242,26 @@ pub extern "system" fn Java_com_goudengine_internal_GoudGameNative_createPlane<'
     })
 }
 
+#[allow(non_snake_case)]
+#[no_mangle]
+pub extern "system" fn Java_com_goudengine_internal_GoudGameNative_instantiatePlane<'local>(
+    mut env: jni::JNIEnv<'local>,
+    _class: jni::objects::JClass<'local>,
+    contextId: jni::sys::jlong,
+    sourcePlaneId: jni::sys::jint,
+) -> jni::sys::jint {
+    crate::jni::helpers::catch_jni_panic(&mut env, "Java_com_goudengine_internal_GoudGameNative_instantiatePlane", 0, |env| -> crate::jni::helpers::JniCallResult<jni::sys::jint> {
+            crate::jni::helpers::prepare_call(env)?;
+            crate::jni::helpers::clear_last_error();
+            let result = crate::ffi::renderer3d::goud_renderer3d_instantiate_plane(goud_context_id_from_jlong(contextId), sourcePlaneId as _);
+            if crate::jni::helpers::last_error_code() != 0 {
+                let _ = crate::jni::helpers::throw_engine_error(env, "goud_renderer3d_instantiate_plane", Some(result as i64));
+                return Err(());
+            }
+            Ok(result as i32)
+    })
+}
+
 #[allow(non_snake_case)]
 #[no_mangle]
 pub extern "system" fn Java_com_goudengine_internal_GoudGameNative_createSphere<'local>(

goud_engine/src/libs/graphics/renderer3d/core/mod.rs

@@ -165,6 +165,18 @@ pub struct Renderer3D {
     /// Object IDs that were actually included in the static batch (not overflowed).
     /// Used to distinguish batched objects from overflow objects that need individual draws.
     pub(in crate::libs::graphics::renderer3d) static_batched_ids: FxHashSet<u32>,
+    /// Pools of instanced plane primitives, keyed by `instanced_mesh_id`.
+    /// One pool per source plane; every instance through `instantiate_plane`
+    /// goes into the corresponding pool's `InstancedMesh`, collapsing to a
+    /// single instanced draw call per source plane (#679).
+    pub(in crate::libs::graphics::renderer3d) plane_instance_pools:
+        FxHashMap<u32, super::core_plane_instances::PlaneInstancePool>,
+    /// Reverse lookup from a plane-instance handle to `(instanced_mesh_id, slot)`.
+    pub(in crate::libs::graphics::renderer3d) plane_instance_index: FxHashMap<u32, (u32, usize)>,
+    /// Reverse lookup from a source plane object id to its pool's `instanced_mesh_id`.
+    pub(in crate::libs::graphics::renderer3d) source_plane_to_pool: FxHashMap<u32, u32>,
+    /// Reusable scratch buffer of dirty pool ids (avoids per-frame alloc).
+    pub(in crate::libs::graphics::renderer3d) scratch_dirty_plane_pool_ids: Vec<u32>,
 }
 
 // StaticBatchGroup is defined in core_static_batch.rs
@@ -364,6 +376,10 @@ impl Renderer3D {
             static_batch_groups: Vec::new(),
             static_batch_vertex_count: 0,
             static_batched_ids: FxHashSet::default(),
+            plane_instance_pools: FxHashMap::default(),
+            plane_instance_index: FxHashMap::default(),
+            source_plane_to_pool: FxHashMap::default(),
+            scratch_dirty_plane_pool_ids: Vec::new(),
         })
     }
 }