forgeax-engine-performance

Identify the expensive owner, remove redundant work at its actual change frequency, and verify the requested workload. Follow the checkout's delivery and rendering gates.

This Engine entrypoint owns the reusable action rules below. Detailed methods, counterexamples and dated measurements stay in the linked Harness references; raw captures stay outside source. Integrate later experience into the applicable rule here as well as its evidence reference.

Numeric allocation ownership

Choose storage by the last reader: World frame scratch for synchronous work, World-owned buffers for persistent system state, existing publication/page/device owners for suspended or submitted work. Preserve persistent semantic facts. Measure backing allocations, view/Result objects, copying/zeroing, retained capacity and metadata separately. Repeated large allocate/release can discard backing while leaking slot metadata. Fault-inject allocation admission and test spike/drain/trim before claiming a production pool. See the ECS memory contract. Guard synchronous lifetime at each actual system invocation; a manual scope wrapper alone does not prevent a suspended system from escaping reset. For allocate/fill/copy stages, pass explicit output windows and consume them before scope close; account for nonzero offsets and initialize reused lanes. Normalize a finished accumulator in place when no later reader needs its old values. Scope adapters must return expected domain failures through Result so a retryable validation error does not become a poisoned World. Include cumulative multi-view/pass demand in arena admission controls. Tiny backing savings can cost more view/Result objects; retain small factory allocations when complete-owner measurements do not support migration. For repeated borrows of one physical allocation, validate once and retain its current typed window with that allocation. Invalidate after successful resize, not failed admission, and drop the owner cache on retirement. Keep independent completion capabilities and detached release callbacks; recycling a public lease would let an old callback release a newer tenant. Compare overlapping readers, periodic/dense resize and cold allocate/retire, not just warm acquisition.

Drive the optimization

1. Freeze source/build and native payload identity, scene, backend, Workers, quality and actions. Preserve original failures. A content/profile/ABI change needs a fresh baseline. Unexplained rendering follows RHI Debug.
2. Attribute the actual expensive population before editing. Separate ordinary completion throughput, intrusive profiling and private diagnostic controls. Name removable work and a counterexample that could falsify the change.
3. Apply the ownership and hot-path rules below. Measure the complete replacement owner, including key construction, validation, allocation, retained storage, publication, uploads and retirement where affected.
4. Validate semantic controls, then compare preselected matched windows. Report implementation proof, helper results, whole-Worker results and unfinished targets separately. Batch verified owner changes before another broad run.

Choose the producer before adding reuse

Keep unique immutable visibility facts at the extraction producer, then let Feature frames share that snapshot when no additional reports change its meaning. Do not rebuild a copy and dedup Set every frame for inactive rows. Borrowed arrays, getters and custom additions remain live; shallow freeze alone is no ownership proof. Include producer capture and cold/periodic changes in the complete-owner comparison, and avoid argument expansion for unbounded entity populations.

Clearing reused small Maps/Sets can cost more CPU than fresh collections while leaving sampled allocation unchanged. Do not infer backing reuse from wrapper reuse. Prefer removing a duplicate producer envelope, comparing admitted fields before materialization, or packing a large synchronous index workspace into one arena span. Return structured allocation failures through the scope and prove a warm backing plateau, held output independence and smaller-demand recovery. Keep preparation/settlement admission closed to callback reentry before reusing private state; old candidates remain once-only capabilities.

Keep numerical membership with its admitted view when the complete binning inputs are unchanged; refresh unrelated light payloads independently. Capture numeric dependencies rather than retaining an old frame bag, validate budgets before hits, and replace the fact only after successful computation. Preserve old outputs on change, failure and disposal. Prove the actual pipeline and configuration producer: a borrowed frozen copy is not the owned default. Compare stable, periodic, dense and cold work, including output backing separately from sampled JS. A cache can remove backing churn while adding cold metadata. Inspect disabled profiling too: per-item callbacks can allocate lexical environments even without an active timer. Use a direct shared numeric kernel for ordinary execution and preserve the instrumented path's phase order and exact output.

