BlueGit

timfa frameworkv3

Optimize scene draw-order updates for frequent layer changes.

Reuse one sorted buffer instead of slice().sort() each dirty frame, notify the scene from GameObject.layer, and splice-reinsert when only a few objects move.

timfa Tim Falken · pushed by timfa

Authored 2026-09-06 · 2 months ago

Hash
1bc8317d65c82f83f8249322d4cbb74613ee4177
Parent
417815da
2 files changed +123 −9
framework/engine/gameobject.js +16 −2
@@ -4,7 +4,7 @@ class GameObject
4 4 renderer = null;
5 5 collider = null;
6 6 scene = null;
7 layer = 0;
7 _layer = 0;
8 8 tags = [];
9 9
10 10 destroyed = false;
@@ -14,7 +14,21 @@ class GameObject
14 14 this.transform = new Transform(this, x, y, 1, 1, 0);
15 15 this.renderer = new Renderer(this, sprite);
16 16 this.collider = new Collider(this);
17 this.layer = layer;
17 this._layer = layer;
18 }
19
20 get layer ()
21 {
22 return this._layer;
23 }
24
25 set layer (value)
26 {
27 if (this._layer === value)
28 { return; }
29 this._layer = value;
30 if (this.scene)
31 { this.scene.objectLayerChanged(this); }
18 32 }
19 33
20 34 initQuadtree (quadTree)
@@ -4,7 +4,7 @@ class GameObject
4 renderer = null;
4 renderer = null;
5 collider = null;
5 collider = null;
6 scene = null;
6 scene = null;
7 layer = 0;
7 _layer = 0;
8 tags = [];
8 tags = [];
9
9
10 destroyed = false;
10 destroyed = false;
@@ -14,7 +14,21 @@ class GameObject
14 this.transform = new Transform(this, x, y, 1, 1, 0);
14 this.transform = new Transform(this, x, y, 1, 1, 0);
15 this.renderer = new Renderer(this, sprite);
15 this.renderer = new Renderer(this, sprite);
16 this.collider = new Collider(this);
16 this.collider = new Collider(this);
17 this.layer = layer;
17 this._layer = layer;
18 }
19
20 get layer ()
21 {
22 return this._layer;
23 }
24
25 set layer (value)
26 {
27 if (this._layer === value)
28 { return; }
29 this._layer = value;
30 if (this.scene)
31 { this.scene.objectLayerChanged(this); }
18 }
32 }
19
33
20 initQuadtree (quadTree)
34 initQuadtree (quadTree)
framework/engine/scene.js +107 −7
@@ -16,6 +16,13 @@ class Scene
16 16 pendingRemoval = [];
17 17 _sortedActiveObjects = null;
18 18 _sortDirty = true;
19 /** Objects whose `layer` changed since the last draw-order rebuild. */
20 _layerChanged = [];
21 /**
22 * If more than this many objects change layer between draws, fall back to a
23 * full in-place sort (cheaper than many splice reinserts on large lists).
24 */
25 _layerChangeFullSortThreshold = 64;
19 26
20 27 g_primary = false;
21 28
@@ -211,11 +218,15 @@ class Scene
211 218 { return; }
212 219
213 220 this.activeObjects.push(obj);
214 this._sortDirty = true;
215 221 obj.scene = this;
216 222 obj.initQuadtree(this.quadTree);
217 223 obj.checkQuadtree();
218 224
225 if (this._sortedActiveObjects && !this._sortDirty && !this._layerChanged.length)
226 { this.#insertSortedByLayer(this._sortedActiveObjects, obj); }
227 else
228 { this._sortDirty = true; }
229
219 230 obj.addedToScene && obj.addedToScene();
220 231
221 232 return obj;
@@ -235,6 +246,98 @@ class Scene
235 246 { this.quadTree.remove(obj); }
236 247 }
237 248
249 /**
250 * Called when an object's draw-priority `layer` changes.
251 * Batches small moves for splice-reinsert; floods into a full sort when many change.
252 */
253 objectLayerChanged (obj)
254 {
255 if (!obj || this._sortDirty)
256 {
257 this._sortDirty = true;
258 return;
259 }
260 this._layerChanged.push(obj);
261 if (this._layerChanged.length > this._layerChangeFullSortThreshold)
262 {
263 this._sortDirty = true;
264 this._layerChanged.length = 0;
265 }
266 }
267
268 /** Force a full draw-order rebuild on the next draw (e.g. bulk external edits). */
269 markSortDirty ()
270 {
271 this._sortDirty = true;
272 this._layerChanged.length = 0;
273 }
274
275 #lowerBoundByLayer (sorted, layer)
276 {
277 let lo = 0;
278 let hi = sorted.length;
279 while (lo < hi)
280 {
281 const mid = (lo + hi) >> 1;
282 if (sorted[mid].layer < layer)
283 { lo = mid + 1; }
284 else
285 { hi = mid; }
286 }
287 return lo;
288 }
289
290 #insertSortedByLayer (sorted, obj)
291 {
292 const at = this.#lowerBoundByLayer(sorted, obj.layer);
293 sorted.splice(at, 0, obj);
294 }
295
296 #reinsertSortedByLayer (sorted, obj)
297 {
298 const from = sorted.indexOf(obj);
299 if (from >= 0)
300 { sorted.splice(from, 1); }
301 this.#insertSortedByLayer(sorted, obj);
302 }
303
304 /**
305 * Ensure `_sortedActiveObjects` matches `activeObjects` ordered by `layer`.
306 * Avoids allocating a fresh array every frame (no `slice().sort()`).
307 */
308 #ensureDrawOrder ()
309 {
310 const active = this.activeObjects;
311 if (this._sortDirty || !this._sortedActiveObjects)
312 {
313 let sorted = this._sortedActiveObjects;
314 if (!sorted)
315 {
316 sorted = new Array(active.length);
317 this._sortedActiveObjects = sorted;
318 }
319 else if (sorted.length !== active.length)
320 { sorted.length = active.length; }
321
322 for (let i = 0; i < active.length; i++)
323 { sorted[i] = active[i]; }
324
325 sorted.sort((a, b) => a.layer - b.layer);
326 this._sortDirty = false;
327 this._layerChanged.length = 0;
328 return;
329 }
330
331 if (!this._layerChanged.length)
332 { return; }
333
334 const changed = this._layerChanged;
335 const sorted = this._sortedActiveObjects;
336 for (let i = 0; i < changed.length; i++)
337 { this.#reinsertSortedByLayer(sorted, changed[i]); }
338 changed.length = 0;
339 }
340
238 341 update (deltaTime)
239 342 {
240 343 if (this.destroyed)
@@ -258,6 +361,8 @@ class Scene
258 361 }
259 362
260 363 this.pendingRemoval.length = 0;
364 this._sortDirty = true;
365 this._layerChanged.length = 0;
261 366 }
262 367
263 368 this.quadTree.update(deltaTime);
@@ -402,12 +507,7 @@ class Scene
402 507 gl.clearTransparent();
403 508 }
404 509
405 if (this._sortDirty || !this._sortedActiveObjects)
406 {
407 this._sortedActiveObjects = this.activeObjects.slice().sort((a, b) => a.layer - b.layer);
408 this._sortDirty = false;
409 }
410
510 this.#ensureDrawOrder();
411 511 const sortedActiveObjects = this._sortedActiveObjects;
412 512
413 513 // Bucket visible objects once so empty bloom layers can be skipped entirely.
@@ -16,6 +16,13 @@ class Scene
16 pendingRemoval = [];
16 pendingRemoval = [];
17 _sortedActiveObjects = null;
17 _sortedActiveObjects = null;
18 _sortDirty = true;
18 _sortDirty = true;
19 /** Objects whose `layer` changed since the last draw-order rebuild. */
20 _layerChanged = [];
21 /**
22 * If more than this many objects change layer between draws, fall back to a
23 * full in-place sort (cheaper than many splice reinserts on large lists).
24 */
25 _layerChangeFullSortThreshold = 64;
19
26
20 g_primary = false;
27 g_primary = false;
21
28
@@ -211,11 +218,15 @@ class Scene
211 { return; }
218 { return; }
212
219
213 this.activeObjects.push(obj);
220 this.activeObjects.push(obj);
214 this._sortDirty = true;
215 obj.scene = this;
221 obj.scene = this;
216 obj.initQuadtree(this.quadTree);
222 obj.initQuadtree(this.quadTree);
217 obj.checkQuadtree();
223 obj.checkQuadtree();
218
224
225 if (this._sortedActiveObjects && !this._sortDirty && !this._layerChanged.length)
226 { this.#insertSortedByLayer(this._sortedActiveObjects, obj); }
227 else
228 { this._sortDirty = true; }
229
219 obj.addedToScene && obj.addedToScene();
230 obj.addedToScene && obj.addedToScene();
220
231
221 return obj;
232 return obj;
@@ -235,6 +246,98 @@ class Scene
235 { this.quadTree.remove(obj); }
246 { this.quadTree.remove(obj); }
236 }
247 }
237
248
249 /**
250 * Called when an object's draw-priority `layer` changes.
251 * Batches small moves for splice-reinsert; floods into a full sort when many change.
252 */
253 objectLayerChanged (obj)
254 {
255 if (!obj || this._sortDirty)
256 {
257 this._sortDirty = true;
258 return;
259 }
260 this._layerChanged.push(obj);
261 if (this._layerChanged.length > this._layerChangeFullSortThreshold)
262 {
263 this._sortDirty = true;
264 this._layerChanged.length = 0;
265 }
266 }
267
268 /** Force a full draw-order rebuild on the next draw (e.g. bulk external edits). */
269 markSortDirty ()
270 {
271 this._sortDirty = true;
272 this._layerChanged.length = 0;
273 }
274
275 #lowerBoundByLayer (sorted, layer)
276 {
277 let lo = 0;
278 let hi = sorted.length;
279 while (lo < hi)
280 {
281 const mid = (lo + hi) >> 1;
282 if (sorted[mid].layer < layer)
283 { lo = mid + 1; }
284 else
285 { hi = mid; }
286 }
287 return lo;
288 }
289
290 #insertSortedByLayer (sorted, obj)
291 {
292 const at = this.#lowerBoundByLayer(sorted, obj.layer);
293 sorted.splice(at, 0, obj);
294 }
295
296 #reinsertSortedByLayer (sorted, obj)
297 {
298 const from = sorted.indexOf(obj);
299 if (from >= 0)
300 { sorted.splice(from, 1); }
301 this.#insertSortedByLayer(sorted, obj);
302 }
303
304 /**
305 * Ensure `_sortedActiveObjects` matches `activeObjects` ordered by `layer`.
306 * Avoids allocating a fresh array every frame (no `slice().sort()`).
307 */
308 #ensureDrawOrder ()
309 {
310 const active = this.activeObjects;
311 if (this._sortDirty || !this._sortedActiveObjects)
312 {
313 let sorted = this._sortedActiveObjects;
314 if (!sorted)
315 {
316 sorted = new Array(active.length);
317 this._sortedActiveObjects = sorted;
318 }
319 else if (sorted.length !== active.length)
320 { sorted.length = active.length; }
321
322 for (let i = 0; i < active.length; i++)
323 { sorted[i] = active[i]; }
324
325 sorted.sort((a, b) => a.layer - b.layer);
326 this._sortDirty = false;
327 this._layerChanged.length = 0;
328 return;
329 }
330
331 if (!this._layerChanged.length)
332 { return; }
333
334 const changed = this._layerChanged;
335 const sorted = this._sortedActiveObjects;
336 for (let i = 0; i < changed.length; i++)
337 { this.#reinsertSortedByLayer(sorted, changed[i]); }
338 changed.length = 0;
339 }
340
238 update (deltaTime)
341 update (deltaTime)
239 {
342 {
240 if (this.destroyed)
343 if (this.destroyed)
@@ -258,6 +361,8 @@ class Scene
258 }
361 }
259
362
260 this.pendingRemoval.length = 0;
363 this.pendingRemoval.length = 0;
364 this._sortDirty = true;
365 this._layerChanged.length = 0;
261 }
366 }
262
367
263 this.quadTree.update(deltaTime);
368 this.quadTree.update(deltaTime);
@@ -402,12 +507,7 @@ class Scene
402 gl.clearTransparent();
507 gl.clearTransparent();
403 }
508 }
404
509
405 if (this._sortDirty || !this._sortedActiveObjects)
510 this.#ensureDrawOrder();
406 {
407 this._sortedActiveObjects = this.activeObjects.slice().sort((a, b) => a.layer - b.layer);
408 this._sortDirty = false;
409 }
410
411 const sortedActiveObjects = this._sortedActiveObjects;
511 const sortedActiveObjects = this._sortedActiveObjects;
412
512
413 // Bucket visible objects once so empty bloom layers can be skipped entirely.
513 // Bucket visible objects once so empty bloom layers can be skipped entirely.