@px-lsp/server 0.1.0

package/src/games/ck3/ambientScopes.ts

@@ -0,0 +1,273 @@
+/**
+ * Ambient (engine-provided) saved scopes per definition kind (update plan v1.1
+ * §B3). These names are referenced via `scope:x` but are never `save_scope_as`'d
+ * in script — the engine binds them — so a save-site index can't explain them.
+ *
+ * SOURCE: hand-curated from the game's `_*.info` files (2026-07 scope audit:
+ * every folder's documented `scope:<name>` lines were swept and typed). Scope
+ * type names are the canonical ones from event_scopes.log. Some ambient scopes
+ * only exist in specific blocks of the kind; per AD-5 they are offered for the
+ * whole file (rank/annotate, never hide) with the block noted in the doc.
+ */
+import type { AmbientScope } from "../../schema/types";
+
+const CHAR = "character";
+
+function s(name: string, type: string, doc: string): AmbientScope {
+  return { name, type, doc };
+}
+
+/** Ambient scopes keyed by schema kind. */
+export const AMBIENT_SCOPES: Record<string, AmbientScope[]> = {
+  // common/character_interactions/_character_interactions.info
+  character_interaction: [
+    s("actor", CHAR, "The character sending the interaction (the initiator)."),
+    s("recipient", CHAR, "The character receiving the interaction."),
+    s(
+      "secondary_actor",
+      CHAR,
+      "Present when the interaction declares a secondary actor (e.g. marriage) or a redirect saves one."
+    ),
+    s(
+      "secondary_recipient",
+      CHAR,
+      "As secondary_actor, for the recipient side (e.g. the character being married off)."
+    ),
+    s(
+      "intermediary",
+      CHAR,
+      "The intermediary who forwards the interaction, when one is used. Set/replaced via redirect."
+    ),
+  ],
+
+  // common/activities/activity_types/_activity_type.info
+  activity_type: [
+    s("activity", "activity", "The activity (is_valid, on_* effect blocks, phases…)."),
+    s("host", CHAR, "Host of the activity."),
+    s(
+      "special_option",
+      "flag",
+      "Flag of the selected special option; unset when the activity has no special option category."
+    ),
+    s("province", "province", "Phase blocks: the location the phase is at / being evaluated in."),
+  ],
+  // common/activities/guest_invite_rules/_invite_rules.info (root = host character)
+  guest_invite_rule: [
+    s(
+      "special_option",
+      "flag",
+      "Flag of the selected special option; unset when the activity has no special option category."
+    ),
+  ],
+  // common/activities/intents/_intents.info
+  activity_intent: [
+    s("target", CHAR, "The target of the intent."),
+    s("activity", "activity", "The activity the intent applies to."),
+    s("special_option", "flag", "Flag of the selected special option."),
+  ],
+  // common/activities/pulse_actions/_pulse_actions.info
+  activity_pulse_action: [
+    s("activity", "activity", "The activity."),
+    s("host", CHAR, "Host of the activity."),
+    s("province", "province", "Current activity location."),
+    s("first", CHAR, "First saved character, shown in the pulse-action entry."),
+    s("second", CHAR, "Second saved character, shown in the pulse-action entry."),
+  ],
+  // common/activities/activity_locales/_activity_locales.info
+  activity_locale: [s("activity", "activity", "The activity."), s("host", CHAR, "Host of the activity.")],
+
+  // common/schemes/scheme_types/_schemes.info
+  scheme_type: [
+    s("scheme", "scheme", "The scheme itself."),
+    s(
+      "owner",
+      CHAR,
+      "The scheme owner (same as scheme_owner, valid in an unbroken chain from the scheme scope)."
+    ),
+    s(
+      "target",
+      CHAR,
+      "Whatever the scheme targets — a character for character-targeted schemes (title/culture/faith schemes target those types)."
+    ),
+    s(
+      "target_title",
+      "landed_title",
+      "The targeted title, when the scheme targets a title (otherwise unset)."
+    ),
+    s("agent", CHAR, "An agent in the scheme (on_agent_exposed and similar per-agent effects)."),
+  ],
+  // common/schemes/agent_types/_agent_types.info
+  scheme_agent_type: [
+    s("owner", CHAR, "The owner of the scheme."),
+    s("scheme", "scheme", "The scheme."),
+    s("target", CHAR, "The target of the scheme."),
+  ],
+  // common/schemes/pulse_actions/_pulse_actions.info
+  scheme_pulse_action: [
+    s("activity", "scheme", "The scheme (the docs reuse the activity slot name)."),
+    s("owner", CHAR, "Owner of the scheme."),
+    s("first", CHAR, "First saved character, shown in the pulse-action entry."),
+    s("second", CHAR, "Second saved character, shown in the pulse-action entry."),
+  ],
+
+  // common/secret_types/_secret_types.info (root = the secret)
+  secret: [
+    s("secret_owner", CHAR, "The character the secret is about."),
+    s("secret_target", CHAR, "Optional character related to the secret (e.g. the lover in a lover secret)."),
+    s(
+      "target",
+      CHAR,
+      "is_shunned/is_criminal: the character checking whether they view the secret as shunned/criminal."
+    ),
+    s("discoverer", CHAR, "on_discover: the character who discovered the secret."),
+    s("secret_exposer", CHAR, "on_expose: the character who exposed the secret."),
+  ],
+
+  // common/story_cycles/_story_cycles.info (root = the story)
+  story_cycle: [s("story", "story", "The story cycle (same as root in its effect blocks).")],
+
+  // common/situation/situations/_situations.info
+  situation: [
+    s("situation", "situation", "The situation."),
+    s("situation_sub_region", "situation_sub_region", "The situation sub-region of the current block/phase."),
+    s(
+      "situation_participant_group",
+      "situation_participant_group",
+      "The participant group (participant blocks)."
+    ),
+  ],
+
+  // common/casus_belli_types/_casus_belli.info
+  casus_belli: [
+    s("attacker", CHAR, "The attacker in the war."),
+    s("defender", CHAR, "The defender in the war."),
+    s("claimant", CHAR, "The claimant, for claim CBs."),
+    s("target", "landed_title", "The target title, when the CB has one."),
+  ],
+
+  // common/council_tasks/_council_tasks.info
+  council_task: [
+    s("councillor", CHAR, "The councillor performing the task."),
+    s("councillor_liege", CHAR, "The councillor's liege."),
+    s("county", "landed_title", "County tasks: the county being worked."),
+    s("province", "province", "Province tasks: the province being worked."),
+    s("target_character", CHAR, "Character-targeted tasks: the target."),
+  ],
+
+  // common/buildings/_buildings.info (root = province)
+  building: [s("holder", CHAR, "The holder of the province the building is in.")],
+
+  // common/legends/legend_types/_legends.info
+  legend_type: [
+    s("legend", "legend", "The legend."),
+    s("creator", CHAR, "The creator of the legend."),
+    s("protagonist", CHAR, "The protagonist of the legend."),
+  ],
+
+  // common/epidemics/_epidemics.info
+  epidemic: [
+    s("epidemic", "epidemic", "The epidemic."),
+    s("epidemic_type", "epidemic_type", "The epidemic's type."),
+  ],
+
+  // common/inspirations/_inspirations.info (root = inspiration)
+  inspiration: [
+    s("inspiration", "inspiration", "The inspiration."),
+    s("inspiration_owner", CHAR, "The character who has the inspiration."),
+    s("inspiration_sponsor", CHAR, "The sponsoring character, once sponsored."),
+  ],
+
+  // common/travel/travel_options/_travel_options.info (root = travel owner / plan)
+  travel_option: [s("owner", CHAR, "The travel plan owner.")],
+  // common/travel/point_of_interest_types/_travel_point_of_interest_types.info
+  point_of_interest: [s("province", "province", "The point-of-interest province.")],
+
+  // common/court_positions/types/_court_positions.info (root = character)
+  court_position: [
+    s("liege", CHAR, "The court owner employing the position."),
+    s("employee", CHAR, "The character employed in the position."),
+  ],
+  court_position_task: [
+    s("liege", CHAR, "The court owner employing the position."),
+    s("employee", CHAR, "The character employed in the position."),
+  ],
+
+  // common/character_memory_types/_character_memories.info
+  character_memory_type: [
+    s("memory", "character_memory", "The memory."),
+    s("new_memory", "character_memory", "The newly created memory (creation blocks)."),
+    s("owner", CHAR, "The memory owner."),
+  ],
+
+  // common/great_projects/types/_great_project_types.info
+  great_project: [
+    s("great_project", "great_project", "The funded project (ongoing projects)."),
+    s("owner", CHAR, "The project owner."),
+    s("founder", CHAR, "The project founder."),
+    s("province", "province", "The project's province."),
+  ],
+
+  // common/domiciles (root = owner character / the domicile)
+  domicile_building: [s("owner", CHAR, "The domicile owner.")],
+  domicile_type: [s("owner", CHAR, "The domicile owner.")],
+
+  // common/task_contracts/_task_contracts.info
+  task_contract: [s("employer", CHAR, "The character offering the contract.")],
+
+  // common/subject_contracts + tax slots
+  subject_contract: [
+    s("liege", CHAR, "The liege side of the contract."),
+    s("subject", CHAR, "The subject side of the contract."),
+    s("vassal", CHAR, "The vassal (tax blocks)."),
+    s("tax_collector", CHAR, "The tax collector."),
+    s("tax_slot", "tax_slot", "The tax slot."),
+  ],
+  tax_obligation: [
+    s("liege", CHAR, "The liege."),
+    s("vassal", CHAR, "The vassal."),
+    s("tax_collector", CHAR, "The tax collector."),
+    s("tax_slot", "tax_slot", "The tax slot."),
+  ],
+  tax_slot_type: [
+    s("liege", CHAR, "The liege."),
+    s("vassal", CHAR, "The vassal."),
+    s("tax_collector", CHAR, "The tax collector."),
+    s("tax_slot", "tax_slot", "The tax slot."),
+  ],
+
+  // common/succession_election/_succession_election.info (root = the title)
+  succession_election: [
+    s("candidate", CHAR, "The candidate being evaluated."),
+    s("holder", CHAR, "The current title holder."),
+    s("holder_candidate", CHAR, "The holder as a candidate."),
+    s("title", "landed_title", "The elective title."),
+  ],
+  succession_appointment: [s("title", "landed_title", "The title being appointed.")],
+
+  // Misc single-scope kinds
+  vassal_stance: [s("liege", CHAR, "The vassal's liege.")],
+  legitimacy_level: [
+    s("target", CHAR, "The character whose legitimacy is checked."),
+    s("liege", CHAR, "The target's liege."),
+  ],
+  scripted_relation: [s("target", CHAR, "The other character of the relation.")],
+  suggestion: [s("recipient", CHAR, "The character receiving the suggestion.")],
+  important_action: [s("recipient", CHAR, "The character the alert is for (the player).")],
+  house_aspiration: [s("house", "dynasty_house", "The house the aspiration belongs to.")],
+  combat_phase_event: [s("combat_side", "combat_side", "The combat side of the phase event.")],
+  culture_creation_name: [
+    s("culture", "culture", "The culture being created."),
+    s("other_culture", "culture", "The other parent culture (hybrid cultures)."),
+  ],
+  innovation: [s("character", CHAR, "The innovating culture's ruler (specific trigger blocks).")],
+
+  // common/artifacts
+  artifact_template: [s("artifact", "artifact", "The artifact.")],
+  artifact_visual: [s("artifact", "artifact", "The artifact.")],
+
+  // common/accolade_names/_accolade_name.info (root = the accolade)
+  accolade_name: [
+    s("accolade_type", "accolade_type", "The accolade's primary type."),
+    s("owner", CHAR, "The accolade owner (the liege)."),
+  ],
+};

