KingdomComeGlueMapper

Explore the world of Kingdom Come: Deliverance in Kingdom Come: Deliverance II.

An experimental world and gameplay converter built around the assets in your installed games.

Download setup · Installation guide · Feature checklist · Report an issue

KCD1 terrain, vegetation and water in the KCD2 engine. Earlier development capture; see the checklist below for current scope.

The project

KingdomComeGlueMapper reads compiled KCD1 and KCD2 archives, converts the original landscape and assets, and builds a separate region for KCD2. The combined setup packages the world, coach travel and supported gameplay conversions into one mod.

The goal is to preserve KCD1's authored world while using compatible KCD2 runtime systems. Buildings and terrain retain their source placement; interactions receive native contracts where implemented. Wildlife uses KCD2 models, animations and AI at converted KCD1 habitats.

• A world to explore: terrain, buildings, interiors, vegetation, roads, streams and original map detail.
• Growing gameplay support: seating, ladders, cooking, washing, harvesting, pickups, doors, selected services and wildlife.
• Local asset conversion: generated game content comes from your own installations and stays on your machine.
• Inspectable tooling: Python converters, dependency reports, regression tests and focused in-game experiments.

Project status

The main Rataje world is imported geographically. Complete KCD1 gameplay, campaign progression and every interactive object are still being converted. Separate source maps and every DLC or alternate quest state are not covered by a whole-game completion claim.

This page describes the current source and inspected development build as of 13 October 2026, checked against the build pipeline and converter code. Downloaded releases may predate features listed here; check their release notes. A current source implementation is not evidence that an older setup executable contains it.

The normal setup route is Continue a Trosky save → coachman → Travel to the Rattay region. The separate campaign-start experiments are developer work, not the normal installation route. KCD1 saves are not converted.

Getting started

Windows setup

1. Install both games. The setup currently accepts KCD2 1.5.6; this is enforced by its version check.
2. Download the Windows x64 setup executable from Releases.
3. Select both installations and a build folder outside the game directories.
4. Allow at least 90 GiB for building and 35 GiB on the KCD2 drive for installation staging. The setup combines the estimates when they share a drive; these are preflight requirements, not final mod sizes.
5. Close the games and choose Build and install.
6. Launch KCD2, continue a Trosky save and use the coachman's Travel to the Rattay region option.

The packaged executable includes its Python runtime. Python and the Modding Tools are not required to use the setup EXE. Installation targets Mods/kingdomcomegluemapper, verifies the generated package and backs up an existing recognized installation.

See the Windows setup guide for package-only builds, logs, cancellation, installation checks and rollback.

Run the current source

Use Windows and Python 3.14 for the setup development environment:

git clone https://github.com/SamG-Coder/KingdomComeGlueMapper.git
cd KingdomComeGlueMapper
python -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements-setup.txt
.venv/Scripts/python.exe tools/setup_app.py

To build a distributable setup executable:

.venv/Scripts/python.exe tools/build_setup_exe.py

The executable and self-test report are written to outputs/release. Developer engine probes additionally use the official KCD2 Modding Tools. Older build_*_probe.py commands are focused experiments with specific baseline requirements, not substitutes for the combined setup workflow.

Feature checklist

How to read this checklist: a checked item means the described conversion exists in the current code. It does not mean every instance has passed in-game acceptance. Unchecked items are remaining work, including validation of implemented features. Runtime evidence and limitations are stated separately.

World, terrain and rendering

• Convert compiled KCD1 terrain into the target terrain format, preserving height and surface assignments.
• Validate terrain samples, sector offsets and shared boundaries.
• Convert terrain materials and resolve texture families, streaming mips and available HD overrides.
• Import individual vegetation, instanced rocks/clutter and merged grass/ground cover.
• Import static buildings, interiors, props and supported level-local landscape geometry.
• Import initial/shared-state roads and decals.
• Repair legacy static-brush registration flags that hid ground meshes, steps and rocks.
• Convert building material features and repair supported secondary-UV blend inputs.
• Convert water volumes, stream surfaces and their material dependencies.
• Exclude explicitly later-state water from the initial world.
• Compensate the KCD1/KCD2 animation time-base difference for Waterfall shader materials.
• Convert interior probes, reflex lights, clipping associations and opacity voxels for basic GI.
• Register imported map imagery, detail layers and location information.
• Finish shallow mud-puddle surface appearance over imported ground.
• Complete broad roof/interior lighting, probe-boundary and material-fidelity validation.
• Validate collision, LOD transitions, streaming and traversal across the entire map.
• Convert supported initial-world particles, fog and ambient audio across the main KCD1 map, using native KCD2 effects and sound controls.
• Import original KCD1 adaptive music and bind registered settlement, inn, countryside, river and cave areas to the native KCD2 music system.
• Validate all music transitions by listening, including combat/dice outcomes, native-world return travel and remaining quest-driven states.
• Validate environmental appearance, audibility and boundary transitions throughout every region; restore unsupported legacy mixer behavior where a suitable native contract exists.
• Reconstruct quest-driven layer activation instead of selecting only the supported initial world.
• Extend conversion and acceptance to separate source maps and remaining DLC/world states.

