Getting Started

English | French version

Release scope: Unity 6000.2 or later, URP, Windows / Android / iOS. The four supplied biomes are Forest, Tropical, Snow and Autumn. See compatibility and recorded validation.

Import Core first, then the optional Starter unitypackage for editable examples under Assets/SorolifMapGenerationStarter. Core updates do not overwrite that folder. See Starter installation.

Choose Biome first. Biome preset lists only matching BiomeSetting assets and selects a compatible default: editable Starter preset, then Core reference preset, then another matching asset. A compatible custom selection is preserved. This works in both Simple and Expert mode. Select biome preset to edit opens its settings. If no matching preset exists, the Inspector explains the automatic fallback. Direct material and prefab overrides retain priority.

The Biome menu offers only types with an available BiomeSetting. The supplied selection is Forest, Tropical, Snow and Autumn. Show In Biome Selector is on by default for new presets; turn it off for unfinished or optional content. To offer another type, create a BiomeSetting, choose its Biome Type and leave this option enabled. No enum entries are removed. Existing explicit settings and runtime generation continue to work even when their preset is hidden from new selections.

Each generated root has a Generated Map Info component with its captured seed, biome, symmetry, main settings and strategic markers. Use Select Map Information on the generator to find it; its Show Gizmos and Show Labels switches control the map's Scene view markers. See Generated Map Information.

For prefab placement rules and their Inspector, see Props Placement.

For grass prefabs and GPU instancing, see Grass Details: select the generator, click Apply dense grass preset (screenshots) in Terrain style, then Generate Map. This enables props and grass with chance multiplier 1 and height 0.5–0.8. Older biomes without grass rules use the included prefabs automatically; authored grass rules remain authoritative.

Zero-setup demo

For an in-Editor walkthrough, open Tools > Sorolif > Map Generation > How To Use. The guide includes eleven topics with numbered steps, English/French language selection and accent-insensitive search. English is the initial default; an explicitly selected language is remembered. The How To Use button in the Inspector and the ? buttons beside Simple/Expert sections open the relevant topic. Reading the guide never changes your map settings.

Start with Your first map, then follow Procedural layout or Import an image. Other pages cover map altitude, biome materials, contour smoothing, dirt paths, water and cliffs, PNG export, runtime code and troubleshooting. Explicit action buttons create demos/assets or select relevant objects; generation remains an Inspector or runtime action. The runtime page provides a copyable, complete MapBootstrap.cs example. Select the complete offline guide highlights the corresponding documentation asset in Project.

Use Tools > Sorolif > Map Generation > Create Starter Demo Scene. Choose a scene location. The command creates independent biome settings referencing Core/Art, lighting, a camera and a complete generated map; existing settings are preserved.

See WaterRendering.md for the Forest, Snow, Tropical and Autumn water materials, camera setup and shader controls.

See MountainRendering.md for the rock transition at the foot of mountains, contour smoothing and preserved physics layers.

The same wizard prepares four editable biome presets: Forest, Tropical, Snow and Autumn. They use the package's own textures and configured source-model prefabs, with shared cube-based resource placeholders. Select Biome preset to change the visual starting point. Details are in StarterAssets.md.

To evaluate image-driven generation without preparing an asset first, use Create Image Import Demo Scene. It uses the packaged Examples/ImageImport/StarterImageMap.png, creates a matching editable palette under Assets/SorolifMapGenerationStarter, and leaves the source image and palette assigned on the generated scene for inspection.

The Welcome & Setup window presents this action on first import and once after each package update. Reopen it at any time from Tools > Sorolif > Map Generation > Welcome & Setup. Its readiness section checks the packaged shaders, biome discovery, optional Unity Layers and the currently selected generator. The same report is available through Run Setup Check.

The demo uses a fixed seed so its result is reproducible. Its generator remains editable: change the seed or terrain settings in the inspector and click Generate Map to explore variations.

1. Create a generator

Use Tools > Sorolif > Map Generation > Create Map Generator. The command creates a GameObject with MapGenerator and a default MapDefinition.

The generator creates its output as a child hierarchy. Re-generating replaces that hierarchy while preserving the generator component and configuration.

The inspector starts in Simple mode. This view is intended for normal production use and exposes the map source, players, strategic density, main terrain features, resources and seed. Use the Balanced, High Ground or Naval quick-start buttons to configure a coherent baseline before adjusting individual features. Select Expert at the top of the inspector to tune every algorithm, rendering override, water/cliff parameter, screenshot option and scene integration reference. Switching views never discards hidden values.

