ParadoxCode for VS Code

Project overview · 简体中文入口

This guide owns installation, editor workflows, and troubleshooting. Settings, defaults, commands, and agent tools come from the generated extension reference.

Setup

1. Install ParadoxCode from Visual Studio Marketplace.
2. Open and trust the Mod folder, then open an EU4 script or localisation file.
3. The extension downloads the matching server release, verifies its checksum, and starts it.
4. If discovery misses your game installation, use the installation picker in the ParadoxCode walkthrough. Select your EU4 installation, rather than a text-only corpus copy.

The extension's Get Started walkthrough supplies the current command labels and guided setup. For an offline install, download the VSIX and a matching native server archive from GitHub Releases, extract the server, and set paradoxcode.serverPath to its executable. Supported targets and archive names are defined in server-distribution.json.

Workspace and dependencies

Open the directory containing the Mod's common, events, or other game folders. Use the dependency commands from the Command Palette to add, remove, or reorder dependency roots. The ordered paradoxcode.dependencies array may select live source roots or persistent indexes. When an explicitly selected dependency index becomes stale, rebuild it or remove its index field to resume live scanning. Unsaved editor buffers participate in analysis.

Vanilla discovery and indexing are guided by the walkthrough. The paradoxcode.vanilla.* settings control whether local Vanilla data is discovered or an existing cache is required. Configured exclusions prune generated files before indexing. Use the reference for exact properties and defaults.

Diagnostics and language features

The diagnostic guide explains stable codes and remedies. Diagnostic ignore codes and severity overrides are extension settings; unknown codes are rejected. The workspace-wide diagnostics setting controls publication for closed files, while validation commands can still compute a complete workspace summary.

Localisation is indexed for lookup/navigation and receives transparent-encoding safety feedback; it does not publish server diagnostics or completion items. Script rename is restricted to writable Mod sources, and formatting refuses malformed input it cannot safely preserve.

Mission Preview

Open a mission file under common/missions or missions, then choose Open Mission Tree Preview to the Side. The preview supports live refresh, source navigation, texture-backed nodes, keyboard navigation, and zoom controls. The view keeps its pan and zoom across refreshes, fitting only when a different mission file is opened. The search box finds missions by localised title or id; opening a result jumps to its source definition and centers the canvas on the node. A Series panel mirrors the canvas layout column by column (Slot N blocks wrapping left to right) with a checkbox per mission series: hidden series keep their canvas position but drop out of the canvas, dependency arrows, search result highlighting, and the diagnostic summary, and each document remembers its hidden set for the session.

Transparent Localisation (Chinese)

Mods running the EU4dll double-byte patch store localisation as escape-tripled bytes. ParadoxCode ships the transcoder and edits those files as readable Chinese through the pdcloc:// view:

• Entry is path-scoped but content-gated: an eligible file — any localisation/**/*.yml or a script file matching paradoxcode.localisation.transparentScriptGlobs (**/*.txt by default) — takes over the raw tab and opens in the decoded view only when it actually participates in transcoding: an escaped or damaged form, or plain text whose quoted CJK a save would encode. Transcode fixed points (no escape markers, no quoted CJK) stay on their ordinary file:// view so search, diff, git, and timeline keep working on them; a fixed point that later grows quoted CJK is promoted to the decoded view automatically. Files rendered inside a diff editor are never taken over. paradoxcode.localisation.autoOpen picks the policy: needsTranscode (this behaviour, the default), always (the legacy takeover of every eligible file whatever its bytes look like), or off. Plain readable files pass through unchanged; their quoted CJK is escape-encoded on the next save (announced by an informational LocalisationWillTranscodeOnSave hint).
• Saving writes the scoped form: escape triples only inside quoted strings, comments and code as readable UTF-8 — the game-side transcoder reads the strings exactly as with whole-file encoding. Partially escaped files self-heal on save. Saving is refused (never double-encoded) when a string already contains escape markers, or holds code points the ecosystem cannot round-trip.
• Stray escape markers outside every quoted string are damage: the file is shown as-is with a LocalisationMixedEncoding error anchored at the marker; fix it by hand.
• While a decoded view is active, the status bar shows EU4 decoded view; click it to open the raw transcoded file, and use the editor-title eye to peek at the raw bytes momentarily.
• Turn paradoxcode.localisation.transparentEncoding off to disable everything automatic (no pdcloc:// provider, no redirection, no save-time encoding): the manual Encode File (EU4dll Escape Form) and Decode File (Readable Text) commands become available instead, each a one-shot disk rewrite with a .pre-transcode.bak backup written next to the file.

Agent tools

The running language server supplies read-only workspace queries and in-memory draft validation. Use the generated tool reference for names, input schemas, and prompt references. If tools are absent after extension activation, run Developer: Reload Window once. External clients use the MCP entry point.

Configuration

Use VS Code Settings under paradoxcode, or workspace settings.json for shared project choices. REFERENCE.md is generated from the same manifest VS Code reads, including localized descriptions, defaults, enums, and array/object constraints. This reference describes extension defaults; editor-neutral initialization behavior belongs to the server integration guide.

Troubleshooting

• Server missing or download failed: inspect the ParadoxCode output channel, installation policy, selected executable, and whether a matching release exists. A source checkout may be newer than the published release; point it at your locally built server.
• No language features: trust the workspace, open a recognized game file, and check the active language mode and server output. The extension's language/activation registrations live in package.json.
• Missing symbols or textures: check the selected Mod, dependency order, game installation, and Vanilla policy. A text-only corpus does not contain the game's image assets.
• Settings changed: many server settings apply live; executable/installation changes require restarting the server. Reload it from the Command Palette when diagnosing configuration changes.
• Transcoding refused: consult the diagnostic guide and repair the original content before retrying.

For a bug, use the issue template with a minimal repository-owned reproduction. Keep licensed game content and machine paths private. Extension development and validation are described in CONTRIBUTING.md.