Carry a fixed value fact from the actual material producer through its existing resource, then pass that fact to phase-local consumers. A global identity lookup on every ownership query can slow borrowed inputs; prefer direct owner evidence at the caller. Keep live readiness, proxy/getter behavior and old accepted versions independent of the current proof. Include receive/adoption cost, one material, many materials, continuous changes and borrowed controls; warm short CPU cases sufficiently and preserve the original caller in the baseline. Trace the actual receive/schema-rebinding chain: an intermediate copy can lose a producer proof before its consumer. Preserve fixed value ownership across metadata-only derivations and exact-snapshot adoption while keeping public aliases borrowed. Keep the fact with the existing resource authority instead of copying, freezing or registering every derived snapshot again. Include continuous-rebinding CPU: extra proof maintenance can cost more despite lower allocation. A snapshot fact must outlive its latest mutable resource owner. Preserve it in the existing identity authority, independently of the owner's current version; qualify multiple holders, rejected candidates, exact-snapshot clones and fresh copies. Keep borrowed entries cheap instead of adding metadata to every input.

Keep a prepared plan's fixed material/class slot projection with that actual producer capture. Let its first consumer supply the ordinary index instead of building another index before consumption; keep current accepted values and World scopes in each recording. Borrowed arrays and mixed CPU/GPU demand retain their ordinary live merge. Measure stable, periodically replaced and continuously replaced plans: a retained index can save steady work while adding cold cost.

Separate cold Scene identity/content columns from pose/version columns so a pose edit does not copy static relations. Protect matrix windows returned even before a pending page is captured; a later write or slot reuse cannot overwrite an old observation. Include real copied bytes, old-root/old-window controls and complete owner CPU in the comparison. A numeric copy reduction alone does not prove that the complete renderer scales independently of its retained row population.

Keep retained source identity separate from requested raster work. An empty GPU eligibility list does not itself imply CPU fallback: hidden and zero-instance sources need neither lane. Fix the membership producer and use the same demand predicate for receipts, diagnostic summaries and presentation. Keep real visible resource failures observable. Qualify hide/show, zero/nonzero transitions, held old rosters and actual Renderer N/K controls; a counter-only fix cannot remove unnecessary traversal. Profile diagnostic consumers as well as rendering. A warning that never fires can repeatedly scan every inactive row. Keep ordered demand membership with the captured source root and consume it directly; do not infer demand through custom projections. Bail out disabled diagnostics before reading rows, after cheaper light/latch guards. Include lit, dense-change, cold and borrowed controls so producer maintenance and small-path regressions stay visible. Full exports of N records still cost O(N); report them separately from ordinary draw work. Resolve bounded diagnostic identities through the producer's captured immutable index when it already supplies that fact; do not eagerly scan N rows for a 64-sample quota that may never fill. Preserve held roots and address generations. A borrowed array can change without changing identity, and a custom projection can change membership facts. Count and sample their current rows in one coherent observation instead of adding a second correctness scan. Compare the complete producer/record/query path, including sparse late candidates, actual pose edits, explicit queries and custom inputs; keep GPU and whole-game qualification separate. Forward diagnostic field selection to the owner before producing large inventories, rather than only selecting before cloning or serialization. Scalar status/capability reads must not build per-entity material, instance or LOD exports. Omitted selection keeps the full detached result; qualify empty and explicit full selections, old observations and cross-Worker cloning. Keep diagnostic retention/export side effects independent of output selection.

A small matrix window can retain a complete old numeric page. Repeated lane edits can leave the current row cache holding many old page buffers even after external readers close. Measure unique reachable backing through actual current outputs, including cold, rotating edits, held roots and drain. Split independently changing numeric storage into smaller immutable chunks when that reduces copying and retention; count extra chunk/view metadata, dense-write CPU and JS allocations too. Clear removed observations from the current copied page while preserving old roots. Chunking reduces the retained unit; it does not establish explicit page leases or authorize recycling storage still visible to automatic readers.

