DCS Mission Authoring Gateway

dcs-me-gateway is a local MCP server between an AI mission designer and the DCS-SMS Mission Editor bridge. It turns many fragile editor commands into a small, versioned authoring protocol.

The gateway does not click the UI and never focuses DCS. Requests are written to the existing DCS-SMS mailbox. If DCS is unfocused and its Mission Editor update loop is throttled, a request remains queued until ticks resume or the caller-selected deadline expires.

Implemented in 0.9

• Thirty-five MCP tools: update discovery, mission authoring/validation, persistent semantic map and hydrology preprocessing, offline queries, live map inspection, live airbase and carrier-package allocation, native transport routing, DCS-authored loadout discovery, live AI-task discovery, flight-profile/timing planning, package templates, drawings, deterministic mission documents, optional Skynet-IADS setup, and bounded offline external-content management.

• Forty-one declarative patch operations for the mission environment, groups, units, payloads, routes, typed waypoint options/behavior, named group Triggered Actions, triggers, circular zones, group frequencies, and unit callsigns.

• Stable logical references, including adoption of existing named mission entities and DCS-allocated unit names.

• The mission-design guidance is advertised as MCP server initialization instructions, not only as an optional resource/prompt, so compatible clients receive the planning, timing, loadout, and AI-policy defaults automatically.

• Compact semantic snapshots, deterministic revisions, optimistic concurrency, and per-operation postcondition checks.

• Per-mission bindings and idempotency records protected by atomic writes and inter-process locking.

• Absolute request expiry and explicit OUTCOME_UNKNOWN handling prevent late execution and unsafe replay after a lost response.

• A validated patch is dispatched in one Mission Editor callback; partial committed prefixes are recorded if a later verb fails.

• Prefab-shaped mission fragments use a dedicated DCS-SMS transaction endpoint with native ID/name allocation, cross-reference remapping, rollback, and editor-side replay protection.

• Save/reopen verification waits for a stable semantic revision and migrates bindings across Save As identity changes.

• Fixed compatibility guards for DCS-SMS-created vehicle routes and stale Mission Editor route-panel ownership.

• No arbitrary-Lua MCP tool.

• Revision-tracked F10 map annotations support verified batches of circles, lines, polygons, text labels, and removals without exposing a tool per shape.

• A data-driven mission-template catalog returns tunable S-300PS/Buk site layouts and staged AWACS/tanker racetracks. The two SAM packages are live checked against the installed DCS unit database; they are functional, representative starting points rather than exact real-world orders of battle.

• Carrier-package authoring discovers live Supercarrier entitlement, available free/paid hulls, and carrier-capable aircraft from DCS's own runway-category metadata. One transaction can place a carrier alone or in a representative blue/red escort formation, calculate wind over deck, author supported TACAN/ICLS/Link 4/ACLS actions, bind aircraft starts and optional recovery waypoints to the deck, and apply named loadouts plus combat consumables.

• Basic communications authoring writes group frequencies and normalized unit callsigns. Offline validation warns when AWACS/tanker groups share a frequency.

• Cached terrain can answer coordinate/elevation profiles and straight-line terrain LOS with explicit clearance and obstruction points. Buildings and vegetation remain outside that model.

• Mixed-mode authoring includes a deterministic 1024×1440 military-light player dossier and a copy-on-write .miz external-content overlay. The dossier reads callsign, aircraft, route, timing, radios, carrier aids, stores, fuel, gun, and countermeasures from a pinned saved mission; optional tactical prose remains explicit agent input. Route pages use clean cached DCS terrain with semantic and F10 overlays disabled. The overlay manages aircraft/general kneeboards, briefing text and pictures, and bounded image/sound/Lua resources without editing the source mission in place.

• A resumable tile cache extracts authoritative DCS elevation and surface type, derives slope, aspect, roughness, and candidate ridge/valley/pass features, and renders both a clean terrain PNG and an annotated context PNG without requiring DCS for later queries.

• An independently resumable hydrology layer samples DCS surface type at 50 m by default without rebuilding elevation, slope, or semantic regions. It packs each sample into two bits, skips high-confidence uniform land and open-sea base tiles, derives bounded eight-connected river/lake components with separately reported conservative short-gap stitching, and can expand from a validated slice to full-dataset coverage with stable tile IDs.