package/src/games/ck3/index.ts

@@ -0,0 +1,38 @@
+/**
+ * The Crusader Kings III game profile: identity plus every CK3 knowledge table
+ * and bundled-data import, assembled behind the GameProfile interface.
+ */
+import type { GameProfile } from "../profile";
+import { ck3Meta } from "./meta";
+import { BLOCK_REF_FIELDS, CK3_SCHEMA, PREFIX_REFS, REF_FIELDS } from "./schema";
+import { STRUCTURE_SOURCES } from "./structures";
+import { CK3_MODIFIER_PLACEHOLDERS } from "./modifierPlaceholders";
+import { CK3_SAVE_SCHEMA } from "./saveSchema";
+// Bundled baseline data (packages/server/data/ck3/), imported at build time so
+// completion/hover work without gamePath set. See scripts/build-data-types-json.ts
+// and scripts/build-gui-schema.ts for regeneration.
+import BUNDLED_DATA_TYPES from "../../../data/ck3/dataTypes.json";
+import GUI_SCHEMA from "../../../data/ck3/guiSchema.json";
+
+export const ck3Profile: GameProfile = {
+  ...ck3Meta,
+  schema: CK3_SCHEMA,
+  refFields: REF_FIELDS,
+  prefixRefs: PREFIX_REFS,
+  blockRefFields: BLOCK_REF_FIELDS,
+  structureSources: STRUCTURE_SOURCES,
+  // Events declare `scope = character|landed_title|…` and default to character
+  // when the key is absent (events/_events.info); custom loc `type = all` → any
+  // scope; scripted_guis declare `scope = X`.
+  defRootKeys: {
+    event: { key: "scope", default: "character" },
+    customizable_localization: { key: "type" },
+    scripted_gui: { key: "scope", default: "character" },
+  },
+  modifierPlaceholders: CK3_MODIFIER_PLACEHOLDERS,
+  bundledDataTypes: BUNDLED_DATA_TYPES,
+  guiSchema: GUI_SCHEMA,
+  saveSchema: CK3_SAVE_SCHEMA,
+  wikiNote: "Source: CK3 wiki (may lag behind the current game version)",
+  diagnosticSource: "ck3-script",
+};