New recipes start with one main River layout, automatic biome bridge prefabs, forests, mountain landmarks and two contested objectives. Additional Naval Zones and artificial Choke Points start at zero: the river already provides a natural strategic passage. Increase those values explicitly for extra waterways or forced bottlenecks. Balanced restores this terrain profile and enables bridges after another preset was selected. High Ground uses strategic plateaus and their ramps without water. Naval uses islands and requires naval transport between separate landmasses. Preset buttons preserve the selected biome asset, map size, player count, seed and output settings. Existing saved recipes retain their own values; select a preset explicitly to adopt its settings.

The initial 70-cell map leaves room for two players and their natural expansions. Very small maps may not fit every requested expansion; generation reports expansions.capacity with the affected player count. Increase Map Size or reduce Expansions Per Player when this warning appears.

Expert options are grouped into separate collapsible sections, including individual plateau/ramp, forest, mountain, image-smoothing, river, bridge, island, lake and cliff-fitting groups. Section state is stored in Editor preferences and never changes the map recipe.

Generate Minimap Layer and Generate Aerial Layer are off by default. Find them under Output in Simple mode, or Optional outputs and project layers in Expert. Regenerate after changing either switch. Optional outputs and project integration covers their layers, graph tags and bridge prefab lookup.

When Generate Aerial Layer is enabled, the hidden MeshGround/AerialGround mesh and its collider provide an optional flight surface on the Aerial layer (falling back to Ignore Raycast when that layer is absent). It follows the final ground and water, including global altitude, with Aerial Clearance world units of vertical clearance (3 by default). Mountains do not raise the flight level: the continuous surface passes through the massif, and rock protruding above it remains a physical obstacle through its own collider. A conservative margin near steep ground breaks can add clearance. Regenerate the map, then rebuild your navigation data if your game uses a separate navigation bake, including protruding rock as obstacles. The renderer stays hidden; no navigation package is required. See Aerial navigation for diagnostic views.

2. Configure visual assets

Assets can be assigned directly on MapDefinition, supplied through its explicit Biome Override reference to a preset anywhere in the project. Select a compatible preset in the Inspector, or assign MapDefinition.BiomeOverride in code. Leaving it empty uses directly assigned local materials and prefabs. All included art is stored under Art; runtime generation reads serialized asset references.

Recommended minimum setup:

Direct material and prefab values on MapDefinition take precedence over the resolved BiomeSetting. When Biome Override is empty, the original recipe uses its explicitly assigned local assets. Assign a compatible biome preset to use the supplied complete art setup.

Plateau ramps are added outside the plateau without removing its faces. Set Plateau Ramp Length (default 5 cells, range 2–18) to choose a short steep descent or a longer gentle one. Ramp surfaces and colliders use the shared Walkable layer configured by Walkable Layer (ramps and bridges) on the map. No dedicated Ramp layer is needed. If the configured layer is missing, generation falls back to the configured ground layer, then Default.

To create only the starter visual assets, use Tools > Sorolif > Map Generation > Create Starter Biome Assets. It creates editable triplanar terrain materials, original stylized grass/forest/dirt/sand/rock texture copies, four BiomeSetting presets (Forest, Tropical, Snow and Autumn), and cube-based resources, trees, rocks, cliffs and a river bridge under Assets/SorolifMapGenerationStarter.

This explicit starter action reserves a free user-layer slot as Walkable for ramp surfaces and bridge decks. Existing layer names are never replaced. If every user-layer slot is occupied, the setup check reports the missing layer.

Bridge deck colliders also use Walkable. Separate barrier colliders use the configured Environment layer. Custom projects should define these layers in Tags and Layers.

Triplanar terrain rendering

The included Sorolif/RTS Terrain/Triplanar shader is selected automatically for newly created starter terrain materials. Use Top Texture for horizontal terrain and Cliff / Side Texture for steep faces. World Texture Scale controls world-space tiling and Projection Blend controls how sharply projections meet.

Sorolif/RTS Terrain/Triplanar Stylized adds banded lighting, slope accents and a rim highlight for readable low-poly or illustrated maps. The starter asset command creates Triplanar_Stylized_Preset.mat as an editable example. Both shaders avoid visible UV stretching on plateau walls, mountain slopes and generated cliffs. Detailed property guidance is available in TriplanarShaders.md.

3. Generate procedural maps

With Enable Map Altitude active, the map perimeter is closed automatically by rock faces down to a common base. MeshGround/MapSides follows the rendered terrain, including paths and coastal floor extensions, and has a matching collider. It uses Mountain Material, then Env Material or Grass Material as a fallback. Existing mountain border faces are continued below their lower edge.

Select Procedural as the generation mode, choose the map size, player count, symmetry and water layout, then click Generate Map.

Full Map Symmetry is disabled by default: Symmetry controls player-start placement while the rest of the map keeps natural generation. Enable Full Map Symmetry to mirror the entire map, including terrain, water and decoration. See Full-map symmetry.

