Skip to content

Add mesh limits and clone recycling to prevent memory overflow#402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tracygardner merged 7 commits into from
Mar 15, 2026
Merged

Add mesh limits and clone recycling to prevent memory overflow #402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a8d37ec
Add mesh memory management guards for unbounded mesh spawning
claude Mar 15, 2026
abfc786
Fix per-model instance limit for createObject and createCharacter loops
claude Mar 15, 2026
cb06b76
Extend per-source recycling to primitive shapes; consolidate with sha…
claude Mar 15, 2026
215fa17
Increase maxClonesPerSource from 100 to 500
claude Mar 15, 2026
86002f5
Add meshRecyclingEnabled flag to gate per-source mesh recycling
claude Mar 15, 2026
cf5e2eb
Address CodeRabbit review comments on PR #402
claude Mar 15, 2026
ce03ed8
Add meshLimitEnabled flag to gate global mesh count limit
claude Mar 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions api/models.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -54,6 +54,10 @@ export const flockModels = {
modelName = modelName.replace(/[^a-zA-Z0-9._-]/g, "");
desiredBase = desiredBase.replace(/[^a-zA-Z0-9._-]/g, "");

if (flock.maxMeshesReached()) return "error_" + flock.scene.getUniqueId();

flock._recycleOldestByKey(modelName);

// --- compose final runtime name using RAW key, and reserve it ---
const desiredFinalName = desiredBase;
const meshName = flock._reserveName(desiredFinalName); // may suffix on true collision
Expand DownExpand Up@@ -165,6 +169,8 @@ export const flockModels = {
resolveReady(mesh);
cleanupAbort();

flock._registerInstance(modelName, meshName);

// Allow the container to be GC'd (anims/skeletons are now in the scene)
releaseContainer(container);
})
Expand DownExpand Up@@ -268,6 +274,8 @@ export const flockModels = {
};