package/src/games/ck3/meta.ts

@@ -0,0 +1,28 @@
+/**
+ * Crusader Kings III identity and conventions. Data only — safe for the VSCode
+ * client to import without pulling the knowledge tables into its bundle.
+ */
+import type { GameMeta } from "../profile";
+import { GITAN_MEASURED_METRICS } from "../../gui/measuredMetrics";
+import { CK3_SCAFFOLDS } from "./scaffolds";
+
+export const ck3Meta: GameMeta = {
+  id: "ck3",
+  name: "Crusader Kings III",
+  shortName: "CK3",
+  engine: "jomini",
+  descriptor: "mod",
+  configDirName: ".ck3modding",
+  docsFolderName: "Crusader Kings III",
+  steamAppId: 1158310,
+  eventNamespaces: true,
+  // The engine's own default metrics: they were measured on this game's font,
+  // and the layout engine reuses them for games whose probe has not run.
+  uiFont: "fonts/Gitan/GitanLatin-Regular.otf",
+  guiTextMetrics: GITAN_MEASURED_METRICS,
+  scaffolds: CK3_SCAFFOLDS,
+  tiger: { binaryName: "ck3-tiger", repoSlug: "amtep/tiger", confName: "ck3-tiger.conf" },
+  // "" keeps the pre-profile cache filenames (docsCache.json, vanillaIndex-*.json)
+  // so existing users' caches survive the M2 restructure.
+  cacheSuffix: "",
+};

