Shared tags vs addon-private tags

✅ Source verified 🏷 Data-design pattern

Political World exposes two different kingdom-tag concepts.

They exist for different jobs.

Shared kingdom tags

Public methods include:

GetKingdomTags(...)
HasKingdomTag(...)
AddKingdomTag(...)
RemoveKingdomTag(...)

These tags are intentionally shared/global.

The source keeps their historical storage key:

ukiol_api_kingdom_tags

for compatibility.

Use shared tags only when multiple mods intentionally agree on the meaning of a tag.

Example concept:

trade_embargoed

could be useful as a shared convention if several addons document and honor the same meaning.

Addon-private kingdom tags

Public methods include:

GetAddonKingdomTags(...)
HasAddonKingdomTag(...)
AddAddonKingdomTag(...)
RemoveAddonKingdomTag(...)

These require a registered addon and are stored inside that addon’s collision-safe data namespace.

Internally, the inspected source stores the private tag list under local key:

__private_tags

The actual final save key is still namespaced through the addon-data system.

Private tag format

The current implementation serializes the local tag list as a pipe-delimited string:

tag_a|tag_b|tag_c

A private local tag containing | is rejected by the add path.

This serialization format is an internal implementation detail. Addons should use the public methods instead of reading the __private_tags string directly.

Decision rule

Ask:

Does another independent mod need to understand this tag?

If no:

use addon-private tag

If yes, intentionally:

use shared tag with a documented cross-mod convention

Examples

Private:

dragon_dynasty
has_completed_my_quest
internal_reform_stage_2

Shared only by agreement:

sanctioned
neutral_trade_zone
protected_state

The names above are examples, not built-in Political World tag IDs.

Why private should be the default

Private storage gives:

• collision protection;
• clear ownership;
• easier cleanup;
• safer refactoring;
• less accidental coupling between mods.

Shared state creates a dependency even if no DLL/reference dependency exists.

A string understood by two mods is already a protocol.

Migration note

The shared/global tag key intentionally retains a legacy ukiol_* identifier.

Do not rename a persistent key merely to match current branding.

See Stable IDs are data, not branding.

Runtime persistence — WBML-0001

Both tag families were included in a full-process save/load probe.

Verified environment:

WorldBox 0.51.2 build 719
NeoModLoader 1.2.0.1
PoliticalWorldAPI 1.14.0
WBML 0.0.1

After saving, fully closing WorldBox, starting a new process and loading the same save:

addon-private kingdom tag ... PASS
shared kingdom tag .......... PASS

This verifies persistence for the tested environment.

It does not yet verify isolation between two different world saves. That is the purpose of WBML-0002.