For reproducible output, disable Use Random Seed and provide a fixed Seed. The same configuration and seed produce the same logical map layout.

Set Choke Points above zero to funnel travel between player territories through narrow passages. Continuous dividers use forests when enabled, or rock ridges when forests are absent; existing mountains and water remain obstacles. In the Islands layout, irregular low islands narrow the sea into straits of varying width, including the outer sea route. Forest settings populate woodland when matching props are configured; mountains add optional rock cores. Nearby neutral expansion islands can join these formations without moving their resources or changing the expansion count. Player coastlines retain an open-water apron. Naval passages remain water and do not create dirt paths. Planning uses the final relief, ramps and bridge decks, preserves settlement clearings, and reconnects approaches through legal terrain. Constrained terrain can require additional openings to keep existing settlement access. Zero disables these strategic dividers. Regenerate the map to update its passages.

With multiple passages, openings spread along the territory boundaries and need broad approaches on both sides. Tiny isolated pockets are avoided. Land roads share a collector with a single connection from each town, rather than one long road from every base to every passage. Adjacent ramp/deck openings share one marker. If safe spacing cannot fit the requested count, optional openings are skipped; access-preserving openings can still increase the count.

Land passage Naval strait (Islands)
Land choke Naval choke

B marks main bases, N natural expansions, X contested expansions and C the actual passages.

Contested Expansion Count scatters neutral objectives over free terrain using the seed. Placement compares complete layouts to balance estimated access from the player bases while reducing large empty sectors. Individual sites may favor different players; they are no longer all attracted to player medians. Access is estimated from base-to-objective distances before relief and water generation, not from unit travel times. Footprint safety and spacing can reduce the achieved count on crowded maps. With a single objective, equal access takes priority.

Important density controls:

Cliff prefab renderer bounds are centered on the actual steep face, independently of the prefab root pivot. The grid-to-world half-cell offset is applied automatically. Every ramp component creates exactly two continuous lateral cliff rails. Each rail uses one prefab stretched between the high and low caps and pitched in 3D to follow the ramp slope. Its inner renderer face is aligned under the ramp boundary rather than centering the whole prefab on it, so the border stays flush while most of its depth remains outside the playable ramp; the access center and both caps remain open. In the Unity Editor, generated details remain connected prefab instances; runtime generation uses ordinary instantiated GameObjects.

Procedural roads stay curved with Enable Path Smoothing on or off. The option refines their contours without selecting a different road network. Towns connect to natural expansions, other expansion sites and strategic arteries through safe terrain. Roads do not automatically trace forest outlines or connect unrelated mines to one another.

Procedural bases act as towns with irregular dirt hubs and 4–6 curved local streets; expansions use 3–5 shorter arms. Their rotation, length and curvature vary with the map seed. Arms shorten or disappear near water, mountains, resources, ramps and height breaks. Imported image paths retain their authored footprint.

Free ends of curved paths and base arms taper to points. Their edge variation fades out at the tip; connected roads and ramp mouths retain their width.

Dirt paths and ramp approaches have a shallow 0.02-unit recess, with edges blending into the ground and ramp mouths. Their colliders follow the same surface. The depth remains 0.02 Unity units when Cell Size changes.

4. Generate from an image

  1. Select Image generation mode.
  2. Assign Source Map Image.
  3. Enable Read/Write in the texture import settings.
  4. Assign a MapGeneratorImageLayer set, or use Auto Match when its source-name patterns match the image family.
  5. Keep related scans in one shared layer set by adding a common pattern such as PhotoScan_2. Matching ignores case, spaces, punctuation, copy suffixes and file extensions.
  6. Use semantic layer prefixes (Grass, Forest, DirtPath, Water/Lava, Mountain) so imported cells receive the correct gameplay behavior and biome-material fallback.
  7. Keep Enable Image Ground Relief enabled for subtle seeded altitude variation; tune its strength and scale when a flatter or broader result is preferred.
  8. Leave Import Image Resources disabled when gold mines and oil fields will be placed manually.
  9. Generate and tune tolerance/vote values only if the scan contains unusually strong lighting or compression noise.

The importer is tolerant of paint and JPEG variation, including low-saturation black, gray, silver and white regions. Water and Lava layers generate both navigable water classification and the continuous underwater-floor terrain mesh; their visible surface and seabed extend beneath at least one neighboring coastal cell to prevent shoreline gaps. This overlap is visual only and does not make ground cells navigable as water. The inspector reports a blocking validation error when the source texture is missing or not readable, and warns about duplicate prefixes or unresolved custom materials.

Procedural contour smoothing