Evidence: terrain/buildings/vegetation and selected ground repairs have in-game confirmation. Water-layer repair preserves retained records, and the flow-speed correction targets Waterfall materials specifically. It is not a universal adjustment to every water shader. Lighting conversion exists, but full visual parity remains open.

Interior exposure adaptation is corrected across the imported map's time-of-day profiles, with user confirmation in a sampled house. Broader lighting validation remains open; see interior lighting.

Environment coverage: the installed conversion includes 1,307 particle emitters, 21 fog volumes, 1,355 audio entities and 931 linked audio boundaries across the main map's selected initial world. Missing KCD1 sounds and reverbs use explicit native KCD2 equivalents; these are semantic substitutions, not identical recordings. The corrected build reaches gameplay, resolves all 1,190 nonempty imported play-trigger references in the live engine, and received user confirmation on 13 October 2026. This is map-wide conversion coverage, not inspection of every individual effect. Quest/later-state layers and separate maps remain outside this pass. See the environment conversion audit for exclusions, validation and the reserved player-ID fix.

Sources: terrain converter, static assets, brush repair, water selection, water timing, lighting, voxel packaging.

Music coverage: 119 original KCD1 scenes and 80 area bindings are installed for the main map's supported initial world. Runtime probes verify Skalitz, its inn, countryside, Rattay, Talmberg and leaving the imported-world boundary. Original town, pub and countryside scene playback is visible in the native debug overlay. Full listening acceptance, quest music and native-level return travel remain open. See the music conversion audit.

Everyday interactions and items

Container coverage: the installed development build registers 2,769 converted stashes and preserves nine shared personal chests. All 174 generated loot tables include registered item names and GUIDs (2,208 entries); the user confirmed starting-home fruit sacks work after this fix. Containers are temporarily unowned. Merchant/NPC-generated stock, campaign transfers, wearable fit and persistence remain separate acceptance work. See the container conversion audit.

• Convert authored chairs and benches to native seating contracts.
• Convert supported cooking fireplaces/pots to native player interactions and effects.
• Convert authored washing troughs, including helper alignment and cleaning effects.
• Register supported imported vegetation for native herb harvesting.
• Convert supported loose items and initially populated item slots into native pickups.
• Convert authored personal chests to persistent shared player storage.
• Convert active architectural doors, including native animation contracts, locks and keys.
• Add the selected Rattay inn rental, bed and room-service contract.
• Stage and install native storage for all 2,769 remaining initial-world stashes, including chests, sacks, bags, baskets, shelves and supply piles.
• Convert 174 authored inventory presets and resolve their 589 item types, including 312 additional KCD1 wearable components.
• Validate locks, keys, model changes, replenishment and save/load across the converted containers; restore ownership and theft rules when homes/NPCs are converted.
• Include fish traps, water/fish baskets and beehives in the native storage conversion.
• Validate their specialised behaviour, replenishment and interaction effects in game.
• Convert bird nests, contents, physics and associated sounds.
• Convert digging spots, graves and buried sacks, including tools, contents and dug-state persistence.
• Map all 1,387 active source beds to native sleeping contracts, including ground beds, shelters, tents and sleeping benches; preserve existing rental and miller beds.
• Restore original home/NPC access rules for newly converted beds and validate every bed family, approach side and save/load behaviour. New beds are temporarily usable without ownership restrictions.
• Convert all 113 ladders selected for the initial world to native climbing entities, preserving meshes, heights and approach settings.
• Validate top/bottom entry and exit at every ladder; convert the 26 deferred ladders when their quest layers are supported.
• Convert grindstone instances and verify sharpening effects.
• Convert alchemy benches and their complete activity contracts.
• Convert archery-target activities and dice-game locations.
• Complete book/recipe rewards, unmapped item effects and campaign-dependent item behaviour.
• Verify interaction state, item quantities and persistence after save/load and return travel.

Evidence: seating, herb picking, washing, loose-item pickup and the selected rental/bed fixes have sampled user gameplay confirmation. The inspected development level contains 274 washing triggers and 303 cooking groups; the pickup conversion report records 1,773 placements. These counts are coverage snapshots, not individual acceptance tests.

