Text tools¶

Plain script, checked once in the game

These effects need no native code; they also work on text already in a save when CAPIE is missing. They are generated by sdk/capie-script-sdk/tools/gen_sdk.py and checked offline. The SDK's demo mod ran them in the game on CAPIE 1.1; the other in-game checks are open.

HOI4 script has no string type and cannot split or compare text. The SDK works around that with character codes: a field arrives as up to 32 numbers, the SDK keeps them in temporary variables (the work buffer), and scripted localisation turns stored codes back into letters.

The work buffer¶

Temporary variable	Meaning
`capie_len`	number of characters, 0 to 32
`capie_c0` .. `capie_c31`	character codes (alphabet)

capie_v1_field_load fills it from field capie_field of the current Apply command and checks what CAPIE sent. capie_v1_text_load fills it from a text slot.

Effects¶

Effect	Inputs	Result
`capie_v1_begin`	`capie_open_epoch`, `capie_min_api` (default 2)	`capie_err` 0 or 10..16
`capie_v1_field_load`	`capie_field` 1..4	work buffer; `capie_err` 21..26 or 35
`capie_v1_text_trim`	work buffer	leading and trailing spaces removed; 21 when nothing is left
`capie_v1_text_validate`	`capie_min_len` (default 1), `capie_max_len` (default 32)	`capie_err` 31..34
`capie_v1_text_store`	`capie_slot` 1..4	work buffer copied into the slot of ROOT
`capie_v1_text_load`	`capie_slot`	slot copied into the work buffer
`capie_v1_text_equals_slot`	`capie_slot`	`capie_eq` = 1 when the buffer equals the slot
`capie_v1_text_clear`	`capie_slot`	slot emptied
`capie_v1_report`	`capie_err`, `capie_err_field`, `capie_err_at`	stored on ROOT for the message line

Trim, validation, storing and the setters do nothing while capie_err is not 0.

Text slots¶

Each country has four slots: arrays capie_v1_txt1 .. capie_v1_txt4 with lengths capie_v1_txt<n>_len. The localisation key CAPIE_V1_TXT<n> draws slot n of ROOT, so you can nest it in your own text:

 MYMOD_MOTTO_LINE:0 "Motto: $CAPIE_V1_TXT3$"

Slots are shared by every mod that uses the SDK on that country. The setters use slots 1 and 2 as scratch space; keep text you want to show later in slots 3 and 4. If two mods both keep text in the same slot, the later Apply wins. Per-mod slots would need per-mod tables and are not part of API level 2.

Setters¶

The state, character and party setters turn slot text into a literal through meta_effect, the way Rename Anything sets names. The country setter copies the codes into the name layer. Call it in the scope of the object you rename, after your permission check.

Effect	Scope	Text
`capie_v1_set_country_name`	the country	slot 1 name, slot 2 adjective, written as the country name layer; flag and colour stay
`capie_v1_clear_country_name`	the country	removes the name layer; the country shows its cosmetic tag or base name again
`capie_v1_set_state_name`	the state	slot 1
`capie_v1_set_character_name`	the character	slot 1
`capie_v1_set_party_name_democratic`, `_communism`, `_fascism`, `_neutrality`	the country	slot 1 short name, slot 2 long name

The country name layer is drawn by capie_core.dll 1.2 or later. Without it the game shows the cosmetic tag or base name. The SDK has no faction setter; faction names use the faction name layer of API level 5.

Error codes¶

`capie_err`	Meaning
10	CAPIE missing: no `capie_cap` in this command
11	CAPIE older than `capie_min_api`
12	stale opening: the editor changed, or this opening was already applied
13	editor limit of the session reached
14	editor built wrong (a mod author issue)
16	multiplayer: not every human player confirmed the same CAPIE build
20	not allowed (your permission check)
21..26	field error 1..6 from CAPIE (empty, too long, invalid, control, reserved, unsupported)
31	shorter than `capie_min_len`
32	longer than `capie_max_len`
33	starts or ends with a space
34	two spaces in a row
35	damaged payload (length or code out of range, a fraction, a code past the length)

[ROOT.CAPIE_V1_LAST_ERROR] shows the message of the last capie_v1_report, in English or Polish, with the field number and position where they apply. The other game languages use the English text.