Added 3 new WS modding documentation pages

docs/content/english/War Sails/_index.md

@@ -0,0 +1,7 @@
++++
+title="War Sails"
+weight = 100
++++
+
+{{%children style="h5" description="true"%}}
+

docs/content/english/War Sails/what_makes_seaborne_village_raid_scene.md

@@ -0,0 +1,131 @@
++++
+title = "What Makes a Seaborne Raid Scene"
+description = ""
+weight = 20
++++
+
+### **Navigation Mesh**
+
+* Works similarly to village scenes.  
+* In scenes created using two separate levels, for the `land_raid` **Level** (check ["What Makes a Village Scene"](https://moddocs.bannerlord.com/authoring-mission-scenes/villages/) documentation), all **NavMesh** on land must have **ID 0** in the `naval_raid` **Level**.  
+* **Agents** can walk in water up to a height of 1.40 meters. Therefore, **NavMesh** with **ID 0** should be baked up to a depth of 1.40m; if the water is deeper, **Agents** will swim.
+
+---
+
+### **Spawn Points**
+
+* All **Spawn Points** must be positioned inside the **Soft Borders**.  
+* All **Spawn Points** must be placed on top of the **NavMesh**.  
+* **Battle Spawn Points**:  
+  * All defender **Spawn Points** must be located within the **Defender Boundaries**.  
+  * **Prefab**: `naval_battle_set`  
+  * Place the defender parts of the set on land and the attacker parts in the sea/river.  
+  * Attacker **Spawn Points** should not be too close to the shore.  
+  * Ensure all defender **Spawn Points** have empty space around them for troops to spawn properly.  
+  * Move defender reinforcement **Spawn Points** out of sight as much as possible without being too far from the front lines.  
+  * Since a raid can be performed with 3 ships, you can position attacker infantry, archer, and cavalry **Spawn Points** facing the direction they will travel in the water.  
+  * The distance between attacker **Spawn Points** should be adjusted according to ship dimensions.  
+  * If a river scene is being prepared, it must be wide enough for large ships to move freely.
+
+---
+
+### **Tactical Positions**
+
+* **Prefab**: `tactical_position`  
+* Use the `chokepoint` **Tactical Position** type within the **Script**, adjusting its size for where you want infantry to position and defend.  
+* Use the `cliff` **Tactical Position** for the general placement of archers. This position determines the general location of archers, from which they distribute to `strategic_archer_point` entities and return to when retreating.  
+* The `cliff` **Tactical Position** **Prefab** should be used as a child of the `chokepoint` **Tactical Position** **Prefab**.  
+* **AI** will position themselves according to the rotation of the **Prefab** and the width defined in the **Script**.  
+
+<img src="/img/seaborne_raid/1.jpg" style="max-width: 800px;"/>
+
+<img src="/img/seaborne_raid/2.jpg" style="max-width: 800px;"/>
+
+---
+
+### **Tactical & Strategic Archer Positions**
+
+* **Prefab**: `strategic_archer_position`  
+* Defines the location where a single archer will go. Many can be added to the scene; all defender archers in battle will distribute among these positions.   
+* To reposition archers who are placed far from the main battlefield to harass incoming ships early on, you have two tactical options to bring them back into the main fight:  
+* **Option A (`unsafe_archer_point`):** If you give these entities the `unsafe_archer_point` **Tag**, once the ships complete their landing, these archers will automatically fall back toward the main battlefield (`cliff` **Tactical Position**) to rejoin the active defense.  
+* **Option B (`volume_box_archer_point`):** If you want more precise control, you can use the `volume_box_archer_point` **Tag** (applied to both the archer positions and a corresponding `volume_box`). This ensures that the archers will hold their positions and only fall back to the `cliff` **Tactical Position** when the enemy actually penetrates your designated **Volume Box** area.
+
+<img src="/img/seaborne_raid/3.png" style="max-width: 800px;"/>
+
+**Volume Box Trigger Point**:
+
+* **Prefab**: `volume_box`  
+* **Tag**: `volume_box_archer_point`  
+* This setup acts as a spatial trigger for archer maneuvers. Unlike the `unsafe_archer_point` which triggers upon landing, this allows for precise control based on attacker progression.  
+* **Setup Rule**: The `volume_box_archer_point` Tag must be assigned to both the `volume_box` entity itself and all `strategic_archer_point` entities that you want to be triggered by this specific box.  
+* **Behavior**: When any attacker enters the tagged `volume_box`, all archers stationed at the matching tagged `strategic_archer_point` entities will immediately begin their retreat toward the `cliff` **Tactical Position**.
+
+<img src="/img/seaborne_raid/4.jpg" style="max-width: 800px;"/>
+
+---
+
+### **Player View Point (for Defender)**
+
+* Use the `arrow_new_icon` **Prefab** and assign the `player_spawn_frame` **Tag** to it.  
+* The player will **Spawn** facing the direction of the arrow.  
+* **Note**: The rotation and direction of the arrow are critical, as they directly determine the player's initial field of view upon spawning.
+
+---
+
+### **Landing Points**
+
+* 3 empty entities must be placed on the shore using the correct **Tags** for 3 ships to land:  
+  * Attacker infantry ship landing **Tag**: `landing_001_0`  
+  * Attacker archer ship landing **Tag**: `landing_002_0`  
+  * Attacker cavalry ship landing **Tag**: `landing_003_0`  
+* Ensure there is enough distance between the landing points of the ships on the shore.  
+* For the route you want ships to follow in the water, you can give similar **Tags** to empty entities placed in the water.  
+  * Example: For the infantry ship, from near to far: `landing_001_1`, `landing_001_2`, `landing_001_3`. In this case, the attacker infantry **Spawn Point** inside the `naval_battle_set` will target `landing_001_3` first, then the others in sequence to reach `landing_001_0`.  
+* The rotation of all entities must face the next target landing entity.  
+* The rotation of the final destination `landing_00x_0` must be positioned to ensure the ship docks correctly at the shore.
+
+<img src="/img/seaborne_raid/5.jpg" style="max-width: 800px;"/>
+
+---
+
+### **Jumping Points**
+
+* Used to indicate which direction **Agents** jumping from the ship to the shore should move.  
+* Use empty entities with **Tags** `jumping_001`, `jumping_002`, `jumping_003` for each ship, and they must be a child of their associated final landing point.  
+  * Example: The entity with the `jumping_001` **Tag** must always be a child of the `landing_001_0` entity.  
+* The rotation should be adjusted to ensure **Agents** use the most logical **Mechanics** to leave the ship.
+
+---
+
+### **Flee Positions**
+
+* Positions to which fleeing troops and horses will run.  
+* Ensure they are inside the **Soft Border** and have **NavMesh** below them.
+
+---
+
+### **Soft Border**
+
+* **Prefab**: `border_soft`  
+* These entities define the red boundaries of the scene.  
+* When placed, they form a polygon by connecting the two closest border entities.  
+* To visualize the current boundaries, navigate to `Visibility Window` \-\> `Visibility Masks` and enable `Borders`.  
+* **Design Note**: Ensure the layout of these borders prevents players from abusing the map limits or finding unintended escape routes.
+
+---
+
+### **Sounds & Atmosphere**
+
+* Works similarly to village scenes.  
+* Ensure environmental sounds reflect the naval nature of the raid.  
+* **Atmosphere** must look consistent across all seasons and times of day.
+
+---
+
+### **Gameplay Design Hints**
+
+* Having ships under fire before docking increases the epic battle feel. You can place archers further out to shoot at ships early on. To ensure these archers rejoin the frontline defense rather than getting left behind, you can use the `unsafe_archer_point` **Tag** to trigger their fallback to the `cliff` **Tactical Position** upon ship landing, or utilize the `volume_box_archer_point` setup to trigger their relocation exactly when the enemy reaches a specific zone in your scene.  
+* Using physical **Chokepoints** in the scene will increase the difficulty for the attacker.  
+* Make sure the scene works well at night.  
+* To maintain the "village raid" atmosphere, ensure the battle does not start or end too far from the village area.

docs/content/english/War Sails/wsworldmap.md

@@ -0,0 +1,236 @@
++++
+title = "War Sails World Map"
+description = ""
+weight = 10
++++
+
+Creating or modifying the War Sails world map involves a few additional requirements compared to Bannerlord. They are listed below.
+
+## Navmesh
+
+With the War Sails DLC, many bodies of water become navigable, introducing several new navmesh types beyond those used in the base game. When creating or modifying a War Sails world map, you may need to use the following navmesh types:
+
+* `CoastalSea`  
+* `OpenSea`  
+* `River`  
+* `NonNavigableRiver`  
+* `UnderBridge`  
+* `Lake`
+
+The corresponding navmesh ID values are shown in the image below.
+
+<img src="/img/warsails_world_map/1.png" style="max-width: 800px;"/>
+
+`CoastalSea` and `OpenSea` are both navigable water types, but they serve different gameplay purposes. They use different movement speed modifiers and are treated differently by the sea attrition system, so choose the appropriate type based on the intended gameplay.
+
+Use the `UnderBridge` navmesh type for the faces directly beneath bridges, as well as the adjacent faces leading into and out of the bridge. This navmesh type does not affect movement speed or sea attrition. Instead, it controls bridge-specific behavior:
+
+* Ships will automatically fold and unfold their sails when passing underneath the bridge.  
+* When the player sails under a bridge, the bridge becomes transparent to improve visibility.
+
+Lakes are not navigable in War Sails. The `Lake` navmesh type functions as impassable terrain and cannot be traversed by ships.
+
+## Flowmap
+
+In War Sails, wind and water currents affect movement across navigable water. Strength and direction are defined by the Flowmap, which can be edited directly in the World Map Editor.
+
+To edit the Flowmap:
+
+1. Click Paint Flowmap, located between the Paint Flora and Navigation Mesh buttons.  
+2. Also, open the Inspector and select the Flowmap tab in order to correctly edit it.
+
+<img src="/img/warsails_world_map/2.png" style="max-width: 800px;"/>
+
+The Flowmap is painted much like terrain textures or the heightmap, but each brush stroke also defines a direction. The editor displays colored arrows to visualize the Flowmap:
+
+* The arrow direction indicates the wind and water current direction.  
+* The arrow color indicates the wind and water current strength.  
+  * Blue represents the weakest wind and water current.  
+  * Red represents the strongest wind and water current.
+
+The Flowmap directly influences the water shader. Because of this, painting neighboring areas with sharply opposing flow directions can cause visible stretching or unrealistic water deformation. If you need adjacent areas with opposite current directions, create a smooth transition between them instead of painting an abrupt change. This produces more natural-looking water while still allowing distinct current patterns.
+
+## Settlement Setup
+
+War Sails introduces several additional entities for coastal settlements. These entities enable features such as embarking and disembarking, naval blockades, and village landing points.
+
+### Port Points
+
+To allow naval parties to embark and disembark at a coastal town, add a child entity named `town_port` to the settlement.
+
+The entity must:
+
+* Be tagged with `main_map_city_port`.  
+* Be placed on a navigable naval navmesh, such as `CoastalSea` or `River`. Not placing it correctly will lead to errors.
+
+<img src="/img/warsails_world_map/3.png" style="max-width: 800px;"/>
+
+**Settlement XML Configuration**
+
+After adding a `town_port` entity to a coastal town, you must also update the `settlements.xml` file.
+
+In the settlement's Buildings section, add the Shipyard building:
+
+```xml
+<Building
+    id="building_shipyard"
+    level="1" />
+```
+
+And for the shipyard scene, you should add the shipyard location in the settlement's Locations section, like this:
+
+```xml
+<Location
+    id="port"
+    scene_name="aserai_shipyard" />
+```
+
+### Blockade Points
+
+When a coastal town is under siege, War Sails displays a naval blockade around the settlement. To define the blockade area and ship positions, add the following:
+
+* `town_blockade_start` entity with the `Blockade_Arc_Start` tag as a child entity  
+* `town_blockade_end` entity with the `Blockade_Arc_End` tag as a child entity  
+* `BlockadePositionScript` to the town entity
+
+<img src="/img/warsails_world_map/4.png" style="max-width: 800px;"/>
+
+Once these have been added, the editor will display:
+
+* Red markers representing the individual blockade ship positions.  
+* A sphere indicating the center of the blockade arc.
+
+Moving the start and end points changes the extent of the blockade arc, allowing you to adjust the visual placement of the blockade fleet.
+
+The `BlockadePositionScript` also exposes several parameters that control the appearance of the blockade, including:
+
+* The number of ships.  
+* The number of blockade arcs.  
+* The spacing between ships.  
+* Other blockade layout settings.
+
+Adjust these values to achieve the desired visual result.
+
+<img src="/img/warsails_world_map/5.png" style="max-width: 800px;"/>
+
+### Drop Off Points
+
+Coastal villages use drop-off points instead of ports to support embarking and disembarking.
+
+To add a drop-off point, create a child entity named `drop_point` and assign it the `main_map_village_dropoff` tag.
+
+As with town ports, the drop-off point must be placed on a navigable naval navmesh (such as `CoastalSea` or `River`) for it to function correctly.
+
+<img src="/img/warsails_world_map/6.png" style="max-width: 800px;"/>
+
+## Transition
+
+In addition to transitions between naval travel and coastal settlements, War Sails also supports direct transitions between navigable water and land.
+
+The only requirement is that both the source and destination navmesh types must be navigable.
+
+For example:
+
+* A party can transition from `CoastalSea` to `Plain` or `Forest`.  
+* A party cannot transition to an impassable terrain type, such as `Mountain`.
+
+This allows you to define embarkation and disembarkation points at any suitable navigable shoreline, not just at settlements.
+
+## Scripts
+
+One of the most important components in the world map scene is the `SettlementPositionScript`, located under the `settlement_scripts` entity.
+
+Whenever you make changes that affect navigation or settlement locations, the Settlement Distance Cache must be regenerated. This includes changes such as editing the navmesh or moving a settlement, including `town_gate`, `town_port`, or `drop_point`.
+
+To safely regenerate the cache, perform the following steps in order:
+
+1. Before rebuilding the Settlement Distance Cache, verify that the following are selected:  
+   * `_partyNavigationModelOverridenClassName` → `NavalPartyNavigationModel`  
+   * `_distanceModelOverridenClassName` → `NavalDLCMapDistanceModel`  
+2. Check Positions  
+   * Validates settlement-related positions and moves the camera to any problematic locations, making them easier to identify and fix.  
+3. Save Positions  
+   * Saves the current settlement positions and all associated data.  
+4. `ComputeAndSaveSettlementDistanceCache`  
+   * Rebuilds the Settlement Distance Cache. This final step can take a significant amount of time, depending on your hardware. During the process, the editor computes pathfinding routes between every settlement and every other settlement, then stores the results in the cache.
+
+<img src="/img/warsails_world_map/7.png" style="max-width: 800px;"/>
+
+## Water Plane and Material
+
+War Sails does not use the engine's automatically generated scene water. Instead, it uses custom planar meshes with water materials.
+
+The built-in scene water is designed for mission scenes and has fixed scaling and behavior, making it unsuitable for the flexibility required by the campaign world map. Custom water planes allow you to precisely control the size, placement, and appearance of navigable water.
+
+A standard War Sails water plane uses the following configuration:
+
+* Material: `naval_worldmap_water`  
+* Scripts:  
+  * `water_flowmap`  
+  * `CampaignMapAmbientOccluder`  
+* Tag: `snapped_water_body`
+
+The image below shows the required components and parameters for the main world map water plane.
+
+Note: The world map scene also contains additional `water_plane` entities used for lakes. Before making any changes, make sure you have selected the correct water plane.
+
+<img src="/img/warsails_world_map/8.png" style="max-width: 800px;"/>
+
+### Creating a New Water Plane
+
+To create a new water plane:
+
+1. Add the `water_plane` prefab to the scene.  
+2. Position, rotate, and scale it as needed.  
+3. In the Inspector, open the Materials tab and assign the desired water material (typically `naval_worldmap_water`).  
+4. Ensure the required scripts and tag are present if the water plane is intended to function as navigable world map water.
+
+Once configured, the water plane will integrate with the War Sails water rendering and Flowmap systems.
+
+## Storm System
+
+War Sails features a dynamic storm system that generates storms over open water.
+
+The world map is divided into a grid of 32 × 32 unit cells. For each cell whose center lies on an `OpenSea` navmesh, the game periodically checks whether a storm should spawn.
+
+Three storm types are available:
+
+* `Storm`  
+* `ThunderStorm`  
+* `Hurricane`
+
+The type of storm generated depends on the Flowmap data at the selected location. Each storm type has its own movement speed, radius, and damage characteristics.
+
+### Configuring Storms
+
+Storm behavior can be customized by overriding the `StormModel` (through code, not in the editor). This allows you to adjust parameters such as:
+
+* Hourly spawn chance  
+* Maximum number of active storms  
+* Storm type configuration  
+* Storm lifetime
+
+### Storm Movement
+
+Storms do not follow predefined paths. Instead, they are driven by the Flowmap.
+
+As a storm moves across the world map, it continuously follows the flow direction defined by the Flowmap at its current location. This allows storm movement to naturally match the current patterns you've painted into the map.
+
+### Flowmap Considerations
+
+Storms gradually weaken and eventually dissipate when they remain over land navmesh.
+
+For this reason, when painting the Flowmap near coastlines, it is recommended to direct the flow away from land and toward open water. This helps keep storms at sea and prevents them from immediately dissipating after spawning or drifting near the coast.
+
+## Pirate Spawn Points
+
+War Sails uses dedicated pirate spawn points to control where pirate parties appear and the regions they patrol over time.
+
+Each pirate spawn point must have a `PirateSpawnPoint` script attached. In the script, set the Clan String ID to the appropriate pirate clan. War Sails has two clans available:
+
+* `northern_pirates`  
+* `southern_pirates`
+
+If you wish to add new clans, you should define them in the `clans.xml`, and then proceed to add them to the world map.
+
+<img src="/img/warsails_world_map/9.png" style="max-width: 800px;"/>

docs/content/russian/War Sails/_index.md

@@ -0,0 +1,7 @@
++++
+title="War Sails"
+weight = 100
++++
+
+{{%children style="h5" description="true"%}}
+