Known issues and current limitations

This page describes the boundaries of the current 0.2.0 beta. Confirmed defects should be added with a tracking reference, workaround, affected versions, and removal version; none are currently recorded as unresolved release defects.

Current limitations

• Platform support: only Win64 is currently advertised and verified. Other targets have not completed the release matrix.
• Engine support: the verified source-compatible lines are Unreal Engine 5.6, 5.7, and 5.8. See ENGINE_VERSION_SUPPORT.md for exact patch baselines.
• Networking: multiplayer is outside the supported initial-release scope and no multiplayer example ships in the public launcher. Networking source remains available for evaluation, but its integration surface, performance, bandwidth behavior, prediction, hostile-input hardening, and upgrade compatibility are not advertised release promises.
• Samples: the five-map customer launcher, skeletal/VAT horde twins, original character pack, and automated/package gates pass on the advertised UE 5.6-5.8 matrix. Broader gameplay breadth, long-session soak, accessibility, and Marketplace promotional media remain outside the verified technical distribution gate.
• Performance publication: reference-hardware 10k/100k/1M simulation throughput plus a packaged 420-enemy VAT-horde frame/GPU/draw/primitive snapshot are published. The numbers are scoped separately. Long-session representative worst-frame capture, broader renderer settings/hardware, and worker-thread attribution remain open; no one-million-visible-enemies claim is made.
• Editor language: user-facing editor text is localization-ready through text macros where implemented, but the full localization and accessibility review remains open.
• CI infrastructure: the repository contains a valid three-engine GitLab pipeline, but the private project currently has no matching Windows Unreal Engine runners. Local verification remains authoritative until runners are attached.
• Direct calls during Mass processing: direct mutation/effect/damage/ability calls intentionally reject unsafe access. Use the matching queued operation from callbacks or code that may overlap Mass processing.

FAQ

Does Mass Forge replace Unreal Gameplay Ability System?

No. Mass Forge is a Mass-native attributes, effects, damage, tags, and abilities framework for actorless or represented entities. It does not require an Ability System Component or one UObject per entity. A project may still use GAS for players and Mass Forge for crowds, connecting them through the Actor/Entity effect and damage adapters.

Are Health, Mana, Armor, or other starter names mandatory?

No. The wizard's Vital, Combat, and Support entries are editable examples. Runtime behavior uses project-authored stable Attribute IDs, definitions, policies, and formulas. Rename or move a deployed attribute with an explicit snapshot migration after data has shipped.

Does every Mass entity need an Actor?

No. Attributes, effects, abilities, targeting, networking identity, persistence, and inspection work with generation-checked Mass handles. Actor adapters are optional integration paths for represented entities and ordinary player/gameplay Actors.

When should a Blueprint use the direct node or the queued node?

Use a direct node only when the entity manager is known to be idle. Use the matching queued node from callbacks, asynchronous systems, or code that may overlap Mass processing. A successful queued submission returns a positive request ID and exactly one completion unless its world tears down.

Does Mass Forge promise one million visible animated enemies?

No. The published 10k/100k/1M results measure actorless Mass Forge simulation paths and report their exact scope. Representation, rendering, navigation, collision, and VAT costs are separate. Any visible-crowd claim requires a packaged-game profile on representative hardware.

What survives save/load or travel?

Durable entity-state format 4 can preserve attributes, counted tags, grants, cooldowns, charge recovery, regeneration remainder, active Persistent Effects, and one cast/channel under documented remapping rules. Session references and world-local handles never enter SaveGame data.

How can a project display an entity's “mind”?

Register a bounded world-level Entity Inspection Provider and emit project-owned sections such as intent, target, task, or faction. The runtime snapshot and editor Entity Inspector display them without storing a UObject on every entity or making debug data simulation authority.

Troubleshooting flow

1. Run Mass Forge Project Health and resolve every error before testing runtime behavior.
2. Confirm the Actor resolves successfully or the Mass handle still has the exact index/serial generation and required traits.
3. Read the returned typed result and its nested result fields; use ERROR_AND_RESULT_CODES.md for the specific cause and remedy.
4. If the result is Mass Is Processing, switch the call to its bounded queued counterpart and correlate the positive request ID with the terminal completion event.
5. For save/load, retain the received format/schema versions, run the complete migration chain on a temporary copy, recreate population relationships, and restore only after all validation succeeds.
6. If the issue persists, reproduce it in the smallest project possible, run Copy Support Report, review it for private data, and attach the fields requested by SUPPORT_REQUEST_TEMPLATE.md.

Reporting a new defect

Run Project Health, copy the support report, and use SUPPORT_REQUEST_TEMPLATE.md. Do not paste passwords, access tokens, private source, complete saved games, or unrelated logs. A report that reproduces against an unmodified Mass Forge release is the fastest path to a regression test and fix.