Enable Procedural Contour Smoothing is enabled by default, with strength 0.85. It reuses the image importer's geometric relaxation on the final forest, mountain and shoreline contours. Adjust Procedural Contour Smoothing Strength in the Simple terrain settings or Expert scene settings; zero or disabling it restores the previous geometry, including the optional planar vertex noise.

The deformation affects shared render/collision vertices only. It preserves cell types, heights, resources, strategic plateaus, ramps, reserved land routes and bridge approaches. Curved dirt paths retain their separate path-smoothing control. Water is rebuilt from the final contour field after terrain generation, without repeating water placement or connectivity rules. Image contour controls retain their existing behavior and source-image boundary fitting.

Logical base/expansion/resource regions, plateau interiors and broad vegetation clearance masks do not freeze decorative forest boundaries. Physical resource anchors, ramps, plateau edges, bridges and narrow choke geometry remain pinned. Mountain footprints may be smoothed even though their gameplay type is Blocked; other blockers stay pinned. Coastlines and mountain outlines take priority over decorative material junctions so grass/forest changes do not interrupt the curve. Vegetation exclusions and strategic route reservations are retained unchanged.

5. Runtime generation

using Sorolif.RTS.MapGenerator;
using UnityEngine;

public sealed class RuntimeMapExample : MonoBehaviour
{
    [SerializeField] private MapGenerator generator;

    private void Start()
    {
        generator.Definition.UseRandomSeed = false;
        generator.Definition.Seed = 20260711;

        ProceduralMapGenerationResult result =
            generator.GenerateRuntimeMap();

        if (!result.Succeeded)
            return;

        Debug.Log($"Generated {result.Grid.Size}x{result.Grid.Size} map");
    }
}

ProceduralMapGenerationResult exposes the generated root, grid, strategic cell positions and player spawn world positions.

The complete public entry-point reference and an editable integration example are documented in RuntimeAPI.md. UPM installations expose the example in Package Manager's Samples section; the classic Asset Store package places it under Examples/Runtime Generation.

6. Generate a map screenshot

Enable Generate Screenshot After Generation in the Screenshot section. Top-down is the default view. In Expert mode, select Isometric and configure pitch and yaw when a three-quarter presentation better exposes terrain elevation. Both modes fit all eight corners of the generated renderer bounds. Configure Screenshot Output Folder, resolution, padding, background and the LayerMask to include. The capture uses its own temporary orthographic camera and therefore does not require a scene camera.

Relative folders are resolved from the Unity project root in the Editor and from Application.persistentDataPath in a player build. Absolute folders are used unchanged. The default filename is MapName_Seed.png; disable Screenshot Overwrite Existing to preserve an existing image and append a timestamp instead.

Use Capture Map Screenshot to capture an already generated map manually. At runtime, the resulting absolute path is returned in ProceduralMapGenerationResult.ScreenshotPath:

ProceduralMapGenerationResult result = generator.GenerateRuntimeMap();

if (result.Succeeded && !string.IsNullOrEmpty(result.ScreenshotPath))
    Debug.Log(result.ScreenshotPath);

Map altitude

For broad relief in either generation mode, enable Map altitude in the Simple or Expert Inspector. Set its minimum and maximum offsets and optionally assign a readable grayscale height map; otherwise seeded hills are generated. See MapAltitude.md for image orientation, geometry and runtime sampling. Regenerate after changing these settings.

7. Save and reload recipes

After generating in the editor, use Save Current to create a MapGenerationSaveData asset. Reload Saved reapplies its definition and seed, then regenerates the map.

The save asset stores the generation recipe and strategic positions; it does not duplicate all generated meshes as source assets.

8. Optional integrations

The core package has no mandatory third-party dependency.

Do not enable the Sorolif RTS integration symbol in a standalone project unless you also provide its corresponding framework assemblies.

See Compatibility.md for the verified release environment, render-pipeline behavior, performance considerations and features intentionally left to the host RTS project.

Open the included examples

For a ready-made example, choose Tools > Sorolif > Map Generation > Open Included Procedural Demo or Open Included Image Demo. Unity creates a new editable scene copy under Assets/SorolifMapGenerationExamples and opens it. Existing copies are preserved. The terrain is visible as soon as the scene opens. Select the Map Generator to inspect its assigned recipe, or enter Play Mode to regenerate it automatically through the included QuickStartDemo component. No third-party content or optional runtime sample import is needed. Four presets, materials and illustrative cube-based prefabs are included under QuickStart.

The commands work for both distributions; UPM scenes cannot open directly from the read-only package. UPM materials and presets belong to the package cache; duplicate the biome or material into Assets to customize it. Remove or disable QuickStartDemo once your own startup code calls the runtime API. The creation wizards remain available for producing fresh editable examples in Assets/SorolifMapGenerationStarter.