TOBI`S KARTENGENERATOR 0.3.6 BETA 1 HF1
USER GUIDE - ENGLISH
====================================

1. PURPOSE OF THE APPLICATION
-----------------------------

Tobi`s Kartengenerator creates empty, editable maps for Panzer Corps 1.
The following target modules are available:

- Modern Conflicts
- PAK Mod
- Panzer Corps Original

The generated map contains terrain, water, settlements, sites, roads and
railways. It intentionally contains no units, victory conditions, triggers,
events, deployment hexes or complete mission logic yet. Final scenario work
must therefore be completed in the appropriate Panzer Corps Editor.


2. SYSTEM REQUIREMENTS
----------------------

- Windows 11 (target system)
- Windows 10 compatibility is additionally being tested with BETA 1 HF1
- Windows PowerShell 5.1
- Panzer Corps 1 and the Editor for the selected target module
- no Python required
- no internet connection required

Extract the complete application folder before starting the program.


3. STARTING THE PROGRAM AND SELECTING A LANGUAGE
------------------------------------------------

German start:
  Start_MC_Kartengenerator.bat

English start:
  Start_MC_Map_Generator_EN.bat

The upper-right corner must display "Version 0.3.6 BETA 1 HF1". The interface
language can be changed during operation through "Sprache / Language".

The default output folder is:

- German interface: Karten
- English interface: Maps

If the user selected a custom output folder, changing the interface language
does not alter that folder.


4. SELECTING THE TARGET MODULE
------------------------------

The highlighted "SELECT TARGET MODULE" control determines which Editor will
receive the generated map.

Modern Conflicts
  Uses the proven MC writer and confirmed MC overlays.

PAK Mod
  Uses the tile and overlay deviations confirmed through controlled PAK Editor
  references.

Panzer Corps Original
  Uses classic PC1 base tiles. MC and PAK overlays are ignored in this mode;
  every overlay field is written with value 0.

Important: Always open the map in the Editor matching the selected target
module.


5. PROJECT, MAP SIZE AND SEED
-----------------------------

Map name
  Determines the file and scenario name. Unsupported special characters are
  replaced with underscores during export.

Output folder
  Displays the destination for the finished PZSCN and PZLOC files. Use
  "Browse" or "Choose output folder" to select a custom folder.

Map width and map height
  Determine the size of the map in hexes.

Random seed
  The same seed reproduces the same map geometry when all settings are equal.
  "New seed" creates a different random number.

Project file
  "Save" stores the current settings as an MCMap project file. "Open" loads
  such a project again.


6. MAP TYPE AND LANDSCAPE PROFILE
---------------------------------

The map type controls the basic shape, for example Continent, Coast,
Archipelago, Lake district, Mountain region, Desert or Mixed.

"Apply map-type profile" loads suitable base settings for the selected map
type and resets the landscape profile to Standard.

The landscape profile controls a typical distribution and cluster shape, for
example:

- Open Eastern Europe
- Eastern Europe - forest/swamp
- Mountains & passes
- North Africa - desert
- Coast / island

"Apply landscape profile" enters all values belonging to that profile
automatically. Other values do not have to be set to 0 first. Individual
settings may still be adjusted manually after applying the profile.


7. TERRAIN, WATER, SETTLEMENTS AND SITES
----------------------------------------

The setting tabs control the amount and distribution of map elements. Terrain
percentages refer to usable land. Any share not allocated remains open base
terrain.

Settlements and airfields are kept outside the three locked rows along the map
edge. On large maps, airfields are distributed approximately 14 to 16 hexes
apart whenever possible. Smaller maps use an automatically reduced distance.

Ports are placed only at usable coast positions whose graphics are confirmed
for the selected target module. If no suitable position exists, the generator
reports a note instead of forcing an incorrect port graphic.


8. RIVERS, ROADS AND RAILWAYS
-----------------------------

Small and large rivers have separate count and target-length settings. A river
length of 0 means automatic length. Rivers receive varied directions, bends
and separation; long parallel courses are avoided whenever possible.

Roads and railway lines are generated as through networks. They may not end in
the map interior and receive connections to the map edge.

HF2 corrects technical validation of desert-road graphics beneath settlements
and fortifications. Earlier builds could report these graphics as invalid even
though the PC1 Editor opened and displayed the map correctly.


9. GENERATING AND VALIDATING A MAP
----------------------------------

1. Enter all required settings.
2. Click "Generate map".
3. Inspect the preview and statistics.
4. If necessary, change settings or the seed and generate again.
5. Click "Validate".

The preview and full validation text remain inside the application and are not
written as files automatically.


10. EXPORTING PZSCN AND PZLOC
------------------------------

After a successful check, click "Export PZSCN + PZLOC".

Example with the English interface and map name W_ste:

  Maps\W_ste\W_ste.pzscn
  Maps\W_ste\W_ste.pzloc

The map folder contains only these two generated files:

- PZSCN: the actual empty Editor map
- PZLOC: scenario, side and settlement text

MCMap projects, preview PNGs, scenario images, validation reports and ZIP
archives are no longer exported automatically. Existing files in a custom
folder are not deleted for safety.


11. SAVING A PROJECT
--------------------

To edit the configuration again later, click "Save" on "Project & Size".
The MCMap file is stored in the "Projekte" folder by default. It is not one of
the two finished map files and is therefore not included in automatic export.


12. CONTINUING IN THE PANZER CORPS EDITOR
-----------------------------------------

1. Open the PZSCN in the matching Editor.
2. Inspect and save the map in the Editor.
3. Add units, sides, ownership, deployment hexes and AI orders.
4. Add victory conditions, turn count, triggers and events.
5. Add a custom scenario image if the completed scenario requires one.
6. Test the finished scenario in the game.

The map generator does not replace the Panzer Corps Editor. It removes much of
the time-consuming work required to create the map foundation.


13. SELF-TEST AND TROUBLESHOOTING
---------------------------------

For every new version or when a problem occurs:

1. Run Selbsttest_Windows.bat.
2. Wait until the complete test has finished.
3. The result must report 0 errors.
4. If an error occurs, keep and provide Selbsttest_Ergebnis.txt.

The self-test checks PowerShell syntax, templates, examples, terrain values,
overlays, transport networks, export files and whether this English guide and
the German text guide carry the current version number.

HF1 fixes the startup failure in the first protected BETA 1 where Windows
PowerShell 5.1 treated an invisible UTF-8 BOM before "Set-StrictMode" as part
of the command name. The BOM is now removed during the protection build and
also handled defensively by the loader. Map-generation logic is unchanged.


14. FEATURES NO LONGER INCLUDED
--------------------------------

Automatic map-screen/OCR conversion was removed because Windows place-name
recognition and automatic terrain detection were not reliable enough. The
sketching feature also remains removed for now because it could not be cleanly
separated from automatic generation.


15. BETA TEST AND CORE PROTECTION
---------------------------------

BETA 1 HF1 is a protected test package. The actual map core is not included as a
readable PowerShell script. Its integrity is checked at startup and it is
loaded in memory only. If bound application files are modified or damaged,
the core refuses to start.

Before public release, test the unchanged ZIP on a second Windows 11 PC and,
if possible, on Windows 10. Keep Windows Defender enabled. Do not bypass an
actual malware detection; instead provide a screenshot and
Selbsttest_Ergebnis.txt.


16. DOCUMENTATION RULE
----------------------

BEDIENUNGSANLEITUNG_DE.txt and BEDIENUNGSANLEITUNG_EN.txt are mandatory
parts of every new or modified version. Both files must always carry the
matching application version.