Treat bulk disposal separately from per-row removal. Clearing one authority can leave derived hierarchy maps, numerical bounds columns, staging arrays and journal capacity retained by the still reachable owner. Drive the actual bounds/cache consumers before spike/dispose tests. Return discarded history to cold capacity, keep cursor positions monotonic so old evidence cannot become current again, and verify old captured values independently of lazy wrapper identity after disposal. Count remaining cold owner storage; an empty row root does not prove zero backing. Inspect strong heap paths when retired Worlds survive a completed lifecycle. Closures created in one function can share a lexical environment: a returned callback may retain previous even when only a sibling cache predicate reads it. Create escaping products in a separate scope with their actual admitted data; keep old held products valid and prove replaced unheld products collect. Exclude WeakMap ephemeron-value edges from a purported strong retaining path, and repeat with data-only observation copies before attributing retention to the owner.

Keep full byte/DataView windows with a persistent numeric table's actual physical backing; use offsets for row writes, clearing and queue uploads. Refresh views only when that backing changes and verify nonzero source offsets through real payload assertions. CPU table retirement follows the last synchronous reader, independently of held GPU versions. Reject update/commit reentry, defer CPU release through an active queue call, and fault-inject disposal at create/upload/retire boundaries before adopting growth. Include held versions and repeated grow/dispose cycles.

Read only the allocation columns a hot consumer needs instead of materializing a complete row view. Keep full detached views for real whole-row observations. Traverse existing publication groups in their original order instead of copying their full population into an intermediate array; build membership indexes directly without mapped temporary key arrays. Qualify sparse pose, content, instance-only and dense-change paths, including zero addresses and independently held versions.

Measure retained products through their next consumer, including serialization. Fewer object allocations can still make a native graph-key path much slower when the produced object representation changes. Keep borrowed getter/toJSON semantics live and retain cold and changing controls. A plain-object sensitivity probe does not justify shipping a shared mutable product or a custom serializer; withdraw a cache whose complete-path CPU cost outweighs the allocation saving.

Share fixed stage facts and synchronous finalizer functions at their installation owner. Pass the exact preparation and accepted work into the runner instead of capturing them in new callbacks or retargeting a shared frame context. Reordering must replace event facts without changing held frames. Keep producer contexts and native-plan capabilities fresh; test throwing submit/abort/source callbacks, sibling cleanup, retry and queue-fenced retirement. Compare accepted, aborted and changing complete-owner paths before claiming a normal-frame CPU gain.

A small record pool can reduce bytes while increasing CPU through lookup and field clearing. For graph callbacks that only consume the resolved encoder, frame and resource resolver, use encodeDirect to remove the argument record. Keep the context form for callbacks that need that record, preserve bound receivers, and measure the complete graph owner with ordinary CPU separate from allocation sampling. No helper result establishes a whole-Worker improvement.

For derived World facts, record dependencies from the actual read queries and reuse StateProjection for candidate membership, additions, removals and generation replacement. Optional absence and required pose joins are inputs too. Keep resource values, time dependence, asset admission and routed failures explicit; restore observation scopes after nested or failed extraction. Arbitrary extractors retain conservative behavior until their complete read route is owned. Numeric publication ranges can feed canonical rows within admission without per-row matrix copies; return detached deltas rather than borrowed packet windows.

Compare incoming numerical columns with canonical values before hydrating row observations or staging per-identity work. A previously staged operation owns its current value: do not compare a later span only with the old columns. Read a borrowed source window once, leave missing-row windows unread, and preserve source offsets, parity, strict numeric equality, duplicate edits and removal/recreation. For large validated transform-only admission, stage numeric source coordinates in arena chunks and share the owner's existing commit-local slot index instead of creating full per-row pending records or another N-sized index. Admit all chunks before canonical writes, clear touched indices on denial, and keep sticky parity through duplicate/reverting edits. Keep borrowed getters on their ordinary route. Measure small selected inputs too: scope, view and Result overhead can outweigh the removed records, so retain tiny ordinary staging when evidence supports it.

Measure complete admission with full unchanged/partly changed input and selected/ fully changing controls. Work on an incoming N-row payload still scales with that payload; this does not prove N-independent maintenance or whole-game savings.

