Update Project Formats
Know what needs rebuilding when you update Studio and the Unreal plugin.
Back up your project before an upgrade. Install Studio and the plugin from the same release, then rebuild and synchronize your packages. See Update CalmUI.
Most users do not need to edit format numbers. If an update reports a source format problem, use its message to identify the file and required change.
Project configuration
The supported configuration migration adds schemaVersion: 1 to a configuration
that does not declare a version. Terminal users can inspect the change with
calmui migrate --check or calmui migrate --dry-run. Running calmui migrate
backs up the original under .calmui/migration-backups before writing it.
A parsing, backup, or write failure leaves the original source unchanged.
View transitions
Opening/closing transition settings use package-manifest version 2. Studio updates that manifest when you edit those settings. A View without transition settings continues to open and close immediately.
Packages built with transition settings use .cuipack 1.7 or later. Update the
plugin together with Studio before rebuilding them.
Large lists and action data
Fixed-height virtual lists require .cuipack 1.8 or later. Existing ordinary
ui:for lists do not change until you add the virtual-list attributes.
Action data expressions such as { saveId: lastSaveId } require .cuipack 1.9.
An older plugin can reject packages using these expressions. Update Studio and
the plugin together, then rebuild rather than hand-editing a compiled package.
Localization declarations
New source builds reject ui:loc with CUI2133.
Open Languages and expand
Migrate legacy declarations. Supply a confirmed default for every key, then
choose Preview migration. Connected Unreal can supply registered source
texts; absent defaults must be entered explicitly. Nothing is guessed.
Review each file before choosing Apply migration to source. The batch includes unsaved buffers and supports Undo. A stale preview must be regenerated. Non-empty or nested legacy content requires manual migration so it is not erased.
For text passed to components, replace text slots with ordinary props:
<Button label="$loc('GameUI::Confirm', 'Potwierdź')" />Inside Button, use {{ props.label }}. Keep slots for icons and nested content.
Set sourceCulture in calmui.config.json to the language of your defaults;
GameUI uses pl. See Translate Your UI.
Localization declarations require a 1.10-or-newer reader. Current readers still load older packages, including their legacy localization instructions. Update Studio and the plugin together before rebuilding. An incompatible plugin shows Not checked in Languages instead of pretending a translation is missing.
Project UI scaling
New packages use format 1.11. Update Studio and the plugin together before rebuilding. Existing projects keep their previous scaling until you open Settings → UI Scaling and save a project design resolution and mode. No CSS migration is needed. New Studio projects start with proportional fit at 1920 × 1080 and 100%. See Project UI scaling.
Safe areas
Safe-area support does not rewrite your layouts. To use reported display margins, add the safe-area CSS values where padding is needed. A layout without those values keeps its existing placement.