package/src/games/ck3/modifierPlaceholders.ts

@@ -0,0 +1,61 @@
+/**
+ * CK3's templated-modifier placeholder table ($CULTURE$_opinion, …), consumed
+ * by data/modifierTemplates.ts via the game profile.
+ *
+ * Every placeholder mapping below was verified against vanilla 1.19:
+ * `common/modifier_definition_formats/` enumerates the generated names, and
+ * script usage (traditions, buildings, perks…) confirms the join rule is
+ * `<definition name>` spliced verbatim into the template. Unverifiable
+ * placeholders are deliberately absent — a wrong expansion is worse than a
+ * missing one:
+ *  - GEOGRAPHICAL_REGION (map_data) and TRAIT_TRACK (nested in traits) have no
+ *    definition-index kind.
+ *  - SUBJECT_SALARY expands to title tiers, but 40 of the 220 tier combinations
+ *    do not exist in vanilla's formats.
+ */
+import type { PlaceholderSpec } from "../../data/modifierTemplates";
+
+/**
+ * MEN_AT_ARMS_TYPE expands to the engine's hardcoded base types (`type = …` in
+ * a men-at-arms definition), NOT to common/men_at_arms_types names: vanilla
+ * uses `heavy_infantry_damage_mult`, never `armored_footmen_damage_mult`.
+ */
+const MAA_BASE_TYPES = [
+  "archer_cavalry",
+  "archers",
+  "camel_cavalry",
+  "elephant_cavalry",
+  "gunpowder",
+  "heavy_cavalry",
+  "heavy_infantry",
+  "light_cavalry",
+  "nomadic_horde",
+  "pikemen",
+  "siege_weapon",
+  "skirmishers",
+] as const;
+
+export const CK3_MODIFIER_PLACEHOLDERS: Record<string, PlaceholderSpec> = {
+  CULTURE: { kind: "culture", label: "culture" }, // akan_opinion
+  // Faiths are nested under `faiths = { … }` and not indexed yet (see
+  // schema.ts); the mapping is inert until they are, which is correct.
+  FAITH: { kind: "faith", label: "faith" }, // mutazila_opinion
+  GOVERNMENT_TYPE: { kind: "government", label: "government" }, // feudal_government_opinion
+  HOLDING_TYPE: { kind: "holding_type", label: "holding type" }, // castle_holding_build_speed
+  LIFESTYLE: { kind: "lifestyle", label: "lifestyle" }, // diplomacy_lifestyle_xp_gain_add
+  MEN_AT_ARMS_TYPE: {
+    values: MAA_BASE_TYPES,
+    label: "men-at-arms base type",
+    // Verified exception: stationed_* variants exist for every base type
+    // EXCEPT nomadic_horde (absent from vanilla formats and script usage).
+    excludeValues: { stationed_: ["nomadic_horde"] },
+  },
+  RELIGIOUS: { kind: "religion", label: "religion" }, // christianity_religion_opinion
+  RELIGIOUS_FAMILY: { kind: "religion_family", label: "religion family" }, // rf_pagan_opinion
+  SCHEME_TYPE: { kind: "scheme_type", label: "scheme type" }, // abduct_scheme_phase_duration_add
+  SCRIPTED_RELATION: { kind: "scripted_relation", label: "scripted relation" }, // scheme_phase_duration_against_rival_add
+  SITUATION_TYPE: { kind: "situation", label: "situation" }, // the_great_steppe_supply_limit_add
+  TAX_SLOT_TYPE: { kind: "tax_slot_type", label: "tax slot type" }, // clan_tax_slot_add
+  TERRAIN_TYPE: { kind: "terrain_type", label: "terrain type" }, // plains_advantage
+  VASSAL_STANCE: { kind: "vassal_stance", label: "vassal stance" }, // courtly_opinion
+};