A hot call count does not imply a large working set; a long-lived object does not imply stable values. Avoid one cache per entity/material, pose-history FIFOs, output signatures that cost as much as the avoided work, and new age/version/ dependency scanners added solely to reduce allocation. Keep existing GPU caches, resource leases, intrinsic invalidation and recovery with their current owners. Do not attach metadata to foreign or frozen inputs.

Select the numeric hot path

Use the implemented ECS contract and Math contract; retain queries at their actual World/system lifetime, with reentry and replacement handled by that owner.

Batches reject write, changed and added descriptors; use their existing write/ temporal paths. Keep entity windows, column lookup and field positioning outside inner loops. For repeated span preparation, retain the latest complete physical column window at the column owner, including its actual backing, range and managed field type. Keep shape records fresh where callers can replace fields; retain frozen managed readers with their original bound storage, own enumeration and detached-call behavior. Partial changed-row windows must not evict the complete-table route. Replacement/growth must drop the old route instead of retargeting held readers. Measure the full query traversal and numerical work, not a cached getter alone.

Do not gather sparse rows into copied dense columns or add a row-wrapper class. Do not expand optional fields into every component combination. Borrow columns only through the valid batch/span lifetime. Structural callbacks and suspended iteration retain their original checks and temporal cursor semantics.

Require output storage for output-writing Math APIs. Returning that same output, or an independent boolean/status, is supported; factories remain explicit allocation sites. Preserve precision, aliasing and result lifetime; measure internal temporaries too. ?? 0 does not allocate; use direct indexed values after proving bounds, and retain meaningful absence handling. Do not trade clarity for many callbacks to eliminate a small fixed traversal cost without a complete-owner CPU/allocation win.

Engine implementation uses the fast paths enforced by pnpm check:ecs-iteration, pnpm check:required-output and pnpm check:foundation-allocations; apps/templates retain their gameplay APIs. These finite gates do not prove every caller is optimal or zero-allocation.

Remove CPU preparation and collection work

A cache hit can still allocate its optional-input or diagnostic collections. Read the same live flags in their original order, then build names/descriptors only in the miss or failure branch that consumes them. Keep finite numeric slots already owned by the cache. Include shared hits, ordinary hits, periodic recovery and cold descriptor production; a function-level heap attribution alone does not prove its final resource cache is missing.

A small fixed restriction must not enumerate a much larger member universe. Retain source-derived membership bounds with the immutable query and traverse the smaller valid domain; nested restrictions can pass their bound without computing an eager intersection. Preserve sorted order and member multiplicity, deduplicate restriction keys where membership is boolean, and cache exact counts only with that fixed owner. Prove attempted membership checks follow K, test both operand orders, and separate required output/tree lookups from whole-population maintenance.

Adopt borrowed key cursors only for intrinsic fixed numerical roots. Preserve the ordinary result lifetime of public Set iterators and keep arbitrary input iterables on their live path. Each walk owns independent traversal state; break/throw closes inner cursors. Empty borrowed walks can share immutable termination. Fuse nested cursor bookkeeping before adding a pool and measure the complete sparse consumer.

Clearing an array's length can discard its backing even when the wrapper is retained. At a quiet immutable output owner, retain a second ledger's capacity only when both ledgers reference the exact detached entries already held by the current root. Clear candidate/retired entries on change, failure, shrink and disposal. Do not retain borrowed source rows to save capacity. Compare the full output walk and address consumer with sparse/dense changes, duplicate/reorder controls and repeated spike/drain; removing quiet writes through an extra per-entry branch can slow the changing path more than retaining a bounded second ledger.

Index invalidation by the complete consumer dependency domain. A binding's coverage may follow a peer execution with the same material/group, World, Mesh and draw; checking only the exact binding misses changes, while rechecking every batch scales with unrelated work. Maintain the adjacency with existing source batch diffs and prune retired routes. A fixed source roster does not prove its consumer selection's routes are immutable: admit that evidence separately at the actual producer, and keep complete re-judgment for borrowed selections. Count attempted checks as well as changed outputs: a zero-write result can still hide a complete scan.