try {
if (flock.maxMeshesReached()) return "error_" + flock.scene.getUniqueId();

Comment on lines +277 to +278

@coderabbitaicoderabbitaiBotMar 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Check remaining mesh capacity before operations that add multiple meshes.

The maxMeshesReached() checks at lines 277, 299, and 309 only verify the current total against the limit. However, the subsequent operations— container.addAllToScene() (line 283), container.addToScene() (line 313), and especially container.instantiateHierarchy() (line 338)—can add multiple meshes in a single call. A scene with few remaining slots can overshoot the maxMeshes limit by adding an entire cloned hierarchy or container, even though the check passed moments before. Since these operations may also be called after async waits or loads (visible in the function flow), the check state can become stale between the validation and the actual mesh addition.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api/models.js` around lines 277 - 278, The current maxMeshesReached() checks
are insufficient because container.addAllToScene(), container.addToScene(), and
container.instantiateHierarchy() can add multiple meshes at once and may run
after async waits; update the code to compute or reserve the number of meshes
that each of these operations will add and verify (or atomically reserve) that
flock.maxMeshes - flock.currentMeshCount >= meshesToAdd before calling them.
Specifically, before calling container.addAllToScene(), container.addToScene(),
or container.instantiateHierarchy(), call or derive a method/logic to get the
expected addition count (e.g., container.countMeshes() or inspecting the
hierarchy/clone size), perform the capacity check against flock.maxMeshes
(instead of just flock.maxMeshesReached()), and fail early (return the same
"error_" + flock.scene.getUniqueId()) if insufficient capacity; ensure the check
is done immediately before the add and consider making the reservation
synchronous to avoid races after async awaits.

let [desiredBase, bKey] = modelId.includes("__")
? modelId.split("__")
: [modelId, modelId];
Expand All@@ -288,15 +296,19 @@ export const flockModels = {
flock.modelReadyPromises.set(meshName, readyPromise);

if (flock.modelCache[modelName]) {
flock._recycleOldestByKey(modelName);
const mesh = flock.modelCache[modelName].clone(bKey);
flock._registerInstance(modelName, meshName);
finalizeMesh(mesh, meshName, groupName, bKey);
resolveReady(mesh);
return meshName;
}

if (flock.modelsBeingLoaded[modelName]) {
flock.modelsBeingLoaded[modelName].then(() => {
flock._recycleOldestByKey(modelName);
const mesh = flock.modelCache[modelName].clone(bKey);
flock._registerInstance(modelName, meshName);
finalizeMesh(mesh, meshName, groupName, bKey);
resolveReady(mesh);
});
Expand DownExpand Up@@ -342,6 +354,8 @@ export const flockModels = {
setTemplateFlags(template, modelName);
flock.modelCache[modelName] = template;

flock._registerInstance(modelName, meshName);

finalizeMesh(root, meshName, groupName, bKey);
resolveReady(root);
releaseContainer(container);
Expand Down
11 changes: 7 additions & 4 deletions api/scene.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -536,15 +536,18 @@ export const flockScene = {
});
},
cloneMesh({ sourceMeshName, cloneId, callback = null }) {
if (flock.maxMeshesReached()) return "error_" + cloneId;

const uniqueCloneId = cloneId + "_" + flock.scene.getUniqueId();

flock.whenModelReady(sourceMeshName, (sourceMesh) => {
if (!sourceMesh || sourceMesh.isDisposed?.()) return;

flock._recycleOldestByKey(sourceMeshName);

const clone = sourceMesh.clone(uniqueCloneId);

sourceMesh.metadata.clones = sourceMesh.metadata.clones || [];
sourceMesh.metadata.clones = sourceMesh.metadata.clones.concat(
clone.name,
);
flock._registerInstance(sourceMeshName, clone.name);

if (clone) {
sourceMesh.computeWorldMatrix(true);
Expand Down
20 changes: 20 additions & 0 deletions api/shapes.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -251,6 +251,9 @@ export const flockShapes = {
boxId = boxId + "_" + flock.scene.getUniqueId();
}

if (flock.maxMeshesReached()) return null;
flock._recycleOldestByKey(blockKey);
Comment thread
coderabbitai[bot] marked this conversation as resolved.

const dimensions = { width, height, depth };

// Retrieve cached VertexData or create it if this is the first instance
Expand DownExpand Up@@ -289,6 +292,7 @@ export const flockShapes = {
flock.applyPhysics(newBox, boxShape);

flock.announceMeshReady(newBox.name, groupName);
flock._registerInstance(blockKey, newBox.name);

if (callback) {
requestAnimationFrame(() => callback());
Expand DownExpand Up@@ -325,6 +329,9 @@ export const flockShapes = {
sphereId = sphereId + "_" + flock.scene.getUniqueId();
}

if (flock.maxMeshesReached()) return null;
flock._recycleOldestByKey(blockKey);

const dimensions = { diameterX, diameterY, diameterZ };

// Retrieve cached VertexData or create it if this is the first instance
Expand DownExpand Up@@ -361,6 +368,7 @@ export const flockShapes = {
flock.applyPhysics(newSphere, sphereShape);

flock.announceMeshReady(newSphere.name, groupName);
flock._registerInstance(blockKey, newSphere.name);

if (callback) {
requestAnimationFrame(() => callback());
Expand DownExpand Up@@ -406,6 +414,9 @@ export const flockShapes = {
cylinderId = cylinderId + "_" + flock.scene.getUniqueId();
}

if (flock.maxMeshesReached()) return null;
flock._recycleOldestByKey(blockKey);

// Get or create cached VertexData
const vertexData = flock.getOrCreateGeometry(
"Cylinder",
Expand DownExpand Up@@ -448,6 +459,7 @@ export const flockShapes = {
flock.applyPhysics(newCylinder, cylinderShape);

flock.announceMeshReady(newCylinder.name, groupName);
flock._registerInstance(blockKey, newCylinder.name);

if (callback) {
requestAnimationFrame(() => callback());
Expand DownExpand Up@@ -484,6 +496,9 @@ export const flockShapes = {
capsuleId = capsuleId + "_" + flock.scene.getUniqueId();
}

if (flock.maxMeshesReached()) return null;
flock._recycleOldestByKey(blockKey);

// Get or create cached VertexData
const vertexData = flock.getOrCreateGeometry(
"Capsule",
Expand DownExpand Up@@ -535,6 +550,7 @@ export const flockShapes = {
flock.applyPhysics(newCapsule, capsuleShape);

flock.announceMeshReady(newCapsule.name, groupName);
flock._registerInstance(blockKey, newCapsule.name);

if (callback) {
requestAnimationFrame(() => callback());
Expand All@@ -558,6 +574,9 @@ export const flockShapes = {
planeId = planeId + "_" + flock.scene.getUniqueId();
}

if (flock.maxMeshesReached()) return null;
flock._recycleOldestByKey(blockKey);

const newPlane = flock.BABYLON.MeshBuilder.CreatePlane(
planeId,
{
Expand DownExpand Up@@ -610,6 +629,7 @@ export const flockShapes = {
newPlane.metadata.blockKey = blockKey;

flock.announceMeshReady(newPlane.name, groupName);
flock._registerInstance(blockKey, newPlane.name);

if (callback) {
requestAnimationFrame(() => callback());
Expand Down
33 changes: 33 additions & 0 deletions flock.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -94,6 +94,9 @@ export const flock = {
meshDebug: false,
performanceOverlay: false,
maxMeshes: 5000,
maxClonesPerSource: 500,
meshLimitEnabled: false,
meshRecyclingEnabled: false,
console: console,
havokAbortHandled: false,
triggerHandlingDebug: false,
Expand DownExpand Up@@ -207,7 +210,37 @@ export const flock = {

return errorContext;
},
// Prune disposed entries and auto-recycle the oldest live instance
// when the per-key cap is hit. Used by all mesh creation paths.
// Only active when flock.meshRecyclingEnabled is true.
_recycleOldestByKey(key) {
if (!flock.meshRecyclingEnabled) return;
if (!flock._modelInstances) flock._modelInstances = Object.create(null);
const current = Array.isArray(flock._modelInstances[key])
? flock._modelInstances[key]
: [];
flock._modelInstances[key] = current.filter((name) => {
const m = flock.scene?.getMeshByName(name);
return m && !m.isDisposed();
});
const max = flock.maxClonesPerSource ?? 500;
if (flock._modelInstances[key].length >= max) {
const oldestName = flock._modelInstances[key][0];
const oldest = flock.scene?.getMeshByName(oldestName);
if (oldest) flock.disposeMesh(oldest);
flock._modelInstances[key] =
flock._modelInstances[key].slice(1);
}
},
_registerInstance(key, meshName) {
if (!flock._modelInstances) flock._modelInstances = Object.create(null);
const current = Array.isArray(flock._modelInstances[key])
? flock._modelInstances[key]
: [];
flock._modelInstances[key] = current.concat(meshName);
},
Comment thread
coderabbitai[bot] marked this conversation as resolved.
maxMeshesReached() {
if (!flock.meshLimitEnabled) return false;
const scene = flock?.scene;
if (!scene || typeof flock.maxMeshes !== "number") return false;

Expand Down
Loading