World beds: the development build adds 1,385 sleep contracts and preserves the two existing rental/miller beds. A sampled raised bed completed a one-hour native sleep cycle; a ground bed opened the native sleep menu with its lower comfort rating. Other families, placement clearance and save/load remain acceptance checks. See the bed conversion evidence.

Ladders: the installed development build contains 113 native ladder entities with their static duplicates removed. The user confirmed climbing works at the sampled test location on 13 October 2026. Other locations and NPC climbing remain separate acceptance checks.

Sources: chairs, benches, cooking, washing, herbs, pickups, player chests, doors, ladders, rental.

Wildlife and population

• Map supported KCD1 wildlife sites to native KCD2 animal definitions.
• Convert boar, red-deer stag, red-deer doe and roe-buck spawn sites.
• Convert forest/dynamic hare-area polygons and authored population overrides.
• Remap native scheduler dependencies, area links and positioning delegates.
• Register 229 wildlife sites, configuring 752 animals across supported populations.
• Package navigation for the imported destination.
• Provide character conversion and selected NPC placement, dialogue and activity integrations.
• Convert remaining regional wildlife contracts and livestock populations.
• Improve sparse hare encounters; the distributed-habitat experiment was rolled back after a loading crash. See the regional audit.
• Restore ambient fish groups and remaining ambient animals.
• Expand NPC population, household ownership and daily routines across the world.
• Verify wildlife hunting/loot, fractional-day respawn handling and save/load persistence.
• Validate navigation and activity selection at every habitat and settlement.

Evidence: runtime sampling found native boar, hare, red-deer doe/stag and roe-buck actors. Two boars changed position between samples. The 752 figure is configured population, not a simultaneous active-actor count. Hare areas use native regional populations rather than an exact reproduction of KCD1's player-centred spawning.

Sources: wildlife converter, wildlife scope and validation, navigation, character conversion.

Travel, services and campaign

• Build world conversion and coach travel into one installable mod.
• Register the imported destination and native level/gameplay lifecycle.
• Add selected Rattay, miller and horse-trader service integrations.
• Register a bounded set of native open-world gameplay graphs and audit dependencies.
• Provide source quest, dialogue and campaign dependency inspection/conversion tooling.
• Complete companion transfer and persistence acceptance through repeated round trips.
• Complete haggling and broader merchant/service coverage.
• Bind destination guards, crime, jail, punishment and escape locations.
• Convert teachers, bathhouses and remaining regional services.
• Complete original KCD1 quests, cinematics, voice/timing and campaign progression.
• Validate campaign-wide saving/loading and cross-region state preservation.
• Provide KCD1 save migration; no existing-save conversion is currently supplied.

Evidence: coach access, map display and selected retail services have recorded gameplay confirmation. Registering native combat, shop, repair or sharpening graphs does not establish every actor or world object is wired to them. The full original campaign remains unfinished.

Sources: combined setup backend, region builder, gameplay graph registration, campaign tools.

Quests and the original New Game opening

• Trace the original New Game entry and convert the opening movie for a development launch; the movie stage has user acceptance.
• Import the mother's original voice recordings, dialogue choices and character appearance into a native dialogue scene.
• Convert source scene markers into native dialogue-entry placement; both participants remain inside the house through the tested two-choice conversation and return to gameplay.
• Resolve the quest-graph loading stall and reconnect original objective callbacks and stat-reward bindings.
• Register original opening quest text and bind the quest to its native destination region; journal text and region have in-game acceptance.
• Add the development menu entry New Game Debug Sasau region below New Game, routing to the installed converted opening; user-confirmed menu operation.
• Verify all character-stat choice branches and prevention of repeated rewards.
• Restore remaining original gestures, lip-sync and starting-player equipment; validate every choice branch.
• Verify the complete movie → conversation → quest gameplay sequence, including movie skipping and save/load.
• Convert subsequent main, side and DLC quests with their actors, objectives, world changes, rewards and persistence.

Current boundary: the development test loads all 109 source objective states, awards both Speech choices, advances the original opening objectives and returns to gameplay with correct actor placement. Speech 7 survived a quicksave/reload without replaying the opening conversation. Opening journal text and region are now confirmed in game. Other stat branches, quest markers and subsequent interactions remain unverified; this is not a completed character-creation or campaign conversion. The ordinary setup still uses coach travel. See the quest conversion checklist for implementation milestones and per-quest acceptance requirements.

Packaging and quality

• Detect Steam installations and validate supported game versions.
• Offer package-only builds and installation of an existing verified package.
• Stage installation with receipt checks, backups and rollback handling.
• Retain build logs, progress events and conversion reports.
• Run asset-free regression tests and CLI checks in Windows CI.
• Build a Windows setup executable with a bundled-runtime self-test.
• Run a fresh complete build and retail acceptance pass for each release candidate.
• Complete whole-map visual and gameplay acceptance, including persistence and mod compatibility.