• Each cache stores DCS-authored named places and fixed-airbase metadata, including runway thresholds/lengths, parking envelopes, shelter flags, and derived apron clusters. Place labels remain explicitly unranked because DCS's towns source provides names and coordinates, not importance.

• A bounded anchor graph caches DCS-native road and railroad corridors between nearby airbases and named places, including detour, elevation/grade, endpoint snap, and water-crossing evidence. Live routing remains available for precise endpoints because the cache is not a complete road-network export.

• Rough settlement regions are buffered named-place clusters with explicit provenance and recommended image-view bounds. They are not building footprints; individual structures remain a visual map-inspection task.

• The semantic cache also stores queryable airbase, settlement, and named-place entities plus contiguous terrain regions classified from surface, elevation, slope, roughness, and low-detail evidence. Regions use compact row runs and record adjacency rather than pretending that a raster cell is a real-world administrative boundary.

• A resumable macro transport graph uses airbase and settlement hubs. Its edges are DCS-native road/rail paths with snapped endpoint gateways, so an offline query can select a multi-edge regional route while live DCS routing remains the authority for the exact first/last-mile convoy geometry.

• On-demand map inspection fits the live ME map to requested bounds, captures only its map widget, writes a georeferenced PNG, and restores the previous camera. A camera-motion frame check rejects hidden-editor captures (for example, when a running mission's F10 view is actually on screen).

• Preprocessing automatically checks cache shape, exact shared tile edges, and 16 deterministic points against live DCS. The same report can be rerun with validate_map_dataset, or with live parity disabled for offline-only QA.

• Conservative low-detail detection records its evidence and only stores a coarse tile when near-uniform land passes every threshold; it does not silently equate ordinary flat terrain with Caucasus edge placeholders.

• DCS-saved golden fixtures, offline archive/Lua/reference tests, and an isolated live authoring harness that edits a clone, restores the original, and verifies its file hash.

• Live airbase planning uses DCS's aircraft-envelope/category filter and the open mission's reserved stands, mission surface wind, runway labels, and a stand-to-likely-threshold taxi proxy. Verified creation supports cold, hot, and runway starts for one-to-four aircraft and removes a partially built group if a construction step fails. Active-runway strategy can reassign the native compact parking choice to the verified preferred stand set.

• Preset-first loadout authoring queries the installed DCS build for named aircraft presets, their declared task compatibility, stores, and weight. Patches can apply one preset or make a bounded per-pylon adjustment; the gateway never asks the model to invent CLSIDs or an entire payload. Combat authoring also explicitly checks gun ammunition; a zero-gun combat aircraft is warned unless that omission is intentional.

• Live task discovery lists only the waypoint and enroute actions DCS exposes for an existing group, and task descriptions provide defaults, allowed values, and missing target-selector guidance before a patch is authored.

• Mission date/time and useful weather fields are readable in every semantic snapshot and writable as one revision-checked environment operation. Typed waypoint options include Reaction on Threat, ROE, radar/ECM use, bingo RTB, silence, and jettison/afterburner prohibitions.

• Role-based fixed-wing profiles and transparent startup/taxi/climb/transit estimates help synchronize package arrival. Offline lint warns when an AI scramble/intercept begins its transit low or slow.

• Offline behavior lint warns about unarmed AI combat aircraft, combat groups without engagement tasking, target tasks without target IDs, semantic waypoint names without corresponding behavior, and air routes without a terminal landing/orbit/loop. Objective lint also warns about opposing outcomes that can both fire, capture conditions satisfied by one surviving group member, briefing-named groups omitted from every recognized outcome condition, and intercept waypoints assigned to non-air groups. These are heuristic authoring warnings, not claims about DCS runtime AI correctness.

The gateway does not claim rollback for declarative patches. DCS-SMS patch verbs are run sequentially in one ME callback; if verb N fails, verbs 1 through N-1 may already be committed. The result records the committed prefix and the idempotency key, preventing a blind duplicate retry. The separate apply_mission_fragment endpoint has native DCS-SMS rollback and reports an incomplete rollback explicitly. If its acknowledged result or post-apply snapshot cannot prove the requested outcome, the gateway returns OUTCOME_UNKNOWN and requires mission inspection before recovery; it never pretends that a failed verification undid the mutation. A future transactional patch verb is described in docs/dcs-sms-extension.md. Because the live semantic revision does not include warehouse contents, the gateway conservatively blocks cached replay of fragments that contain warehouse effects; inspect the mission before choosing a new key. Drawings are included in semantic revisions and save/reopen verification.

Revisions and save/reopen verification cover the protocol 0.1 authoring surface: semantic environment, group, unit, route, trigger, zone, and drawing records, plus mission path and theatre. Briefing, warehouses, and global mission options are outside the current revision boundary.

DCS persists vehicle headings at group level. The semantic snapshot therefore uses the lead vehicle's heading for every unit in that vehicle group. An attempt to give only a non-lead vehicle a different persistent heading fails postcondition verification instead of silently drifting after reopen.

Requirements

• The Windows release includes its own Node.js runtime. Source development requires Node.js 20.17 or newer.

• Windows, DCS World, and the DCS-SMS ME-mod for live-editor tools only.

• Mission Editor open with DCS-SMS -> External execution enabled for mutation.

• inspect_map_view additionally requires the Mission Editor map to be open in a non-minimized window. DCS may remain unfocused or covered; the gateway captures its application window directly, never brings it to the foreground, and does not silently fall back to an occlusion-sensitive monitor capture.

Map extraction requires the typed terrain info, terrain sample-grid, and terrain list-places, terrain nearest-transport, terrain transport-path, airbase plan-start, and airbase create-start verbs in the accompanying DCS-SMS ME-mod 0.32.4 worktree.

Install the Windows release

The release is one ZIP. It includes the gateway, locked production dependencies, a portable Node runtime, and the compatible DCS-SMS Mission Editor bridge source. It does not require a separate DCS-SMS installation and does not install the DCS-SMS mission hook or optional LuaSec/OpenSSL files.

Extract the ZIP, close DCS, and run:

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Clients codex

Supported -Clients values are codex, claude-code, claude-desktop, and generic; more than one may be passed. generic writes a portable mcp-config.json. Codex and ChatGPT desktop share Codex's local MCP configuration. Claude Code and Claude Desktop are registered independently. Other clients can use the same stdio command and environment from the generic file. ChatGPT on the web cannot directly launch a local stdio server; this package targets ChatGPT desktop/Codex on the machine running DCS. See the current OpenAI MCP documentation and Claude Code MCP documentation for their native configuration surfaces.

The installer:

• discovers DCS and Saved Games or accepts -DcsPath and -SavedGames;

• verifies DCS has Full Screen disabled, but never edits that preference;

• refuses to patch the Mission Editor while DCS is running;

• backs up the user's MissionEditor.lua and any previous bridge;

• installs the bundled GPLv3 bridge source and adds only its delimited require block to the user's own editor file; and

• registers only the dcs-me MCP entry requested by the user and pins that entry to the selected Saved Games instance.

At MCP startup the gateway checks GitHub's latest stable-release endpoint, with a 2.5-second timeout and a six-hour local cache. When a newer semantic version is available, its MCP instructions tell the agent to ask the user whether to update. The check never installs anything. After explicit approval, close DCS and every MCP client using the gateway, then run:

powershell -NoProfile -ExecutionPolicy Bypass -File `
  "$env:LOCALAPPDATA\DcsMeGateway\update.ps1"

The updater asks again before mutation, downloads only the versioned Windows release, verifies its separately published SHA-256, and invokes the normal backup-preserving installer. Set DCS_ME_GATEWAY_UPDATE_CHECK=0 to disable the automatic check. check_gateway_update performs an on-demand or forced check. Prerelease tags are intentionally excluded from this update channel.

For an agent-guided install, hand the extracted folder to an agent and ask it to follow VIBEINSTALL.md. After installation, restart the MCP client, open a mission in DCS Mission Editor, and enable DCS-SMS -> External execution. That toggle is session-only.

The gateway is MIT. The bundled DCS-SMS bridge remains GPLv3 and ships with its complete source and license under payload/bridge; see THIRD_PARTY_NOTICES.md.

Install from source and verify

cd C:\path\to\dcs-me-gateway
npm install
npm test
npm run build
npm run test:golden
npm run test:live

Everything through test:golden is fully offline; DCS can remain closed. Validate any saved mission independently with:

npm run validate:miz -- D:\Missions\mission.miz

The validator checks ZIP integrity and expansion limits, required entries, literal Lua syntax, mission structure, IDs/names, routes, coordinates, entity references, dictionary keys, and packaged resources. It parses Lua into data without loading or executing mission code.

Given the declarative patch and saved files from immediately before and after it, produce a focused acceptance report with:

npm run report:patch -- patch.json before.miz after.miz [bindings-before.json] [bindings-after.json]
npm run docs:render -- --mission <saved.miz> --dataset <dataset-id> --output <new-directory>

The report contains direct patch targets, one-hop dependency context, operation postconditions, introduced/resolved validation findings, and any changed entities outside that scope. It exits nonzero if the after-file is invalid, a postcondition fails, a dependency changed unexpectedly, unrelated mission metadata/options/warehouses changed, or an out-of-scope entity changed. Patches that refer to logical IDs created earlier must provide the relevant {"entities": ...} binding object (before and, if allocations changed, after); unresolved IDs are reported explicitly and fail acceptance.

test:live reads only the editor session. Add -- --snapshot for a live, read-only mission snapshot.

npm run test:live-authoring is intentionally mutating. It requires a saved mission already open in the Mission Editor. The harness first Save-As clones that mission under .artifacts/live, edits only the clone, checks idempotency, revision conflicts, route editing, zones, and save/reopen stability, then reopens the original and verifies that its SHA-256 did not change. It does not launch or fly the mission.

Start the MCP server over stdio:

node C:\path\to\dcs-me-gateway\build\index.js

An MCP host should configure that command and path as a stdio server named dcs-me. Diagnostics go to stderr; stdout is reserved for MCP frames.

Configuration

Without an override, the gateway reads DCS-SMS's saved_games config value, then chooses the DCS, DCS.openbeta, or DCS.server instance with the newest ME heartbeat. Set DCS_SMS_SAVED_GAMES when Windows Saved Games has been relocated and DCS-SMS has not recorded that path in its config.

MCP tools

Map-pack lifecycle

Before map-specific mission planning, the mission agent is instructed to call ensure_map_dataset for the theatre. The tool first reuses a complete local dataset, then checks the packaged registry and its optional GitHub-hosted remote registry. A download is streamed, bounded by its registered byte count, checked against its registered SHA-256, safely extracted, validated for dataset/theatre identity and completeness, and published atomically. The packaged registry at maps/registry.json is also the canonical remote registry. Large datasets are immutable, SHA-256-pinned GitHub release assets; raw caches and generated archives are never committed to Git.

If no pack is registered, the tool returns permission_required rather than opening DCS or starting hours of extraction by itself. Only after the user approves may the agent repeat the call with allow_local_build=true. The requested theatre must be installed and open in Mission Editor with external execution enabled. The build is resumable and may require repeated calls.

Developers can explicitly build and package an unhosted theatre:

npm run maps:settlements
npm run maps:build -- --theatre Caucasus
npm run maps:package -- --dataset caucasus-full-v01-250m `
  --base-url https://github.com/ALasek/DCS-ME-gateway/releases/download/maps-v0.9.0

maps:settlements is a fast, independent review pass for the theatre currently open in Mission Editor. It resolves the matching curated catalog through DCS's authoritative coordinate conversion, merges DCS-native town labels, and writes JSON plus a labelled PNG under .artifacts/settlements. It does not sample or rebuild terrain, elevation, land cover, hydrology, transport, or airbase data. Use --output <directory> to choose a stable output location.

The packaging command prints the exact registry entry, including archive size and SHA-256. Add that entry to maps/registry.json and upload the .tgz to the matching release. Local building is the fallback for maps the project author does not own; it is never implicit consent.

preprocess_map_region validates the requested rectangle against DCS's authoritative theatre bounds. DCS's 4,096 limit applies to samples in each terrain-grid request, not to dataset tiles. max_tiles is only a deliberate dataset-size guard (50,000 by default); tile_batch_limit bounds each MCP invocation to 200 missing tiles by default. If the result has complete=false, repeat the call with identical dataset geometry and sampling settings. Each tile and manifest update is already durable, incomplete datasets reject normal queries, and final validation can evict unreadable, malformed, or seam-invalid tiles for automatic repair on the next batch. Batch size and safety-guard changes do not change an automatically generated dataset ID. Its north/east coordinates are the same theatre-local metres used by mission objects. The default conservative prepass may retain high-confidence uniform sea or placeholder-like uniform land at coarse resolution; every such decision is visible in the manifest and query result. Coastlines, mixed surfaces, and flat terrain that do not satisfy all thresholds remain full resolution. Airbases and DCS-authored place labels are cached beside the terrain tiles and annotated on previews. Place records are not classified as city/town/village because the DCS source does not expose that distinction. Semantic provenance records the DCS build, locale, and theatre towns source; place IDs are coordinate-derived because duplicate Lua keys are overwritten when DCS loads some theatre datasets. A changed DCS terrain build requires an explicit force=true rebuild instead of silently reusing stale tiles. query_map_context, query_airbase_context, and query_transport_context read only the cache, so DCS may be closed. The 200 m apron clustering and compact/standard/large envelope bands are navigation heuristics, not DCS compatibility claims. plan_airbase_start always rechecks the requested aircraft and current occupancy through DCS before mutation.

render_mission_documents is deterministic for the same saved mission, terrain cache, style version, selected groups, and supplied prose. By default it selects Player/Client flights. It produces a manifest and ready-to-pass kneeboard_images entries but does not modify the mission. DCS kneeboard folders can target all aircraft or an aircraft type; they cannot distinguish two flights using the same type, so combine those instructions or use briefing pages when flight-specific separation is required. The mission card identifies the aircraft type without implying a per-flight quantity. The comms/loadout page uses canonical human-readable store names, fuel in pounds, and gun ammunition as a percentage; it never displays internal CLSIDs. If the saved mission has stores but no readable preset name, call get_aircraft_loadouts with include_stations=true and pass its DCS-authored display names in flight_notes.loadout_summary. Rendering then emits an explicit warning until those names are supplied. Waypoint tables use verified saved-route ETA values where the route is genuinely scheduled; state-gated or player-paced events can instead use flight_notes.waypoint_notes[].time_label for cues and timing windows without inventing a fixed clock time. Rendering warns when a multi-waypoint player route has neither useful ETA values nor time labels. Route maps add only sparse airbase and major-settlement labels, with route and waypoint labels retaining collision and visual priority. Preview every page before embedding it.

apply_miz_overlay is deliberately not a general mission-table editor. Save the live ME mission, close or open a different file, inspect existing external content, pin that source file's reported SHA-256, and write to a new output path. The tool validates real image/sound/script signatures, refuses referenced resource deletion, and garbage-collects replaced briefing pictures only when no mission reference remains. After the overlay succeeds, open the output in ME and run save_and_verify. Core groups, routes, triggers, and objectives remain ME-authored; this prevents two writers from silently diverging on the same .miz.

Optional Skynet-IADS

For a meaningful multi-site/EWR network, SEAD/DEAD scenario, or mission whose balance depends on radar-emission tactics, the agent may recommend Skynet once and ask whether the user accepts runtime-script-dependent behavior. It should not interrupt every isolated-SAM design with that question. Native DCS alarm states and deterministic emission triggers remain the default for isolated, predictable, or training threats.

After acceptance, give managed SAM group names one common prefix and managed EWR unit names a distinct prefix, save the mission, and call setup_iads with the saved file's SHA-256 and a new output path. The tool verifies and embeds Skynet-IADS 3.3.0 with its upstream-tested MIST 4.5.107, then adds one Mission Start trigger loading MIST, Skynet, and the generated configuration in that order. The resulting .miz is self-contained; players install nothing. Open the output in Mission Editor and run save_and_verify before continuing.

The setup validates script hashes, load order, coalition membership, prefixes, and named command centers. It cannot prove runtime IADS behavior without running the mission. Keep one SAM system type per managed SAM group, one EWR radar per managed EWR group, and do not add native emission actions that fight Skynet for the same radars. Provenance, exact hashes, and licenses are recorded under vendor/skynet-iads/3.3.0 and THIRD_PARTY_NOTICES.md.

analyze_terrain_line bilinearly interpolates the finest cached grid covering each sample and reports clear, blocked, or indeterminate. The classifier uses an explicit elevation-resolution envelope: clear and blocked require the entire envelope to stay on one side of the sightline. Cached-only mode reports the uncertain corridor and recommended spacing without contacting DCS. refinement_mode=auto-live samples that bounded corridor from a matching open Mission Editor theatre, splits it to the extension's per-call sample limit, persists the finer tiles under the dataset, and immediately reruns the LOS. Later queries reuse those tiles with DCS closed. A fine rerun may legitimately remain indeterminate; the response reports a resolution limit and, where possible, a smaller next spacing rather than inventing a clear/blocked answer. This is suitable for radar/SAM placement and route screening, but not final visibility claims where buildings or trees matter.

After the terrain tiles finish, semantic preprocessing derives a 2 km classification raster, smooths isolated non-water cells, and converts each four-connected component into a compact terrain region with statistics, adjacency, and row-run geometry. Airbases and settlement clusters become graph hubs. Road candidates include up to four neighbors within 80 km plus bounded connectivity repair; railroad candidates include up to two neighbors within 120 km. DCS railroad routing is treated as candidate evidence because its terrain-network selector can return unrelated linear features. A cached rail corridor must snap within 1.5 km of both anchors and its routed length must cover at least half their direct separation; weaker results remain failed candidates for inspection instead of being exposed to the agent as rail. transport_batch_limit bounds live DCS path extraction per invocation, and pending/complete/failed edge state is durable and resumable. Completed polylines retain hub IDs and snapped gateway points. query_transport_context uses Dijkstra over completed cached edges for an offline named-hub route; route_ground_transport applies the same conservative rail checks to exact current DCS paths used for mission authoring. Water-surface runs are labeled water-crossing-candidate, not asserted to be destructible bridge objects. Settlement clustering deliberately avoids a per-building catalogue, which would be terrain-version-sensitive and unnecessarily large.

The Persian Gulf processor supplements DCS's own town labels with the sparse, editable catalog at maps/settlements/persian-gulf.json. It contains major cities, ports, and island settlements selected for an approximately 1980-1990 scenario vocabulary; it is not a historical urban footprint. During preprocessing, DCS converts each WGS84 point into the loaded theatre's local coordinates. Matching nearby DCS labels retain their DCS position while gaining the curated name, aliases, type, and importance. A standalone curated point remains regional semantic evidence only. Catalog SHA-256 and source/era provenance are stored in semantics.json, so editing the catalog invalidates and rebuilds cached settlement and transport semantics without rebuilding elevation tiles. See maps/settlements/README.md for the intentionally simple cleanup format.

query_map_context may be called with bounds, a semantic_search, or both. Semantic search can filter terrain classes, minimum region area, proximity to an entity, entity kind/name, and approximate road access without loading terrain tiles or requiring DCS. inspect_map_view is the complementary detail path: it does not cache every building or road marking, but returns the current ME rendering at the requested scale with an affine pixel-to-theatre transform. It temporarily writes the ME map camera, serializes against other gateway mutations, and restores the prior camera even when capture or visibility validation fails. It resolves the exact DCS window handle and fails with window geometry and recovery details when DCS is minimized or an exclusive-fullscreen Alt-Tab has removed its capturable surface. Borderless/windowed DCS may stay behind the MCP client during inspection. If an airbase, settlement cluster, and raw DCS place share a name, use the returned entity ID or a kind:name selector such as settlement:Batumi or airbase:Batumi; ambiguous bare names fail instead of silently selecting one.

Run the local layered cache viewer with npm run viewer during development or npm run viewer:start after npm run build, then open http://127.0.0.1:4317. It visualizes the clean cached topography, contiguous terrain regions, usable and failed transport edges, settlement hulls, semantic entities, and labels without contacting DCS.

validate_map_dataset streams tile readability and array checks, compares only adjacent shared edges, and does not materialize the full map in memory. Its default direct_samples=16 compares evenly distributed cached points with the currently loaded DCS theatre; use direct_samples=0 for the offline-only checks. The report is also saved as validation.json under the dataset directory. The completed dataset overview is likewise painted from one tile at a time into its bounded output raster.

The bounded Caucasus development harness deliberately samples the detailed Batumi-Kobuleti coast-to-mountain strip rather than the map's flat outer area:

npm run test:live-map

It samples north=-370000..-330000, east=610000..670000 at 250 m, persists progress after every tile, and is safe to rerun. Add -- --force only to deliberately refresh already cached tiles. It does not process the whole map.

Hydrology refinement

The 250 m terrain cache is intentionally not treated as authoritative river geometry: a narrow river can fall between grid points and appear as sparse blue dots. preprocess_hydrology_layer attaches a separate hydrology/ cache to an existing completed dataset. Its default 50 m grid stores only a compact two-bit surface code per sample; elevation and terrain derivatives remain at their base resolution. Base tiles already proven to be uniform placeholder land or open sea are omitted from planning, while detailed and mixed coastal tiles are sampled.

Start with representative bounds and repeat identical calls until completeForBounds=true. Later omit bounds to expand the same layer over all detailed base tiles. tile_batch_limit bounds each invocation and max_tiles is only a deliberate safety ceiling. A changed spacing, tile size, theatre, or DCS terrain signature fails closed; force=true deliberately begins a new hydrology refresh and subsequent resumable calls use force=false. query_map_context returns coverage, exact bounded surface counts, deterministic stitch metrics, and sampled eight-connected river/lake components when the layer exists. Its preview and clean documentation maps incorporate the finer water mask.

The original DCS codes and surface counts remain immutable evidence. An offline directional stitcher may fill at most two missing cells when source samples on both ends continue along the same line; inferred cells are reported separately and are used only for component continuity and rendering. This is deliberately more conservative than unrestricted morphological closing, which can merge nearby unrelated waterways. Component geometry is neither a bank polygon nor a navigation guarantee. Rivers narrower than the chosen spacing can still be fragmented, so use a tighter bounded pass or live map inspection when exact bank placement matters. High-confidence coarse placeholder-land and uniform-sea base tiles are outside hydrology coverage by design; this optimization assumes the base low-detail calibration has already separated the map's non-mission terrain from real detailed plains. The viewer exposes the generated layer as a separately toggleable Rivers / lakes overlay. Presentation is derived rather than evidentiary: lakes retain a smoothed sampled-area raster, while river bands are deterministically thinned, conservatively gap-joined, simplified, and drawn as anti-aliased SVG centerlines with a fixed screen-space width. Queries and validation continue to use the original packed cells and separately identified stitch points.

The complete patch schema is also exposed as the MCP resource dcs-me://schema/mission-patch/0.1. See examples/f16-rwr-patch.json and its subsequent examples/f16-rwr-route-patch.json.

Whole-mission authoring should begin with the MCP prompt design_dcs_mission. It guides a conversation rather than demanding a one-shot specification: the agent may ask high-impact questions, recommend defaults, suggest alternatives, and maintain a living player role, outcome, phase, per-group purpose, causal interaction, capability/loadout, and balance record. The canonical human-readable instruction is docs/design-dcs-mission.md; the server loads that same file for initialization instructions, the MCP prompt, and the guidance resource. A coherent backbone and first slice precede mutation, but later details may remain open while approved slices are authored and tested. The same instruction is available as the read-only resource dcs-me://guidance/mission-design/0.1. Mission concepts are developed with the user and implemented incrementally to respect Mission Editor binding barriers.

The complete-fragment schema is exposed at dcs-me://schema/mission-fragment/0.1. It accepts the data model used by a DCS-SMS prefab (meta, groups, statics, zones, drawings, and triggers) plus an explicit placement policy. The endpoint performs its preflight and mutation inside the Mission Editor, so calling it requires DCS; developing and running the repository test suites does not.

The high-level carrier request schema is exposed at dcs-me://schema/carrier-package/0.1. Query get_catalog with kind=carrier_capabilities first to inspect the open DCS installation's hulls, entitlement, carrier-compatible aircraft, and escort types. dry_run=true returns the compiled fragment and resolved wind-over-deck plan without changing the mission. Auto module selection prefers Supercarrier when DCS reports it installed and authorized and otherwise selects the coalition's free carrier.

The high-level airbase request schema is exposed at dcs-me://schema/airbase-start/0.1. create_airbase_start requires an open Mission Editor, checks the requested semantic revision and idempotency key, preflights free compatible stands, invokes the native DCS-SMS construction verb, then verifies group size, aircraft type, waypoint-zero airdrome linkage, takeoff mode, and explicit parking IDs in a fresh snapshot. The default active_runway parking strategy uses surface wind and runway designators to rank free compatible stands by straight-line threshold distance, then verifies the reassignment; compact preserves DCS-SMS's original nearby-group choice. That distance is a taxi proxy, not a routed time guarantee. Fixed land airfields use this endpoint; carrier deck slots use setup_carrier_package. FARPs remain a separate future surface.

Trigger field values can refer to an earlier logical entity with "$ref:<logical_id>"; the compiler substitutes its stable DCS name. A reference to a named Triggered Action is resolved to DCS's current {groupId, taskNumber} tuple immediately before the trigger action is added. Route point index values in snapshots and every patch waypoint_index are zero-based. Trigger rule indices and Triggered Action slots remain one-based.

Supported operations are:

• Existing entities: adopt_entity for exact group, unit, trigger, or zone names.

• Groups: create_group, set_group_task, set_group_late_activation, remove_group. Set lead_logical_id on create_group when later patches must address its first unit; the gateway binds the name returned by DCS.

• Units: add_unit, set_unit_skill, set_unit_heading, set_unit_loadout, set_unit_payload, clear_unit_payload, remove_unit. Payload consumables: set_unit_fuel, set_unit_chaff, set_unit_flare, and set_unit_gun.

• Routes: add_waypoint, insert_waypoint, remove_waypoint, link_waypoint_airbase.

• Waypoint behavior: add_waypoint_task, add_waypoint_enroute_task, remove_waypoint_task, remove_waypoint_enroute_task, clear_waypoint_tasks, clear_waypoint_enroute_tasks, and the typed set_waypoint_option operation. Task fields accept nested JSON-like arrays and records, including selectors such as targetTypes: ["Air"].

• Group Triggered Actions: add_triggered_task, replace_triggered_task, and remove_triggered_task. These author task/en-route-task entries with stable names; use the task logical ID in an a_ai_task or a_set_ai_task trigger action field. Remove its referencing trigger action before removing the task.

• Environment: set_mission_environment for date/time, temperature, QNH, visibility, turbulence, wind at three levels, clouds, and dust.

• Triggers: create_trigger, add_trigger_condition, add_trigger_action, remove_trigger_condition, remove_trigger_action, and remove_trigger.

• Zones: create_zone_circle, remove_zone.

Route editing for a group created in the same patch requires a subsequent patch so the Mission Editor can finish constructing its route state. Editing or removing a unit created by add_unit, or a lead declared through create_group.lead_logical_id, likewise requires a subsequent patch because DCS allocates the final unit name in the operation result. Validation reports these as explicit barrier errors before any mutation is dispatched.

Preset-first aircraft workflow

For an armed aircraft, call get_aircraft_loadouts with aircraft_type and intended_task. Prefer a DCS-authored preset that declares compatibility with that task; when several match, choose the moderate, clearly named preset whose stores fit the mission and expected range. Request include_stations=true for the selected preset before any tuning. Apply it with set_unit_loadout, then use set_unit_payload or clear_unit_payload only for an explicit requirement the preset does not meet. A DCS named preset changes pylons only: compare the unit's inherited fuel/chaff/flare/gun values with the returned airframe maximum and countermeasure defaults, then set unsuitable values explicitly. Store-specific fuze/program settings are not yet part of the gateway's constrained patch schema.

Loadout enumeration is a gateway-owned read-only adapter over DCS Mission Editor me_loadoututils, not a formal DCS-SMS verb. It is therefore version-sensitive, fails closed if the Mission Editor API changes, and has been verified against the locally installed DCS build rather than claimed as a stable Eagle Dynamics interface.

For AI behavior, first call get_ai_task_catalog for the actual group and task kind, then describe_ai_task. EngageGroup/AttackGroup require a numeric groupId; unit variants require unitId; EngageTargetsInZone requires theatre-local x (north) and y (east). Use IDs from the current semantic snapshot. A task name alone does not make a valid target assignment.

Safety boundary

The underlying DCS-SMS bridge executes Lua in the full Mission Editor environment. This server restricts generated code to a fixed batch dispatcher and JSON/base64-serialized DCS-SMS verb calls. Keep it local, do not expose its stdio through an unauthenticated network service, and leave External execution disabled when it is not needed.

The offline validator and patch report do not use the DCS-SMS mailbox and do not require DCS to be installed or running. They establish structural and referential integrity only. They cannot prove that DCS will load the archive, normalize it identically on save, or that runtime AI, sensors, triggers, and weapons behave as intended; those remain explicit later acceptance layers.

License

MIT. DCS-SMS is a separate project; its tools/ tree is GPLv3.

Build a Windows release

The release builder compiles the gateway, installs only locked production npm dependencies into staging, downloads an official Node Windows distribution and verifies its published SHA-256, copies the exact compatible DCS-SMS bridge source and GPL text, inventories npm licenses, writes a per-file manifest, and produces a ZIP plus checksum:

npm run release:windows -- -DcsSmsSource C:\path\to\dcs-sms

Until the customized bridge 0.32.4 source is committed and published, releases must be built from the verified local DCS-SMS worktree. The generated payload/bridge/SOURCE.md records its base revision and whether the worktree was dirty; the full corresponding bridge source is inside the same package.