Editing and Localization

Editing and localization

Writers operate on saved mod files. Save editor buffers before applying disk changes. Preview is the default; use explicit write mode after reviewing destinations and content. Vanilla and dependency mods remain reference inputs.

Review a token-bound write

$createArgs = @("create", "event", "mymod.1", "--prefix", "mymod", "--json")
$preview = pxtk @createArgs | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) { throw "Preview failed." }
$preview.data.files | Format-List file, action, content, contentTruncated
# Review before applying the same options and token.
pxtk @createArgs --write --expect $preview.data.previewToken

Application recomputes the proposal. A different option or changed source can invalidate its token. Files are staged first, then each updated file is replaced atomically. New multi-file writers recheck inputs between and after file commits. A batch is not a filesystem transaction; a failure reports completed files. Do not treat a partial write as a completed change.

Scaffolds and conservative formatting

pxtk create --json
pxtk create event mymod.1 --prefix mymod --json
pxtk format events/mymod_events.txt --check --json
pxtk format events/mymod_events.txt --json

create lists kinds when no positional kind is supplied. Use its positional kind, not --kind. Templates come from the selected profile. CK3 and Victoria 3 expose their existing scaffolds; EU5 currently exposes scripted effects and triggers under its selected stage root. Use --stage only for a profile-supported stage. Create rejects duplicate mod definitions, localization keys and mismatched headers. Script and localization outputs require UTF-8 BOM.

format changes leading indentation in script and GUI files. It does not reserialize statements or format localization. --check reports proposed changes without writing.

Read and update localization

pxtk loc get mymod_1_t --json
pxtk loc set mymod_1_t --value "A new title" --json
pxtk loc check --language german --json

loc set preserves comments, entry versions, sibling entries and line endings. Existing mod entries keep their owned location. New vanilla overrides go in a replace layout; new keys follow configured destinations and meaningful siblings. Use --file <mod-relative-file> to resolve ambiguous placement. Generated localization requires its source workflow. Language coverage is based on indexed references, so dynamic keys can remain unknown.

Translation synchronization

pxtk loc sync --source-language english --language german --json
pxtk loc sync --source-language english --language german --file localization/english/mymod_l_english.yml --json

Sync adds missing target keys as blank entries with source-language comments. It does not translate text. It mirrors source language and stage paths and preserves target translations already present in any target-language mod file. Source and target languages must be explicit and different. Duplicate keys, malformed localization and generated source/destination files are refused. Apply with --write --expect <previewToken> from the same reviewed request.

MCP uses pxtk_loc with {"action":"sync","sourceLanguage":"english","language":"german"}, then the same fields plus write and expect.

Symbol rename

Rename uses the shared LSP's prepare and rename policy and can start from a supported declaration or indexed reference, including a localization key declaration:

pxtk rename --file common/scripted_effects/mymod.txt --line 1 --column 1 --to mymod_new_effect --json
pxtk rename --file localization/english/mymod_l_english.yml --line 2 --column 2 --to mymod_new_title --json

Input line and column are 1-based UTF-16 coordinates. Count UTF-16 units, so an astral Unicode character occupies two columns. Returned edits use zero-based UTF-16 offsets into the original decoded text without its BOM: {start,end,newText}, with an exclusive end. These are different coordinate systems. Definition-edit requests use operation names, not cursor positions.

The provider refuses ambiguous symbol types, same-kind name collisions, foreign definitions, read-only destinations and symbol kinds with unsupported reference forms. GUI, graphics and nested kinds can be unavailable. Every edit destination must belong to the editable mod; the adapter does not apply an allowed subset after a refusal. Dynamic and unindexed references can be missed. Inspect coverage and validate after applying.

Apply the same request with --write --expect <previewToken>. MCP pxtk_rename accepts {file,line,column,to} and optional write/expect. Indexed mod/dependency content and configuration bind the token. Vanilla uses installation path and detected version; concurrent manual vanilla changes require a fresh preview. Script and localization outputs normalize to UTF-8 with BOM and preserve unrelated text and line endings.

Precise definition editing

Create edits.json as a UTF-8 JSON array of upstream definition operations:

[
  {
    "op": "setProperties",
    "name": "mymod_trait",
    "properties": [
      { "key": "martial", "value": "2" },
      { "key": "obsolete_property", "value": null }
    ]
  },
  { "op": "upsertBlock", "name": "mymod_other_trait", "text": "mymod_other_trait = { martial = 1 }" }
]

pxtk edit --file common/traits/mymod.txt --operations edits.json --json

Values are raw script source strings; null removes a property. upsertBlock supplies a definition name and full block text. The shared writer produces surgical offsets against the original valid script. Neighboring source and comments remain in place. Any refused operation, overlapping edit or invalid resulting script rejects the batch. Applying requires --write --expect <previewToken>.

MCP pxtk_edit accepts {file,edits:[...]} directly. CLI JSON argument files are limited to 4 MiB. Returned offsets use the zero-based BOM-free convention described above.

Image preparation

pxtk image inspect art/icon.png --json
pxtk image convert art/icon.png --to dds --dds auto --output gfx/interface/icon.dds --json
pxtk image convert art --to dds --output gfx/interface/prepared --json
pxtk image convert art/icon.png --to png --width 128 --height 128 --fit contain --output prepared/icon.png --json
pxtk image convert art/icon.png --to jpeg --background "#ffffff" --output prepared/icon.jpg --json

Inputs support DDS, TGA, PNG, JPEG and WebP; outputs support DDS, PNG, JPEG and WebP. Batch folders retain subfolders and report unsupported inputs. Outputs must be new files inside the mod and never replace existing files. Input files remain unchanged. Apply conversions with --write after preview review, using --expect to bind the preview.

Resize modes are contain (default padding), cover (crop), inside (fit within bounds) and fill (stretch). Transparent JPEG inputs require an explicit background. DDS auto chooses BC3 for alpha and BC1 otherwise; BGRA8 is also available. BC1 refuses transparent pixels. Outputs have one mip level, with no generated or copied mip chain. Use another converter for assets that require complete mipmaps. EXIF orientation is applied and metadata is not copied. Cubemaps, arrays, volumes and animated inputs are unsupported.