One world map for The Witcher 3 that map mods can share, and that you can build your own way.
Download on Nexus Mods · GitHub Releases · For mod authors · Report a problem
In The Witcher 3 only one mod's world map file can load at a time. Map mods used to ship their own copy of that file, so whichever copy won switched off the map features of every other map mod: quest markers from one mod, Gwent pins from another and a travel route from a third could never all show together.
Conjunction Map Framework (CMF) becomes the game's one map. Other mods no longer replace the map; they tell CMF what they want shown. CMF settles once, when your game loads, whose icon, colour or legend row wins each spot, and draws the result every time you open the map.
From 1.2.0, CMF does more than make map mods work together: you build your own map setup from the best parts of each mod. Take the quest icons from one mod, the shop colours from another and the map's look from a third, and change your mind whenever you like.
Tip
Ink & Iron on CMF's map. Ink & Iron's full map look, its "Lv N" quest tags and its smooth map movement all run on CMF's map, and from 1.3.0 the engraved world overview of its optional World Map file too. The same goes for the other mods under Supported map mods, including Map Quest Insight, Witcher's Path, Gwent Players Map, All Quest Objectives, Annoying Map and Map Remastered. CMF's own adapters do the proof-of-concept work, so none of these mods needed work from their authors for initial compatibility. The final check ran on a 175-mod everyday game, installed with RMMR.
flowchart LR
A[Quest marker mod] --> CMF
B[Gwent pins mod] --> CMF
C[Map theme mod] --> CMF
D[Icon pack] --> CMF
CMF((Conjunction<br/>Map Framework)) --> M[One world map<br/>with all of them]
Note
On its own, CMF changes nothing you can see. With only CMF installed, the map looks exactly like the game's own. What it becomes depends on the CMF-ready mods and adapters you install beside it.
Other map compatibility tools solve the same problem in their own ways, and many players have used them happily. CMF takes a different route.
- Build your own setup, feature by feature. With the optional in-game menu add-on you choose in Options which of your map mods wins each feature: pin icons from one mod, pin colours from another, the map's look from a third. From 1.4.1 a mod's map behaviour (how stacked pins spread out, how the info box moves) is chosen apart from its look, so one mod's icons can go with another mod's spreading. Change your mind at any time, with nothing to reinstall.
- Updates need no rebuild. CMF builds nothing ahead of time. Each map mod tells CMF what it wants shown when your game loads, so when one of your map mods updates, you install the update and play. There is no combined map to rebuild. At most, a mod that uses a CMF adapter may get an updated adapter, and once its author supports CMF directly, the adapter goes away.
- Mods stay as their authors ship them. CMF changes no other mod's files, and its adapters contain none of the mod they adapt.
- Why CMF
- For players
- For mod authors
- Repository guide
- Releases and checking a download
- Reporting problems
- Credits and licence
- The Witcher 3: Wild Hunt Remastered, Steam patch 5.01 (build 5.0.1048522), DirectX 12.
- Windows, or Linux with Steam and Proton: MateusAnd, the Gwent Players Map author, tested CMF 1.0.0 on Linux (keyboard and mouse); later versions have not been tried there yet. Steam Deck not confirmed.
- For each adapter: the mod it adapts, at the version named in the table below.
CMF comes as separate archives. You always need CMF itself; take the rest only for the mods you play with. The newest version of each file is on the Nexus Mods page and in GitHub Releases; each adapter's current version is in the Supported map mods table.
| Archive | What it is | When to install it |
|---|---|---|
mod0000_ConjunctionMapFramework |
CMF itself (1.12.2) | Always |
modCMFInGameMenu |
In-game menu add-on (1.12.2): choose in Options which map mod wins each feature, and see each map mod CMF finds on its Status page | Optional. See Good to know |
modCMFMinimapPanel |
Minimap add-on (2.2.0): your icon packs' icons and colours on the HUD minimap too, on top of whichever minimap you have | Optional. See Good to know for the minimap and HUD mods it was tested with |
modCMFCustomizer |
CMF Customizer (1.0.0, new): one options page for pin size, quest marker and undiscovered place (?) size, selected pin growth, icon labels and when each pin group hides by zoom | Optional; needs CMF 1.12.2. See Good to know |
modCMFExampleIconPack |
Sample icon pack: a small example for pack authors | Optional |
modCMFAdapter… (13 archives) |
Adapters for 13 map mods that don't support CMF yet, including the Map Icons - Remastered pack (new) | Only for those mods you use, and only until the mod's author updates it for CMF. See Supported map mods |
- Install CMF: copy its
Modsandbinfolders into your game folder and let Windows merge them. - Install your map mods as their authors describe.
- If one of those mods is in the adapter list below, add its adapter's
Modsfolder. Many map mods need no adapter at all, and an adapter is only needed until that mod's author updates it for CMF. - Optionally add the in-game menu add-on and the CMF Customizer (each with its
Modsandbinfolders) and the minimap add-on. None of them replaces a game file, so the minimap add-on goes in beside your HUD or minimap mod. - Start the game. The first start recompiles scripts and takes a little longer.
Every archive has a README.txt with its full install, update and removal steps. To remove CMF later, take out adapters and packs first, then the menu and minimap add-ons, then CMF. CMF writes nothing into your saves.
Many map mods work with CMF as they are, with no adapter. An adapter is a small stand-in for a mod that doesn't support CMF yet: it brings that mod's map features back on CMF's map while the mod itself stays exactly as its author ships it. Once the author updates the mod for CMF, you remove the adapter. Adapters contain none of the mod they adapt (only art its author gave for CMF, credited), add no features of their own, and only work with that mod installed: without it, the game stops at the script compile screen.
Two exceptions: the Coloured Map Markers adapter and the Map Icons - Remastered pack also show their icons without that mod installed. Both mods are map-file-only, with no scripts an adapter could check, and their authors' permission covers using their icons on their own. Keep Coloured Map Markers installed anyway if you like its minimap colours: it keeps colouring the minimap as before, and with the minimap add-on the adapter's icons show on top of that minimap too. Map Icons - Remastered likewise keeps its own minimap when installed.
| Mod | Tested version | Adapter | What the adapter brings back |
|---|---|---|---|
| All Quest Objectives On Map - Remastered | 1.2.1 | 1.2.0 | Difficulty icons on quest objectives, its legend row, removing cached merchant pins |
| Annoying Map | 3.1 | 1.0.0 (new) | Its remembered map: each region opens where you left it, at that zoom, and the zoom keys reach the full range. Its hiding of Geralt, Roach, the boat and herbs works with or without the adapter |
| Botanist - NG - Remastered | 3.0.0.2 | 1.0.0 | Its herb markers and legend rows |
| Coloured Map Markers | 1.60 (optional, see above) | 1.0.1 | Its coloured icons: 60 of the mod's own Shape icons on 61 pin types (merchants, places, points of interest open and completed, crafting spots), used with permission |
| Fog of War | 1.2.1 | 1.1.3, needs CMF 1.7.0 (1.0.2 for older CMF) | Hides every map icon under the fog, including other mods' icons (except Witcher Gear Map's markers with its Show Diagrams option on All), and draws its dark fog with a soft edge, in place from the moment the map shows (with CMF 1.8.0 also on the first opening after loading a save) |
| Gwent Players Map | 1.0.9 | 1.0.1 | Its card markers, in its author's own card art, and its "Gwent" tab |
| Ink and Iron - All in One | 0.8.10 (0.9.0 has the same scripts, not yet launched) | 1.2.2 | Ink and Iron's map look, quest level tags, key-hint row, map movement, its tall info box and its gold controller buttons (not yet tried with a real controller). With 1.2.0, also the engraved world overview and seven crests of its optional World Map file, in its author's own art, when you pick them in the menu |
| Map Icons - Remastered | 1.0 (optional, see above; tested without it) | 1.0.0 (new) | Its painted world map icons: kandy422's 138 pictures for shops, services, places, quest kinds, completed places, level badges and your own pins, in the legend too, and its seven flat region emblems on the world overview, used with permission. Needs CMF 1.5.0 or later for all of it |
| Map Pin Teleport | 1.2.2 | 1.0.0 | Teleporting from your own map pins |
| Map Quest Insight | 2.2.0; 2.1.0; 2.0.1 (2.0.0 not launched); 1.6.2 | 2.5.5 for 2.2.0 and 2.1.0, needs CMF 1.6.0 (1.6.3 for its key hints, 1.7.0 for its clean map edges, 1.8.0 to hide the tracker's key row, 1.9.0 for the full-height Quest List, 1.10.0 for the game's button pictures); 2.1.0 for 2.0.1; 2.0.0 for 2.0.0; 1.1.1 for 1.6 | Quest icons by type (main quest, contract and Gwent quest icons in its author's own art), coloured level labels, its info box, spreading stacked markers, its Ultrawide map and Side panels position settings. With 2.0 and adapter 2.0.0 also its round quest badges or symbols, Sticker icons, the quest box beside its marker, Show more, the full-screen map and its panel settings, following its own menu. With 2.0.1 and adapter 2.1.0 also its Quest List on the map and its Change tracked objective key. With 2.1.0 and adapter 2.2.0 also "Lv x-y" on its "Quests not started yet" markers, and the Quest List's Gwent section, Quests Available, Swap Obj and its other 2.1.0 settings. With adapter 2.3.0 and CMF 1.7.0, no dark bars stay under the tabs and button hints at the map's top and bottom edge. With adapter 2.4.0 and CMF 1.8.0, its Clean corner HUD also hides the tracker's row of keys; with Map Quest Insight 2.2.0 it follows Ultrawide map and Map side panels position (16:9, 21:9 or 32:9). With adapter 2.5.0 the Quest List and the Clean corner HUD are laid out as on Map Quest Insight 2.2.0's own map; with CMF 1.9.0 the list runs full height and hides the region title, the legend and the game's top bar while open. With adapter 2.5.1 its Quest Filters follow Map Quest Insight's order and symbols and change the map's markers at once, Quests Available follows the filters, and D-pad Right shows or hides a quest's objectives; with CMF 1.10.0 its keys and prompts use the game's own key and button pictures, on keyboard and controller. With adapter 2.5.2 a mouse click on a quest row's Objectives prompt shows or hides its objectives, a click on a fold prompt folds the section, and Only this region no longer redraws the map's markers. With adapter 2.5.4 and CMF 1.12.0 the info box beside a quest marker moves to the nearest clear spot when its place would cover the Quest List or a map panel. With adapter 2.5.5 and CMF 1.12.2, on a controller the Quest List moves one row per D-pad press, the left stick pans the map, A goes to the map when the crosshair is over a pin, and the highlighted row puts the crosshair on its pin |
| The Stable - Roach-Horse Customization | 2.2.1 | 1.0.0 | Its Stables row on the map |
| Witcher Upgrade Gear Map | 1.0.1 | 1.0.2, needs CMF 1.7.0 (1.0.1 for older CMF) | Its diagram markers, in its author's own art and school colours, its "Witcher Gear" tab and legend row; with Show Diagrams on All its markers show over Fog of War's fog, as without CMF |
| Witcher's Path | 1.0.3 | 1.0.0 | Its travel route drawn on the map, and its buttons |
Made for CMF by their authors: these mods support CMF themselves, with no adapter.
| Mod | By | On CMF's map |
|---|---|---|
| Seamless Adaptive HUD map icons, CMF editions 1.0.0: Heraldic, Wayfinder, Scratch, Runes | gehat | Each pack's own icons for 99 kinds of pins (places, services, completed places, quest kinds, the seven colours of your own pins). Needs CMF 1.5.0 or later. Install one pack only, and not with the same pack's map-file edition. An optional small file per pack draws the icons on the round minimap. Checked in their files and tested by gehat; not yet in our own test runs. |
Tested with no adapter needed, and mods that need their author's update
Tested, no adapter needed: Map Remastered 2.4.2, All Quest Markers, Wild Monster Hunt, Wolf's Bearing (1.0; 1.1 checked in its files, also beside the minimap add-on), Apocrypha Menu Framework 1.0.6, HUD Position Manager 1.0.0, Reveal Map POI, Reveal Map Icons - Remastered (to see their icons, set the map's legend filter to All or Exploration).
Checked in their files, no adapter needed, not yet seen in game: Show Chests on Map (Remastered) 1.7, Show Quests on Map (Remastered) 1.4, Gwent Card Finder, Malaombra's Map 1.3.0, and Configurable Minimap Zoom 1.1.2 (also beside the minimap add-on).
Ultrawide Menus 1.0.2 was tried beside CMF with its patcher run, and CMF's map loaded as usual. From 1.4.1 CMF's map fills wide screens by itself, so Ultrawide Menus is not needed for the map.
Not supported yet (needs its author's update): some map mods keep their map features, and often their icon art, inside their own copy of the world map file. CMF never copies another mod's art or files unless its author permits it, so those features stay hidden under CMF until the author updates the mod for CMF or gives permission for an adapter to use them. The mod's scripts and menus keep working meanwhile. Community Patch - World Map is in this group: everything it changes lives in its own map file, so CMF has no adapter for it.
Supports CMF itself: Smooth Map Remastered by Narcolepsy now supports CMF itself; its CMF version 1.1 is tested with CMF. Install it as its own page describes; it needs no CMF adapter.
The full, current list is on the Nexus Mods page.
Known differences
- Placeholder art in the All Quest Objectives and Botanist adapters, until those authors supply theirs. The Gwent Players Map and Witcher Gear Map adapters (1.0.1), the Map Quest Insight adapter (from 1.0.1), the Ink and Iron adapter (from 1.2.0) and the Map Icons - Remastered pack use their authors' own art. CMF ships another mod's art only when its author permits it, and credits them.
- Ink and Iron's World Map file art (the engraved world overview and crests) shows only when you pick Ink and Iron on the menu's World overview and Region crests and markers rows, or in the settings file: the game cannot tell whether that optional file is installed. Without it, change nothing.
- Fog of War's cloud pictures do not draw on CMF's map until Fog of War supports CMF. From adapter 1.1.1 (CMF 1.7.0) the fog shows as Fog of War's "cloud textures off" look: unexplored land dark, with a soft edge, following Fog of War's colour, opacity and edge settings. The hiding works with every adapter version.
- Show Chests on Map's optional white chest icon is written into the game's own files, so on CMF's map chests show the game's own chest icon (from its files, not seen in game).
- Gwent Card Finder beside the Map Pin Teleport adapter: Card Finder's pins show Map Pin Teleport's "Go Now" button, which most likely does nothing on them (from their files, not seen in game).
- Malaombra's Map: with its "names only on hover" option on, it also hides the quest level labels that CMF adapters draw (from its files, not seen in game).
- Ultrawide Menus: run its patcher, as its page says. Without it, its own map file loads ahead of CMF's.
- Choosing a pin type: when you hold the button to choose a pin type, the chooser still shows the game's icons, even with an icon pack that restyles your pins. A later CMF update draws it from the pack too.
- Map Quest Insight's Quest List comes with adapter 2.1.0 (Map Quest Insight 2.0.1) and 2.2.0 (Map Quest Insight 2.1.0). It sits between the map's region name and the legend, which CMF's map cannot hide yet; Map Quest Insight's own list covers the whole left side. With adapter 1.1.1 instead of 2.0.0 or later, Map Quest Insight 2.0's new map features do not show. Some "!" markers show no level: those are the game's own, which Map Quest Insight never labels, on its own map too.
- Left-aligned text under a centred title in a marker's info box comes from Map Quest Insight's "Format all marker descriptions" with its Journal text alignment set to Left (its default). Set the alignment to Centred, or switch that option off.
- Map Remastered's own region emblems on the world overview do not show; its redrawn terrain does. The Map Icons - Remastered pack brings kandy422's flat emblems.
- Map Icons - Remastered's completed places (cleared monster nests, bandit camps and the like) are drawn very dark in its own art, and the pack keeps them that way.
- Witcher's Path: its speed setting does nothing under CMF.
- World Map Merger is not compatible with CMF, by design: it merges map mods into a map file of its own, which loads in place of CMF's map. Use one or the other.
- Map Pin Teleport: the "Go Now" texts are English, as in the mod itself.
- Per-mod details are in each adapter's
README.txtand in the release'stest-notes.md.
- The in-game menu add-on (1.12.2) is optional. With
modCMFInGameMenuinstalled, Options > Mods > Conjunction Map Framework lets you choose which of your map mods wins each feature.- Mod order ranks your map mods once; Basic choices has one row per feature (pin icons, pin colours, legend, map look, map behaviour, map movement and more); Advanced choices splits a feature further, such as quest icons from one mod and shop icons from another; Status shows which mod wins each piece now, and why.
- Every row starts on Automatic, which keeps CMF's usual winner and names it in brackets. Vanilla uses the game's own look; or pick one of your loaded map mods.
- Highlight a row and the help box, just above the list, says in plain words what that row changes on the map, for example "Makes the map's pins bigger or smaller." On a choice row the next line names every loaded map mod that offers it, for example "Offered by: Botanist, Map Quest Insight". Some offers are known only after the world map has been opened once in a session, and the box says so until then.
- At the title screen, before a save is loaded, the choice rows and Mod order rows show your choices greyed and cannot be changed. Load a save to change them. Reset on the General page still works there.
- With CMF 1.3.0 or later, Advanced choices also has World overview, Region crests and markers and Opening view rows, with their Who wins rows.
- With CMF 1.6.0, Advanced choices also has Pin place and draw order, Map sounds, Pictures under pin icons, Pin highlights and glow, Info box motion, Info box folding, Panel visibility and Pin zoom range, each with its Who wins row; "Info box height and scrolling" is now "Info box size and scrolling". Status > Loaded map mods lists your map mods in the order that decides who wins.
- With CMF 1.7.0, the General page also has Animated pins (Off, 10, 15 or 30 redraws a second, default 15), Stop animation during drag (default On) and Animation memory (32, 64 or 128 MB, default 64; pictures past the limit show still).
- With CMF 1.8.0, Basic choices has The map (how much of the screen the map fills, where it sits and its backdrop), apart from Frames and panels, which now covers only the frames and panels around the map and the frame drawings a mod adds to them. So one mod's map can go with another mod's frames, for example Ink and Iron's map with Map Quest Insight's quest tracker. Panel visibility decides whether a panel, or a part of it, shows, whatever look you picked.
- With CMF 1.9.0, Status > Loaded map mods lists each map mod CMF can find, including mods that never tell CMF they are installed, says Needs its adapter when an adapted mod's CMF adapter is missing, and the Screen row shows your screen's shape (16:9, 21:9, 32:9).
- From 1.3.0 the Basic row Map behaviour, with its own Advanced and Who wins pages, covers how stacked pins spread out, which pin leads a spread, label place and hiding, how the info box moves out of the way, its height and scrolling, and names only on hover. CMF adds no behaviour of its own: each one comes from a map mod. "Pin size and spreading" is now "Pin size", and "Pan and zoom" is now "Pan and zoom feel", with Zoom out to the whole region, Controller crosshair and Fill wide screens as their own rows. Picks made in 1.2.0 on the three rows that moved under Map behaviour count as Automatic again.
- Menu add-on 1.5.0 and 1.6.0 need CMF 1.5.0 or later, 1.7.0 needs CMF 1.7.0, 1.8.0 needs CMF 1.8.0, 1.9.0 needs CMF 1.9.0, and 1.10.0 needs CMF 1.9.0 or later; with an older CMF the game stops at the script compile screen, so update CMF first. With CMF 1.5.0, menu 1.6.0 leaves out the new rows.
- With menu add-on 1.12.2, each Status row shows its value in its own label, so the values stay readable with Ink and Iron's options menu.
- The more specific choice wins: Advanced beats Basic, and Basic beats Mod order. No restart is needed: the minimap add-on follows as soon as Options closes, and the world map the next time you open it.
- Hidden pins add up: every mod's hides apply, unless you keep only one mod's, none (Vanilla), or leave out up to three mods.
- Without the add-on every choice is Automatic, and choices it left behind are ignored. The same choices can also go into
dx12user.settingsby hand, with the game closed:CMFFile_…lines under a[CMFSettings]heading (add the heading if it is missing), listed in CMF'sREADME.txt.
- The CMF Customizer (1.0.0) is optional and new. With
modCMFCustomizerinstalled, Options > Mods > CMF Customizer sets pin size, "Standardize icon sizes", quest marker size, undiscovered place (?) size, selected pin growth, icon labels (Always, Never, On hover) and, for each pin group, when it hides by zoom. Every row starts at Off and then sends nothing. Its choices count as your own settings: they win over other map mods' choices, and your picks in CMF's own menu still come first. It needs CMF 1.12.2. - A missing adapter is easy to spot. CMF warns once per session when another mod's map file loads instead of CMF's. With the in-game menu add-on 1.9.0 or later, Options > Mods > Conjunction Map Framework > Status > Loaded map mods marks each known map mod installed without its CMF adapter with Needs its adapter. The adapter check add-on (
modCMFAdapterCheck) is retired: deleteMods\modCMFAdapterCheckandbin\config\r4game\user_config_matrix\pc\modCMFAdapterCheck.xmlif you have them. - Wide and tall screens. From 1.4.1 the map fills 21:9, 32:9 and 16:10 screens instead of showing a 16:9 picture with dark sides, and its panels and button hints move to the screen's edges. On a 16:9 screen nothing changes. A map mod can switch this off or set it its own way; the menu's Fill wide screens row (Advanced, map movement) picks whose way wins, and Vanilla keeps the 16:9 map. Tested at 21:9 (3440 x 1440) and 16:10 (1920 x 1200); 32:9 has not been tried yet.
- When two mods want the same spot, a "hide" beats any icon or colour; otherwise, with nothing chosen, the mod whose folder name sorts first wins. Your mod manager's load order does not change this. To pick a winner without the menu add-on, list folder names in
Documents\The Witcher 3\dx12user.settings(details in the author guide, section 11):[CMFSettings] CMFProviderOrder1=modMyFavouritePack CMFProviderOrder2=modOtherPack
- When a mod ships its own CMF support, uninstall CMF's adapter for it. With both installed, the game stops at the script compile screen.
- The minimap add-on (2.2.0) replaces no game file. It adds its own small HUD part on top of whichever minimap is installed and draws your icon packs' art on the pins a pack claims. It never moves, resizes or hides the minimap, and pins no pack claims stay as your minimap draws them.
- Tested with the game's own minimap, HUD Position Manager 1.0.0, Ink and Iron 0.8.10, Map Remastered 2.4.2 and Coloured Map Markers 1.60, and removed cleanly after each. Other minimap and HUD mods have not been tried with it yet.
- On the minimap it changes pins by type only. A pin type a pack hides everywhere (every notice board, say) is hidden there too, though a quest ring or glow the minimap draws round it can still show (the hide was tested on Ink and Iron 0.8.10's minimap). A pack's change to only some pins of a type (one particular notice board, or every pin except quest ones) shows on the world map only.
- A pin animated on the world map shows its still picture on the minimap (2.2.0, needs CMF 1.7.0).
- Coming from an older add-on: 2.2.0 replaces 2.1.0, 2.0.0 or 1.0.0 in the same
modCMFMinimapPanelfolder. Unlike 1.0.0, it no longer has to stay away from other minimap mods.
- Do not give another map mod a lower
Prioritythan CMF inmods.settings; that switches CMF's map off. - The map moves at 60 frames per second by default.
Important
Not tested: the Steam Deck, and a real controller before CMF 1.12.2. CMF 1.12.2 was tested on Windows on game build 5.0.1090142 with keyboard and mouse and a real controller, with 39 mods including the Ash & Quill icon packs, Map Quest Insight 2.2.0, Ink and Iron and the CMF Customizer, at 16:9, in several starts and one start on the release archives themselves; ultrawide screens, the new settings with a mod other than the CMF Customizer, Vortex and Mod Organizer 2 were not tried with it. The controller changes were first reported by a player, who has not yet tried the public build. CMF 1.12.0 was tested on Windows with keyboard and mouse on game build 5.0.1090142 with 37 to 38 mods including the Ash & Quill icon packs, Map Quest Insight 2.2.0, All Quest Objectives, Ink and Iron, Fog of War and Witcher Gear Map, in three starts and one start on the release archives themselves; a real controller, ultrawide screens, Vortex and Mod Organizer 2 were not tried with it. CMF 1.11.2 was tested on Windows with keyboard and mouse on game build 5.0.1090142 with 37 mods including the Ash & Quill icon packs, Map Quest Insight 2.2.0, All Quest Objectives, Ink and Iron and Fog of War, in several starts and one start on the release archives themselves; a real controller, ultrawide screens, Vortex and Mod Organizer 2 were not tried with it, and the All Quest Objectives adapter's support for The Stable (1.2.0) was checked in code only. CMF 1.11.0 was tested on Windows with keyboard and mouse on game build 5.0.1090142 with 37 mods including the Ash & Quill icon packs, Map Quest Insight 2.2.0, Ink and Iron and Fog of War, at 16:9, in several starts and one start on the release archives themselves; a real controller, ultrawide screens, Vortex and Mod Organizer 2 were not tried with it. CMF 1.10.0 was tested on Windows with keyboard and mouse on game build 5.0.1090142: six starts with Map Quest Insight 2.2.0 alone, then one start on the release archives themselves with 31 mods including the Ash & Quill icon packs, Map Quest Insight 2.2.0 and Fog of War, at 16:9; a real controller, ultrawide screens, Ink and Iron, Vortex and Mod Organizer 2 were not tried with it. CMF 1.9.0 was tested on Windows with keyboard and mouse on game build 5.0.1090142 with 31 mods including the Ash & Quill icon packs, Map Quest Insight 2.2.0 and Fog of War, at 16:9; Ink and Iron, ultrawide and 4:3 screens, Vortex and Mod Organizer 2 were not tried with it. CMF 1.8.0 was tested on Windows with keyboard and mouse with 33 mods including Ink and Iron, the Ash & Quill icon packs, Map Quest Insight 2.2.0 and Fog of War, at 16:9 and 21:9; 32:9 and 4:3 screens, Vortex and Mod Organizer 2 were not tried. CMF 1.7.0 was tested on Windows with keyboard and mouse with 32 mods including Ink and Iron, Map Quest Insight 2.1.0 and Fog of War, plus a stress pack of 80 animated pins; 32:9 and 4:3 screens, Vortex and Mod Organizer 2 were not tried. CMF 1.6.0 was tested on Windows with keyboard and mouse at 16:9 and 21:9, with Map Quest Insight 2.0.1 and its adapter 2.0.0, Ink and Iron and its adapter, the menu add-on and the adapter check; the Fog of War adapter 1.0.2 is checked in its code only. CMF 1.4.1 was tested on Windows with keyboard and mouse at 16:9, 16:10 and 21:9, with Map Quest Insight 1.6.2 and its adapter. CMF 1.3.0's controller button pictures were seen through a test copy of the map, not yet with a real controller. CMF 1.0.0 and 1.1.0 were tested on Windows with keyboard and mouse, both with the files copied in by hand and installed with RMMR in a full, everyday game setup. CMF 1.2.0 and the in-game menu add-on were tested on Windows with keyboard and mouse with Ink and Iron, Map Quest Insight, Coloured Map Markers, Gwent Players Map and Witcher Gear Map and their adapters, not yet in a full everyday setup. CMF 1.3.0, the menu add-on 1.2.0 and the Annoying Map and Ink and Iron adapters were tested on Windows with keyboard and mouse beside 27 mod folders, in three starts: test packs with placeholder art, Annoying Map with its adapter, and Ink and Iron's art. On Linux (Steam with Proton, keyboard and mouse) MateusAnd, the Gwent Players Map author, tested CMF 1.0.0 with the Gwent Players Map, Witcher Gear Map and Map Pin Teleport adapters: scripts compiled, the game started, and every adapter feature worked.
CMF lets your mod change the world map without shipping a map file: no decompiling Flash, no Script Merger, no compatibility patches for other map mods. Your mod calls CMF from its own scripts, and works beside every other mod that uses CMF.
Three rules shape everything CMF offers:
- Abilities, not special cases. Every ability is one general call that takes its target as an argument. CMF has no calls made for one particular mod, and names (pin types, tags, tab ids, folder names) are open, so your mod can style a pin another mod added.
- Clear winners. When two mods ask for the same thing, a hide wins; otherwise the folder name that sorts first wins, unless the player picks a winner, for a whole mod or one feature at a time. CMF settles this when the game loads, and again when the player changes a choice.
- The version number is a promise.
CMFGetVersion()returns CMF's script interface version (19 from 1.12.2), not a release number. Nothing is removed from 1.0.0 on; later versions only add.
| Ability | Since API version | Guide section |
|---|---|---|
| Pin icons, legend icons and colour tints, for a whole pin type or one pin by its tag | 1 | The CMF calls |
| Replace a map area's background image | 1 | The CMF calls |
| Grey out pins (looks only, they stay usable) | 1 | Greying pins |
| Your own legend rows and filter tabs | 2 | Legend rows and filter tabs |
| Style a single pin as the map builds it | 2 | Styling one pin |
| Hide pins, with exemptions for tracked, quest and fast travel pins | 3 | Hiding pins |
| Pin size, pin labels, the info box height, hiding pins in a filter tab | 4 | Pin size, labels and the info box |
A hook on every pin as the map builds it (CMFCore.OnPinReady) |
4 | The pin hook |
| Key hints and filter tab reports | 4 | Key hints |
| A full map theme: frames, fonts, colours, legend and backdrop | 5 | The map theme |
Info box extras for themes: a drawing that shows only while the box is tall (minPartHeight), and a tall box moved beside the cursor, clear of the other panels (the clear… keys) |
7 | Theme parts and keys |
| Pin clicks handed back to your script, with button text | 6 | Pin clicks |
| Smooth map movement | 6 | Smooth map movement |
| Spreading stacked pins apart | 6 | Spreading stacked pins |
| Drawing lines and images on the map itself | 6 | Drawing on the map |
A tidy name for your mod in the player's in-game menu (CMFSetProviderName) |
8 | API reference |
| The world overview: its painting (one picture or tiles), region crests and markers | 9 | World overview pictures |
| Controller button pictures on the map | 9 | Controller button pictures |
Where the player left the map (CMFCore.OnMapView), and the view a region map opens with (OnMapOpening, CMFSetOpeningView) |
9 | The map's view |
Pictures that show only when the player picks your mod (CMFRegisterChoiceOnly) |
9 | Choice-only claims |
Hiding Geralt's marker (a hide on 'Player') |
9 | Hiding pins |
Filling wide and tall screens your own way (the theme part wide), and the screen size (CMFScreenWidth, CMFScreenHeight) |
10 | Wide and tall screens |
| Names only on hover (property 28) | 10 | Names only on hover |
Showing the map's panels as soon as it starts fading in (readyAtFadeStart) |
10 | Map movement |
| Changing one pin: its colour, info box title, text and height, "?" and cleared-place art, level variants, Geralt's arrow and player markers, moving the game's legend rows, hiding a whole tab | 11 | API reference |
Telling CMF your mod is there (CMFDeclareProvider, CMFProviderPresent), so the Status page knows |
11 | API reference |
A tall info box placed by your own rules (the tall… keys); the info box height claim now only makes long text scroll |
12 | Theme parts and keys |
Your own pins for the session (CMFAddPin, CMFRemovePin) |
13 | API reference |
| Per pin: selected art and size, opacity, draw order, offsets, zoom range, pictures under the icon (badges) and their tint, the picture's size without the game's glow, the info box width, and withdrawing one claim | 13 | API reference |
Styling one legend row, tab, pin or area's title (CMFStyle), reacting to a tab switch (OnMapTab), your own key hints on the map (OnMapHints) and "Show more" folding in the info box (OnInfoFold) |
13 | Key hints and filter tab reports |
A picture or your own movie over the map (CMFDraw with a movie) |
13 | Your own movie on the screen |
| Moving pin pictures: a pin's picture and the picture under it animated, moving and still pins mixed on one map | 14 | Animated pictures |
| Picture fit: icons of every shape filling one box (property 48) | 14 | Pin size, labels and the info box |
Shading areas of the map cell by cell (a grid drawing, CMFDrawSetBits, CMFGridKeepPin), in place from the first moment the map shows |
14 | Drawing on the map |
| Theming the legend's Quest and Custom marker rows, even with no pin placed | 14 | Legend rows and filter tabs |
| The map (its size, position and backdrop) as a choice of its own, apart from the frames and panels | 15 | Who wins each feature |
| Drawings on a panel go with that panel's look winner | 15 | Theme parts and keys |
Showing or hiding a panel or part of it (show, the tracker's nokeys) as behaviour, under Panel visibility |
15 | Theme parts and keys |
Your own movie hiding parts of the map while it shows (map.hidePanels: legend, title, tracker, preview, world button and hint, the game's top bar hubBar) |
16 | Your own movie on the screen |
The game's own key or button picture in your own movie (map.cmfMakeButton, CMFHasAbility('screen', 'button')), switching between keyboard and controller |
17 | Your own movie on the screen |
Redrawing the open map's pins after your mod's settings change (CMFMapRefreshPins(), CMFHasAbility('map', 'refreshPins')) |
17 | API reference |
Letting a key through your own movie to the map: handleInput returns false (CMFHasAbility('screen', 'keyDecline'), CMF 1.11.0) |
17 | Your own movie on the screen |
The map keeps unchanged pins on a redraw, nothing to call (CMFHasAbility('map', 'partialUpdate'), CMF 1.11.0) |
17 | API reference |
| A choice that is the player's own setting (property 50), winning over other mods' choices but not over the player's picks in CMF's menu | 19 | Player settings and size |
| Size multipliers for a pin type, a tag or every pin, and for a selected pin (properties 51 and 52), and "Standardize icon sizes" (property 53) | 19 | Player settings and size |
A minimal pack, the whole script:
@wrapMethod(CR4Game)
function OnGameStarted(restored : bool)
{
var result : bool;
result = wrappedMethod(restored);
if (CMFRequireVersion("modAcmeIcons", 1))
{
CMFRegisterIcon("modAcmeIcons", 'Innkeeper', "img://icons/modacmeicons/innkeeper.png");
CMFRegisterTint("modAcmeIcons", 'Herbalist', 4259648); // 0x40FF40, lime green
}
return result;
}The same pattern as the sample icon pack's script. tools/cmf_pack.py skeleton writes the start-up script for your own pack.
Warning
Calling a CMF function that the installed CMF does not have stops the game at the script compile screen. Check with CMFHasProperty(id) or CMFRequireVersion(provider, version) before using anything newer than the version your mod requires, and never name your own functions with the CMF prefix.
- Copy
examples/modCMFExampleIconPackand rename the folder, for examplemodAcmeIcons. - Put your PNG icons in its
art/folder. - Run
python tools/cmf_pack.py skeleton path/to/modAcmeIconsand paste what it prints into your start-up script. - Write the player
README.txtfrom the template. - Run
python tools/cmf_pack.py build path/to/modAcmeIcons --out path/to/out, fix anything it reports, and copy theModsfolder it writes into the game.
The pack tool needs only Python 3 and its standard library. It checks your art and script and builds the texture cache the game reads.
| Document | What is in it |
|---|---|
| Mod author docs | Start here. The guide as short pages, one per ability, with an API reference |
| Author guide | Everything: art, every CMF call by API version, building, testing, shipping, settings and text, what CMF does not do yet |
| Pin types | All 162 pin type names of the 5.01 world map, with their legend tab and what a claim on each changes |
| Porting pages | One page per adapted mod: "you used to do this; now call these CMF functions" |
| Script-side map bindings | Advanced: the callbacks and values that pass between scripts and CMF's map |
New to CMF? Start at the mod author docs: the same guide split into short pages, one per topic, from what you want to change to getting started and a full API reference.
The adapters are teaching examples, written as the code that mod's own author would add. If your mod has one, its porting page shows the CMF calls that give the same result once your mod supports CMF itself. Fold them into your mod (CMF then becomes a requirement), and the standalone adapter is retired: players uninstall it and use your release.
| Your mod | Porting page | Adapter source |
|---|---|---|
| All Quest Objectives On Map - Remastered | page | source |
| Annoying Map | page | source |
| Botanist - NG - Remastered | page | source |
| Fog of War | page | source |
| Gwent Players Map | page | source |
| Ink and Iron | page | source |
| Map Pin Teleport | page | source |
| Map Quest Insight | page | source |
| The Stable | page | source |
| Witcher Upgrade Gear Map | page | source |
| Witcher's Path | page | source |
The Coloured Map Markers adapter and the Map Icons - Remastered pack have no porting page: those mods have no scripts, so each is only their icons registered with CMF (Coloured Map Markers source, Map Icons - Remastered source).
Smooth Map now supports CMF itself: see Smooth Map Remastered by Narcolepsy. Community Patch - World Map has a porting section in the author guide, section 12; no adapter ships for it.
What is where
| Path | What |
|---|---|
source/core |
CMF's scripts (cmfCore.ws, cmfSettings.ws) |
source/settings, source/strings.json |
CMF's menu file and the source of its string tables |
source/panel |
the edit sets CMF applies to the game's world map panel, and CMF's own ActionScript classes |
source/menu |
the in-game menu add-on: its script, menu file and string source |
source/addons/customizer |
the CMF Customizer add-on: its script, menu file and string source |
source/minimap |
the minimap add-on: its script and its own HUD part's ActionScript class |
source/adapters |
the 12 adapters, one folder each, with a developer README.md and the shipped pack folder |
examples/modCMFExampleIconPack |
the sample icon pack, to copy from |
source/providers |
developer test packs (never shipped) |
docs/authors, docs/api |
the author guide, pin type list, porting pages and map bindings |
tools |
build tools: packs, panels, string tables, releases |
tests |
unit tests for the tools and the shipped scripts |
source/releases |
release notes and the release spec |
Building and testing
Python 3 runs the tools and tests:
python3 -m unittest discover -s tests
python3 tools/cmf_pack.py build source/adapters/gwent-players-map/modCMFAdapterGwentPlayersMap \
--out build/gwent --adapts modGwentPlayersMapEvery shipped adapter and the sample pack rebuild from this repository byte for byte equal to the release archives. Rebuilding the world map panel itself needs the game's own panel file and FFDec; see tools/cmf_pin_panel.py.
Branches
mainholds published releases only, one tagged commit per version (v1.0.0, ...).developis where work lands; a release is a merge ofdevelopintomain.
Each version has a GitHub Release with the same archives as on Nexus Mods, plus SHA256SUMS, test-notes.md (how it was tested and what was not) and rollback-notes.md (removing it or going back).
To check a download in PowerShell, in the folder with the archive:
Get-FileHash .\mod0000_ConjunctionMapFramework-1.12.2.zip -Algorithm SHA256The result must equal that file's line in SHA256SUMS.
Report bugs on the Nexus Mods page's Bugs tab, or open an issue here.
Please include your CMF version, the map mods and adapters you have installed, and the CMF lines from your script log if you have one.
Made by Kyle with the help of AI tools (Claude and ChatGPT). Every published file is reviewed by Kyle.
Card and gear art in the Gwent Players Map and Witcher Gear Map adapters by MateusAnd, the author of both mods, used with permission. Thanks to MateusAnd for testing CMF on Linux.
World overview painting, region crests and gold controller button pictures in the Ink and Iron adapter by WinterElfeas, the author of Ink and Iron, used with permission.
CMF's smooth map movement and quicker map opening are built on the work of Narcolepsy, the author of Smooth Map: much of that code in CMF's map file follows Smooth Map's.
Main quest, contract and Gwent quest icons, Sticker icons, round badges and quest type symbols in the Map Quest Insight adapter by Wolfer, the author of Map Quest Insight, used with permission; adapters 2.0.0 to 2.5.5 carry Map Quest Insight 2.0's, 2.1.0's and 2.2.0's map features with Wolfer's permission.
Icons in the Coloured Map Markers adapter by DJ_Kovrik, from Coloured Map Markers (maintained by LewisElementary), used with permission under the mod's compatibility notice. The adapter is not made by DJ_Kovrik or LewisElementary; questions about it go to CMF's page.
Icons and region emblems in the Map Icons - Remastered pack by kandy422, from Map Icons - Remastered, used with permission. The pack is not made by kandy422; questions about it go to CMF's page.
Thanks to the authors of the map mods CMF adapts. Their mods stay theirs; CMF's adapters contain none of their files, and their art only where the author gave it for CMF, credited.
Licence: Creative Commons Attribution-NonCommercial 4.0 (CC BY-NC 4.0), full text in LICENSE. Anyone may copy, change and share CMF, including inside their own free mods, as long as they credit Kyle and do not sell it or use it commercially.
This is an unofficial fan work and is not approved/endorsed by CD PROJEKT RED.