Versioning, compatibility, and upgrades

Mass Forge uses Semantic Versioning 2.0 for VersionName and a monotonically increasing positive integer for the Unreal plugin descriptor's Version. The changelog describes every customer-visible change, and the engine support matrix records the exact Unreal Engine baselines used for release verification.

Compatibility promise

The 0.x line is a beta: a minor release may change an API or authored-data contract when required to reach a stable design. Every known breaking beta change must still be called out in the changelog, include a migration note, and increment the minor version. Patch releases must remain backward compatible and are reserved for fixes, documentation, tests, and additive behavior.

Starting with 1.0.0:

• patch releases preserve public C++ headers, Blueprint node names and pins, reflected type/property names, enum names and values, Primary Asset types, configuration keys, and serialized formats;
• minor releases are backward-compatible and additive;
• major releases may remove or redesign public behavior only with explicit release notes and a migration path;
• a public Blueprint/C++ API scheduled for removal remains deprecated for at least two minor releases or six months, whichever is longer;
• security, platform, or upstream Unreal Engine constraints may require a shorter window, which must be identified prominently in the release notes.

An API is public when it is exported from Source/MassForge/Public, Blueprint-visible, serialized in an authored asset or snapshot, listed in documentation, or returned as a Primary Asset ID. Private implementation details, editor layout, log wording, internal processor composition, and undocumented private headers are not compatibility contracts.

Frozen sample-facing API baseline

Baseline ID: MassForge.SampleAPI.0.2.v1

This is the frozen integration surface for the first Mass Forge showcase projects. A showcase may use only this documented surface, ordinary Unreal Mass/representation APIs, and project-owned adapters. It must not include a private Mass Forge header, address an internal processor directly, depend on an editor widget implementation, or modify plugin source. Additive APIs may join a later baseline; renaming, removing, or behaviorally repurposing an item below requires a new baseline ID, changelog entry, migration note, compatibility-test update, and coordinated sample upgrade.

The baseline covers these authoring contracts:

• Vital, Combat, and Support Attribute Schema assets and stable Mass Forge Attribute ID domain/name identities;
• Mass Forge Instant Effect, Persistent Effect, Ability, Damage Definition, Derived Attribute Profile, Regeneration Profile, Attribute Snapshot Migration, Ability Condition, Ability Targeting Policy, Ability Execution Plan, and Effect Magnitude Calculation assets;
• Mass Forge Attributes, Gameplay Tags, Abilities, Persistent Effects, Derived Attributes, Regeneration, and High Volume Effects Entity Config traits; and
• the Entity Config wizard's Attributes Only and Combat Ready presets as optional setup accelerators rather than mandatory schemas.

The baseline covers these Blueprint/runtime workflows:

• resolve represented Actors to generation-checked entity handles; read/change attributes; capture, migrate, and direct/queued restore attribute or complete entity state;
• add/remove/query counted Gameplay Tags; direct/queued apply Instant and Persistent Effects; query/remove Persistent Effect instances;
• direct/queued grant, revoke, check, activate, cancel, and interrupt Abilities; observe cast/channel lifecycles; submit and poll AI activation tickets;
• choose targets through represented-Actor, radius, segment-trace, collision-hit, or custom-provider adapters;
• dispatch Entity-to-Entity, Actor-to-Entity, Entity-to-Actor, and Actor-to-Actor effects; apply direct/queued Damage Definitions and receive typed completion/death results;
• inspect actorless or represented entity state, record bounded gameplay history and project-supplied mind breadcrumbs, run Project Health, and retrieve memory/scheduler diagnostics; and
• evaluate the included networking source only as an experimental, unsupported integration surface for the initial release; it is not used by the five public examples or promised by the advertised compatibility matrix.

Networking types remain reflected so existing evaluation projects can compile, but they are outside the initial-release support and sample promise; no multiplayer example is included in the public launcher. A later release that promotes multiplayer to supported status must publish a dedicated compatibility baseline, example, bandwidth scope, topology matrix, and migration policy first.

The compatibility automation reflects the customer-critical functions, properties, structs, enum ordinals, serialization versions, Primary Asset identities, and required documentation clauses behind this baseline. The repository verifier separately guards the full public Blueprint surface, node metadata, bounded runtime contracts, package payload, and all advertised engine/network matrices. Passing those gates is required before a change can continue to call itself MassForge.SampleAPI.0.2.v1.

Protected identifiers

Do not rename or reuse these after release without the versioning process:

• schema attribute domain/name pairs and their stable slots;
• AbilityId, instant/persistent EffectId, DamageId, targeting PolicyId, and MigrationId values;
• Mass Forge Primary Asset type names;
• Blueprint function, pin, struct, property, enum value, config section, and config property names;
• snapshot FormatVersion, SchemaVersion, and stored attribute IDs.

New enum values belong at the end. Existing enum values must keep their names and numeric ordinals. Snapshot and migration result ordinals are explicitly assigned in source; the compatibility automation test pins the broader customer-critical baseline.

Upgrade checklist