A copy-on-write page pool can duplicate backing when automatic immutable row observations must detach their numeric values before reuse. Account for those escaped values and explicit root-edge bookkeeping in the complete replacement owner. Passing last-reader tests is necessary but does not establish a memory or CPU win. Migrate internal consumers to scoped numeric rows/deltas before enabling physical page reuse; preserve automatic public observations separately. Reject an otherwise-correct pool when total backing or CPU grows.

When reconciling persistent membership, submit only actual membership flips. A row publication that changes pose or contents can leave membership unchanged; filter those no-op writes before copying bitmap pages or building an edit batch. Keep real entry/removal, availability recovery and held-frame controls.

Array push may reuse capacity; splice produces a result array. Reusing a Map/Set wrapper does not prove clear/refill reuses its backing storage. Inspect and measure actual operations rather than banning syntax by name.

Publish the final accepted projection directly when an intermediate roster adds no independent semantics. Keep per-view visibility/culling separate from shared preparation, and preserve the accepted-work selection across producer callbacks. For VFX, share immutable code/layout while each Player retains independent buffers, seed, ticks and feedback. Retained effects must keep their own complete material/mesh/texture closure through replacement, abort, ACK and retirement.

Ordered compute dispatches may share one physical pass when the producer owns predicate semantics and no required copy, timing or resource boundary intervenes. Declare the full resource union and keep each kernel's pipeline/bindings explicit. Retain separate passes for custom predicates unless explicitly admitted. Verify indirect readback, Skin overflow ordering, real pixels and GPU timestamps; fewer pass API calls alone do not establish less shader work or lower frame time. Physical pass changes also change per-pass query instrumentation. Compare an equal-write, same-scope control before attributing GPU timing changes; keep every cold/steady window and unresolved asynchronous readback visible.

Reduce GPU work through its existing contract

Fewer shader operations or taps are hypotheses until the actual backend shows both acceptable pixels and lower GPU cost. Resolution, cascade count, distance, filters and quality changes start a different comparison profile.

Fresh Skin wrappers and recycled pages do not establish unchanged pose content. Preserve the current conservative Skin-task demand path. A logical retained result cannot initialize a replacement physical GPU resource.

Preserve scheduling, physics and delayed work

Keep broad terrain/fragment wake bounds and visual-only changes distinct at their actual producer. Avoid whole-queue copying before a budgeted traversal's first yield. Disabling collision, damage, effects, shadows or publication is a sensitivity control, not an equivalent-work optimization.

Qualify allocation and performance evidence

A queue fake retaining synchronous upload input must copy its exact byte window before scratch reuse. Keep byte assertions and separately verify real GPU readback. When moving uploads to creation, validate capture bootstrap and fresh replay as well as live pixels. Removing allocation from one owner does not prove lower whole-Worker allocation, a smaller retained heap, or a solved runtime target.

Select detailed methods and evidence

The tools below read local artifacts and use Node built-ins. They do not launch a browser, acquire a GPU lease, build Engine, or qualify a delivery gate.

Run an entrypoint with --help; Toolbox owns arguments, exit meanings and capture adapters. Use private output paths and retain raw inputs. These summaries establish their stated analytical boundary only.

Keep reusable decisions in this Engine entrypoint; add detailed method and counterexample evidence to the existing topic, and dated results to one scoped case using Contributing. Remove superseded guidance. Preserve raw failures privately and retain useful counterexamples; do not promote one run's numbers, host paths, quality settings or an unimplemented prototype into a universal rule.

When animation times are externally sampled, zero playback speed does not permit skipping pose evaluation. Retain events, normalization and target updates while avoiding unchanged clock writes; verify paused, wrapping and externally edited targets through the same animation owner.

For fixed-input material builds, capture WGSL records and their complete path namespace through the existing Pack source fence, then pass an explicit captureMaterialSourceSnapshot result to the material cooker. Never apply this lifetime to live/default callers. Transport DDC admission requires the product cache's producer checks and an explicit pure, sink-free policy identity; cached dependency topology may order work but cannot admit or skip publication.