Current world-object audit

The following snapshot compares source mission/layer entities selected by the converter's initial-layer filter with the installed development level on 13 October 2026. Source identities are deduplicated. These are conversion targets, not instructions to force every quest-state object into the live world.

Area	Source audit	Current conversion gap
Storage	2,778 Stash entities	2,769 converted stashes registered at runtime; nine shared personal chests preserved. Sampled storage/fruit-loot tests passed; ownership, special-service contents and persistence remain open.
Fish traps	63 stashes using three fish-trap model types	Included in native storage conversion; water/fish baskets are additional variants. Specialised behaviour and replenishment remain unverified.
Nests	103	No converted nest registrations in the inspected level.
Digging	79 holes: 63 grave pits and 16 buried sacks	No converted digging registrations.
Ambient fish	41 fish-group entities	Separate from trap/container interaction; not converted.
Ladders	113	Converted to native climbing entities; sampled player test confirmed. Another 26 are deferred with inactive layers.
Grindstones	11	Global sharpening service registration does not activate these instances.
Alchemy benches	7	Complete native activity conversion remains.
Shooting targets / dice cups	8 / 13	Activity and participant conversion remains.
Beds	1,387	1,385 new native sleep contracts plus two preserved existing beds; 438 inactive-layer beds remain deferred. Family alignment and persistence validation remain.

Some KCD2 systems use different entity classes, so class counts alone are not proof of missing functionality. These gaps were cross-checked against the converter implementations. Counts describe the inspected source/build, not every game version or a published release guarantee.

Next priorities

1. Container acceptance and special storage: verify item transfer, locks, phase changes, wearable fit, replenishment and save/load; complete merchant/NPC-generated stock and campaign-driven storage contracts.
2. Nests and digging: add native interactions, contents, effects and persistent state.
3. World activities: validate bed alignment and restore ownership; extend sharpening, alchemy and minigames; validate ladder access throughout the world.
4. Population and ownership: expand NPCs, livestock, homes, schedules and regional services.
5. World parity and persistence: close visual gaps and verify save/load, travel, respawn and quest-state transitions.

Architecture and validation

Installed KCD1 archives + installed KCD2 reference assets
                         |
           Terrain / geometry / material conversion
                         |
          Native gameplay contracts and dependencies
                         |
             World + travel package verification
                         |
             Mods/kingdomcomegluemapper

The setup's conversion plan builds the world, packages its dependencies, calls the region builder for gameplay/travel, and combines the result. Source transforms and identities are retained or explicitly remapped; unsupported dependencies are reported rather than assumed compatible.

Entry point	Responsibility
setup_app.py / desktop_setup.py	Setup interface, preflight, build orchestration and installation.
setup_campaign.py	World packaging, registration and campaign-oriented developer commands.
region_travel.py	Destination lifecycle, travel, gameplay converters, lighting and wildlife.
travel_bridge_package.py	Combine world/travel packages and apply supported compatibility repairs.
tests / CI workflow	Regression checks, Python compilation and selected CLI entry points.

Run the test suite from the source environment:

.venv/Scripts/python.exe -m pip install -r requirements-test.txt
.venv/Scripts/python.exe -m unittest discover -s tests -v

CI currently checks Python 3.11 and 3.14 on Windows. It does not have the games installed and cannot verify appearance or gameplay. Local binary checks, frozen-executable checks, development-client tests and retail gameplay are separate validation steps.

Documentation and issue reports

• Setup, installation and rollback
• Wildlife conversion and remaining runtime checks
• World pickups · Herb harvesting
• Washing troughs · Room rental · World beds
• Gameplay-system dependencies
• Static-brush visibility repair · Water-layer selection
• Building material investigation · Water animation compatibility
• Historical world inventory · Development notes

Historical documents contain dated experiment results and commands. Use this checklist for current scope, the current code for implementation, and release notes for a particular downloaded build.

For a useful issue report, include the converter commit/release, game version, location or coordinates, a screenshot and reproduction steps. State whether the failure concerns appearance, collision, interaction or persistence. Attach relevant log excerpts or report files without distributing game archives.

Known visual follow-up: shallow mud puddles lose their wet surface over imported ground (#18). The physical-surface correction and the missing wet appearance are separate issues.

License and game content

The original tooling is released under the MIT license. Game assets, trademarks and screenshots belong to their respective rights holders and are not covered by that code license. Third-party tool notices are retained under third_party.

No game archives, extracted textures, meshes or generated world packages are distributed by this repository. Conversion requires your own installed games. KingdomComeGlueMapper is an independent experimental project, not an official Warhorse Studios or publisher release.