1. Upgrade on a source-control branch and retain a restorable project/save backup.
2. Read the complete changelog range and ENGINE_VERSION_SUPPORT.md; update Unreal Engine separately when practical so failures have one cause.
3. Compile every C++ target and load/resave all affected Blueprints to surface deprecated or missing nodes.
4. Open Mass Forge Project Health, run a fresh scan, and resolve every new error before changing schema settings or assets.
5. Compare project configuration with any new defaults. Existing explicit settings remain authoritative unless the release notes say otherwise.
6. Validate representative abilities, effects, damage definitions, targeting policies, and entity configs through Unreal Data Validation and Project Health.
7. Test an unchanged save from every supported SchemaVersion, migrate it through an explicit complete chain, restore it, and verify the values before shipping.
8. Exercise direct and queued paths, actorless entities, represented Actors, entity destruction/reuse, world travel, pause/time dilation, and the project's highest entity-count tier.
9. Maintainers working from the complete Mass Forge source checkout run the project's own functional tests plus the repository-only Scripts/Verify-MassForge.ps1 on every engine/platform combination the project ships.
10. Copy and archive the Project Health support report with the release evidence. Roll back the plugin and project together if a release gate fails.

0.1.x to 0.2.0 Blueprint migration

Get Mass Forge Entity From Actor now returns Mass Forge Entity Resolve Result execution pins instead of a boolean. Move the former true path to Success and handle or deliberately ignore the specific invalid-world, invalid-Actor, different-world, unavailable-representation, unrepresented, and stale-representation pins. The output handle is cleared on every failure.

Register Mass Forge Inspection Provider and Unregister Mass Forge Inspection Provider now return Mass Forge Inspection Provider Result execution pins. Move the former true path to Success. Registration now reports Already Registered explicitly rather than treating a duplicate request as a second success; unregistration reports Not Registered when appropriate. Invalid providers and provider-capacity exhaustion are also distinct outcomes.

The Mass Forge Effect Receiver interface callback remains implementable but is no longer exposed as a direct Blueprint call. Route effects through the Entity/Actor dispatch nodes instead; their dispatch receipt identifies the chosen receiver route and reports rejection without allowing a direct boolean-only call to bypass validation.

The schema Find Entry By Name and Find Entry By Slot helpers are now pure query nodes. Existing value wiring is unchanged; remove obsolete execution-pin wiring if an early 0.1 Blueprint used these helpers directly.

Attribute schema and saved snapshots

Moving a schema entry to a different slot without changing its domain/name identity does not reinterpret a snapshot, but deployed slot layouts should still remain stable because live fragment storage uses them. Renaming, moving to another domain, or removing an attribute requires a higher project SnapshotSchemaVersion and a validated Mass Forge Attribute Snapshot Migration asset. Keep OldestSupportedSnapshotSchemaVersion at the oldest save generation the release promises to load and test a complete path from every integer version in that window. See PERSISTENCE_GUIDE.md and SCHEMA_EDITOR_GUIDE.md.

Changing a value's unit or meaning is a project data conversion, not an identity rename. Perform that conversion in the surrounding SaveGame upgrade before Mass Forge restore, then verify current-schema clamping and derived attributes.

Effects, damage, abilities, and targeting policies

Mass Forge durable entity-state format 4 serializes grant IDs, cooldown and charge-recovery remainder, exact active Persistent Effects, and one active cast/channel. Formats 1–3 remain supported under their documented section boundaries. Projects own the surrounding USaveGame, stable population records, entity recreation, external lifecycle-target relationship resolution, and any game-specific conversion. Never manually bump the Mass Forge outer FormatVersion; migrate only the nested attribute snapshot through Mass Forge migration assets and perform other semantic conversions in the project's own save version.

An active Ability lifecycle is guarded by the Ability's stable ID, soft asset path, execution/timing fields, and Save Compatibility Version. Increment that authored version when an old active phase must fail instead of continuing under new behavior. Active Persistent Effects similarly require their soft definition paths and stable Effect IDs to resolve and agree. Preserve moved assets through Unreal redirectors, or ship an explicit project save upgrade; silently dropping unresolved temporal state is not a compatible migration.

Authored Data Assets are Unreal assets: retain their object paths when possible, use Unreal redirectors or Core Redirects for intentional class/property moves, and keep their stable Mass Forge IDs unchanged. When an ID must change, update every direct reference and every project-owned external/save reference as one migration, then run Project Health and Reference Viewer before deleting the old identity. Duplicate IDs are invalid even if object paths differ.

Behavioral balance changes do not require a plugin major version, but they do require project release notes and regression tests when they change damage totals, costs, cooldowns, stacking, tag gates, targeting, or lifecycle timing.

Automated compatibility gate

MassForge.Editor.Compatibility.PublicApiBaseline fails when the descriptor stops using semantic-version syntax or when a protected customer-critical function, recursively required SaveGame property, enum ordinal, snapshot format, or Primary Asset ID contract changes. World automation additionally performs tagged SaveGame serialization/deserialization and runtime migration/restore scenarios for durable formats 1–4. A deliberate breaking release must update the implementation, compatibility baseline, released-format fixtures, changelog, this guide, and the plugin major/minor version in the same reviewed change; changing the test alone is not a migration.