package/src/games/ck3/saveSchema.ts

@@ -0,0 +1,134 @@
+/**
+ * How a Crusader Kings III save is read for GUI preview values.
+ *
+ * CK3 packs its script into a zip holding one `gamestate` entry (gui/saveZip.ts
+ * finds it; `-debug_mode` writes the same script as plain text instead), and
+ * names the played character LAST, in `played_character`, long after the
+ * `living` record a preview wants. That is what `record` below describes: find
+ * the id first, then cut out `living.<id>`.
+ *
+ * CK3's player is a character, so most rows read that record; the three names
+ * the load-game screen shows (character, primary title, house) the save already
+ * carries ready-localized in `meta_data`, which is why no title or dynasty
+ * block has to be cut out of a 70 MB gamestate to render them.
+ */
+import type { BlockNode } from "../../parser";
+import {
+  age,
+  block,
+  named,
+  scalar,
+  statements,
+  thousands,
+  type SaveContext,
+  type SaveSchema,
+  type ValueMapping,
+} from "../../gui/saveSchema";
+
+/** The living character's own state (currencies, variables) sits under here. */
+function aliveData(ctx: SaveContext): BlockNode | undefined {
+  return block(ctx.character, "alive_data");
+}
+
+function firstName(ctx: SaveContext): string | undefined {
+  return named(ctx, scalar(ctx.character, "first_name"));
+}
+
+const CK3_MAPPINGS: ValueMapping[] = [
+  {
+    // `first_name` is a loc key (`Alp_Arslan`), which is what CK3's own
+    // `GetName` renders for a character.
+    chains: ["GetPlayer.GetName", "GetPlayer.GetFirstName"],
+    read: (ctx) => firstName(ctx),
+  },
+  {
+    chains: ["GetPlayer.GetFullName"],
+    read: (ctx) => {
+      const first = firstName(ctx);
+      const house = scalar(ctx.meta, "meta_house_name");
+      return first && house ? `${first} ${house}` : first;
+    },
+  },
+  {
+    chains: ["GetPlayer.GetAge"],
+    read: (ctx) => age(scalar(ctx.character, "birth"), scalar(ctx.meta, "meta_date")),
+  },
+  {
+    chains: ["GetPlayer.GetGold"],
+    read: (ctx) => thousands(scalar(block(aliveData(ctx), "gold"), "value")),
+  },
+  {
+    chains: ["GetPlayer.GetPrestige"],
+    read: (ctx) => thousands(scalar(block(aliveData(ctx), "prestige"), "currency")),
+  },
+  {
+    chains: ["GetPlayer.GetPiety"],
+    read: (ctx) => thousands(scalar(block(aliveData(ctx), "piety"), "currency")),
+  },
+  {
+    // `meta_title_name` IS the primary title's name, article and all.
+    chains: ["GetPlayer.GetPrimaryTitle.GetName"],
+    read: (ctx) => scalar(ctx.meta, "meta_title_name"),
+  },
+  {
+    // The meta carries the HOUSE name; for most characters the dynasty reads
+    // the same, and a preview shows what is knowable.
+    chains: ["GetPlayer.GetDynasty.GetName", "GetPlayer.GetHouse.GetName"],
+    read: (ctx) => scalar(ctx.meta, "meta_house_name"),
+  },
+  {
+    chains: ["GetCurrentDate", "GetGameDate"],
+    read: (ctx) => ctx.date,
+  },
+];
+
+/**
+ * The character variables the save holds, as the two chains a modder reads them
+ * back with. `alive_data.variables.data` is a list of
+ * `{ flag=<name> data={ type=… identity=… } }`; a script value is conventionally
+ * named exactly like the variable it mirrors, so both chains answer from it.
+ * A variable the save stores without a value (a bare flag) stays absent.
+ */
+function characterVariables(ctx: SaveContext): Record<string, string> {
+  const out: Record<string, string> = {};
+  const data = block(block(aliveData(ctx), "variables"), "data");
+  for (const s of statements(data)) {
+    if (s.kind !== "value" || s.value.kind !== "block") continue;
+    const name = scalar(s.value, "flag");
+    const text = variableValue(block(s.value, "data"));
+    if (!name || text === undefined) continue;
+    out[`GetPlayer.MakeScope.Var('${name}').GetValue`] = text;
+    out[`GetPlayer.MakeScope.ScriptValue('${name}')`] = text;
+  }
+  return out;
+}
+
+/** One variable's stored value; `type=value` is fixed point, x100000. */
+function variableValue(data: BlockNode | undefined): string | undefined {
+  const identity = scalar(data, "identity");
+  if (identity === undefined) return undefined;
+  switch (scalar(data, "type")) {
+    case "value":
+      return fixedPoint(identity);
+    case "boolean":
+      return identity === "0" ? "no" : "yes";
+    default:
+      // A character/title/… variable: the id is all the save holds about it.
+      return identity;
+  }
+}
+
+/** `2700000` -> `27`, `25000` -> `0.25`. */
+function fixedPoint(raw: string): string | undefined {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return undefined;
+  return String(Number((n / 100000).toFixed(5)));
+}
+
+export const CK3_SAVE_SCHEMA: SaveSchema = {
+  dateKey: "meta_date",
+  nameKey: "meta_player_name",
+  mappings: CK3_MAPPINGS,
+  expand: characterVariables,
+  record: { marker: "\nplayed_character={", idKey: "character", block: "living" },
+};