The Cities XXL Map Editor is a free tool for all Cities XXL owners.
To download and install it, simply go to the "Tools" category in your Steam Library.

The user interface is made of the main viewport, the toolbar and a bunch of dockable panels.

You can rearrange the panels at your convenience and even use a second screen if available.

If you close a panel, you can still reopen it using toolbar buttons or by clicking the main tabs above the toolbar:



Each tab has a main panel associated with it that will be automatically selected or reopened when the tab is changed.

Some editors may also have additional panels with specific controls in the toolbar to open/close them.

The editor always starts in the « FlyBy » camera mode on the “default landscape” level.

Important: “default landscape” level cannot be fully edited in the editor. It’s used as a placeholder at startup and should be replaced by a heightmap or .lvl file especially for landscape edition (see “Creating new maps“ chapter).

To orient the view in FlyBy mode click on the middle mouse button.

You can use the arrow keys to navigate with the camera on the map. Use PageUp / PageDown to ascend and descend.

Note: you can also use any in-game camera using the “Camera” button in the “Options” tab.

Once clicked the button will open a new camera panel where you can select a camera and change all the options associated with it:



This panel is very useful for setting the camera speed and general behavior depending on your needs.

You can switch back to fly by mode at any moment by selecting the “FLYBY” camera in the camera’s panel combo box.

The editor uses basic controls for all panels (mainly sliders, checkboxes, textboxes and comboboxes).

One important thing to know is that the sliders are more precise when holding the Alt key during drag. This may be particularly useful when looking for small values.

During your level creation process you may have to add new textures or files that you authored in external tools.

You must be very careful to follow the file locations described in this guide for each file type (normal maps, ground textures, rock textures, environment configs, …) otherwise you may encouter unexpected behaviour.

The game engine expects the files to be located in well defined places under game directories (or .pak files) thus the editor has to follow the same rules.

Due to space limits, the editor is provided with 8 existing levels.

To open an existing level, click on the open level button at the top (or inside that main menu in the upper left corner):



Next choose an existing .lvl file:


 
Here is a short gallery of the provided levels to give you an idea of what can be achieved with the editor:






Note: You can also add all other Cities XXL levels to explore them in the editor. All you have to do is:

• Extract the “Level“ directory from game “Data.pak” file and copy it into <Editor dir>\Data\
  
• Extract all the “land_*.pak” files into <Editor dir>\Data\Gfx\Lanscape

Once extracted, the levels are available in the editor. You can open the .lvl files as shown in the previous documentation.

Note: you can use the community provided PakUnpack tool to extract the .pak files.

We recommend that you open all existing samples to have a better idea of the results you can achieve with the editor.

Important: the provided samples are “production” levels. You won’t be able to modify the existing elevations (in the landscape editor tab) as the edition heightmap was stripped out from the files.

The typical production workflow for new levels is:

• Landscape edition
  
  • Input: heightmaps <-.r32 files
    
  • Output: landscapes ->.land files
  
  
• Material edition
  
  • Input : textures and parameters
    
  • Output: materials ->.xml material files
  
  
• Environment edition
  
  • Input: textures and parameters
    
  • Output: environments ->.xml environment files
  
  
• Forest edition
  
  • Input: SpeedTree files
    
  • Output: forests ->.lvl level files
  
  
• Particle edition
  
  • Input: particle systems
    
  • Output: particles ->.lvl level files
  
  
• Final Level
  The final level is represented by an .lvl file. The .lvl is an indirection file to the .land, material .xml and environment .xml files generated during edition workflow.

Note: at any time you can check the current configuration files of a level in the title bar of the editor:

This chapter presents the step by step process that should be followed to create new game levels.

The first step of level creation is the landscape edition. To access the landscape editor simply click on the landscape tab:


When the tab is selected it also triggers the opening of the “Landscape” panel on the right side of the editor:


This panel allows editing the terrain elevations manually using brushes (see below).

Important: Cities XXL map editor was intended to be used with third party heightmap generation software like WorldMachine, GeoControl, Vue, …

Thus the tools you will find in the Cities XXL editor are more suitable for the modification of existing heightmaps than for the creation of new elevations from scratch (even if it’s still possible).

This is important to keep in mind when designing new levels.

The first step before editing your terrain is to import a new heightmap file.

Important: the input resolution of the file must be 4096x4096 to get the best results. This is required as this work heightmap will be used to bake the normal map and will be dropped at the end of the creation process.

The editor supports 32 bit floating point heightmaps.
To import a new file simply click on the button.

The editor is provided with two sample .R32 files. You will find them in the “<InstallDir>\Data\Gfx\Landscape\R32” directory:

• BigIsland_03.r32 : sample file of an island exported from WorldMachine
  
• Empty_4096.r32 : empty heightmap provided for full manual edition inside the editor.

In this documentation we will be using the BigIsland_03 heightmap as it’s the best workflow for the editor. You can now open the BigIsland_03.r32 file and you should get the following elevations in the editor:



Note: you may have to move the camera in order to see the heightmap (use PageUp/PageDown to go over the terrain after loading the file)

If you don’t have a DCC tool like Terragen, Geocontrol or World Machine for floating point heightmap generation, you can still use simple images as the source of your landscape elevation values.
For this purpose, you can click on the button.

You will be asked for a jpg, tga, bmp or png file.

Note: be aware that the editor will only use the red channel of your image. So it’s a good practice to design your heightmap images in grayscale (white corresponds to the heighest point and black to the lowest elevation value).

Once you’re done selecting an image it will be imported and converted to a floating point heightmap internally:



Note: as 8bit images have very poor resolution, the editor uses a Bicubic B-Spline filter to generate the final 32 bit heightmap.

As the filter is very expensive, the import operation is much slower than Raw32 import. You may expect times between 15 seconds to one minute for the import to complete depending on your hardware configuration.

Finally, as the filtering helps generating intermediate floating point values from the 8 bit image, keep in mind that unlike the raw32 heightmaps it may be more interesting to use small images in this case (starting at 1024x1024 and below).

Indeed a 4096x4096 8bit texture even if filtered with a bicubic filter will have few differences with the original image and thus give poor results and lots of lighting artefacts.

Once your heightmap is imported, you can start to edit it.
First you can modify the terrain shape using brushes.

Modification zone: it represents the area where the brushes will affect terrain elevations.
The zone is represented by one or two red circles that follow terrain relief:


The modification zone is moved with the mouse (only if a brush is active. See below)
To activate a brush, simply click on it’s icon in the Landscape panel (the active brush is selected in blue).

The modification zone’s properties are controlled with three different values.
Note: each brush type has a separated setup.

Softness: defines the way the values are interpolated between the outer circle and the inner circle of the zone.


Size: defines the size of the modification zone
Strength: defines brush strength 
The editor is provided with three brush types.

Up/Down brush: raises or lowers terrain inside the modification zone

To raise the terrain click on the left mouse button:


To lower elevations click on the right mouse button:


Note: it’s better to use full softness with this brush when beginning.

Smooth brush: smoothes terrain details inside the modification zone

Before:


After:


You can see that the brush preserves macro details but smoothes out small terrain variations.
 
Level brush: moves terrain data to a specified level.

The level brush has an additional control inside the brush panel which sets the target level that should be reached when the brush is used:



Important: please note that the level brush may behave differently from other tools because it will always try to preserve the details of the existing data during leveling. Thus it’s impossible to make a totally flat plateau on an existing mountain (you will have to use the empty heightmap and start from scratch or another tool if you are looking for really flat surfaces)

Before:


After:


Finally you can also adjust terrain height by using the Height slider in the Landscape panel:




Note: you have the possibility to go back and forth between Cities XXL editor and your terrain edition software by using the button.

At any moment during brush edition, you can use “Ctrl+Z” to undo your modifications and “Ctrl+Y” to redo them.

Once you’re finished editing the terrain, you must save your work using the .land file format.
This is the internal game format used for playable levels.
To save your modifications click on the button.
This will save your modifications into an editable .land file (the original high resolution heightmap is preserved). This means that you will always be able to reload the file and make additional modifications to it in the editor.
You can also load some previous work using the button.
The currently active .land file is always displayed in the title bar of the editor:

Make sure to go through a save/load process to have the right name in the title bar.

When you are ready to release an entire game level you have the ability to reduce the total size it will take in-game. The high resolution heightmap used for terrain editing is huge (around 100 Mb) so it’s really important to strip it out of the final level.
To do so you can click on the button and select your .land file. The editor will convert it in-place.

Important: we advise to always keep a backup copy of the original editable .land file. You won’t be able to modify the “production” .land file anymore.

Automatic normal map baking
You may notice that if you make some terrain edition in the Landscape tab and then you try to switch to the material tab or any other tab, the editor freezes during a long time before you can use it again.

In fact each time you modify the heightmap it is flagged as dirty. Then when you switch to a different tab the editor ensures that the normal map will be up to date and triggers a “Bake Normal Map” command automatically (see chapter Material editor for more info).

This process is totally normal and ensures that the elevation data will be coherent with the other editors.


Note: in some scenarios (like importing an .r32 heightmap and then switching directly to the material tab) the automatic normal map update won’t be triggered. In this case you will have to launch the update manually from the material tab (see chapter Material editor for more info)

This editor lets you modify the main diffuse texture of the terrain and the detail textures used for LOD.

The material editor is composed of the main toolbar:


And the material panel:

 
The “Render Mode” combo box in the material editor’s toolbar is a very important control when changing terrain materials as you will see it in the next chapters.
It also allows you to see the wireframe geometry that is used to display the terrain. If you select the Wireframe mode you will see the quad tree and the tessellation that is updated behind the scene:


This may be useful to better understand the lighting behavior of your materials.
 
Before making your own materials you can also test all existing game materials. Simply load an existing .xml file while in “Material edition” mode in the Render mode combo box.
Here is a short gallery of existing materials:




Rock can be edited in any rendering mode (except the wireframe mode). This is because it’s dynamically computed and thus not baked into the diffuse texture (see below).

The rock edition panel allows changing the rock textures and the rock parameters that determine how it is applied on the terrain:


Textures: this section lets you choose 4 different textures that will be blended together to make the final visual result.
This result will be computed based on the parameters selected from the “Noise Mix” and “Noise tiling” categories (see below)

To select a texture simply click on its thumbnail. This will open a dialog that will let you select a new file:


If you go to the “<InstallDir>\Data\Gfx\Landscape\Textures\Rock” folder, you will find some sample rock textures that are used in-game.

Please note that if you want to add your own textures, you will have to put them in this folder and follow the same file format and size.

Note: you may have noticed that the existing rock textures are arranged four by four. This can ease texture selection but you are free to make any kind of mix with rock textures.
 
You also have the ability to adjust the tiling of the textures with the tiling slider:



It’s pretty hard to see the tiling on these screenshots so we recommend you to play with the tiling slider to see its effect in real-time.

Slope: this section allows changing the rock appearance depending on the terrain slope. It also controls the transition from rock textures to the ground textures.

Slope slider (low value):


Slope slider (high value):

 
Transition slider (low value):


Transition slider (high value):

Noise Mix: this section offers an artistic control on the way the four rock textures are blended together.

Important: all this process is designed to remove visible texture tiling when playing the game.



Rock textures are mixed together two by two.

1-2: this slider defines the amount of the first rock texture with the second rock texture.

If you put the slider to the left it means that you will see only rock texture 1, if you put it in the middle you will see the same amount of texture 1 and texture 2 blended using a noise mask. Finally if you move the slider to the right you will only see rock texture 2.

3-4: this slider defines the amount of the third rock texture with the fourth rock texture.

The behavior of this slider is the same as for 1-2 but targets rock textures 3 and 4.

Main: defines the amount of 1-2 rock textures or 3-4 rock textures where both groups are this time blended together with another noise.

Again if you move the Main slider to the left you will only see textures 1-2 (blended accordingly to slider 1-2), if you put it in the middle you will see a mix of textures 1-2-3-4 and to the right only the 3-4 texture group.

Transition Blending: drives the blending transition between all the textures (low value means harsh transition and high value means smooth transition like for the slope transition slider).

Here are some visual examples to better understand the system. First the texture setup:


Note: for the purpose of this documentation and to clarify the visual results of the sliders rock textures were replaced by simple colors. These textures can be found in the “<InstallDir>\Data\Gfx\Landscape\Textures” folder. It can be really useful to play with colored textures first to better understand this complex blending system.

Example 1:


Visual result:


You can see only texture 1 (slider 1-2 was set to the left) and texture 4 (slider 3-4 set to the right) which are blended equally over the entire map (slider Main set to the middle)

Note: transition was set to the minimum (harsh transition) in order to better see the colors.
 
Example 2:
The only thing changed here from Example 1 is that the 1-2 slider was moved to the middle.


Visual result:


As you can see the red color has not moved but now the blue color is equally mixed with green (texture 2).
 
Example 3:


In this example all three sliders are set to the middle. The transition slider was also moved to get a smooth transition between all colors.

Visual result:

 
Noise tiling: this final section controls the tiling of noise textures used to blend the four rock textures together. Again those parameters are intended for artistic control of the final blend result.


Once again the textures are tiled together two by two with an additional control (Main) for the tiling of both groups.

Where sliders 1-2 and 3-4 control the tiling of the corresponding textures inside their zones defined by the mix section, the Main slider controls the repartition of the textures on the entire level.

Here are two examples to show the effect of the main tiling slider (mix settings were taken from example 3 of the previous paragraph but with a harsh transition):

Main slider to the left:

 
Main slider to the right:


Using all those settings you should be able to eliminate all kind of tiling artifacts from your levels and add a lot of diversity to your rock layer.





 

You may have noticed that by default the material editor starts in the “Normal” mode (see the Render Mode combo box). This mode is the “in-game” mode.

In this mode you see exactly what players will see if they play your level in the game.

Cities XXL use two different techniques for terrain materials:

• A large scale diffuse texture: this texture is baked from a lot of layered materials that can only be edited when in “Material edition” mode.
  
• Detail maps: those simple textures are blended with the diffuse texture to add additional details when the camera is close to the ground.

As mentioned, the diffuse texture is static. But detail maps are fully dynamic and change depending on the camera position in the game.

In order to edit the ground parameters you will have to switch to the “Material edition” mode.


Once you switch to this mode, the baked diffuse texture is discarded and you see a procedural real-time preview of your ground material layers. In this mode you can change ground parameters and have an instant feedback in the viewport. This is not possible when in “Normal” mode.

Important: please note that detail textures are disabled in this mode. This may be a little bit disappointing at first but it was designed intentionally to let the artist see his raw materials and have a good idea of the final diffuse texture (see next chapter for more information on detail maps).

Ground materials are composed of four custom layers. You are not forced to use all four layers for your levels. As you will see later you have the possibility to define the height range of a layer and thus override the other layers if you don’t need them.

As for the rock layer you will be able to assign 4 different textures for each ground layer and then blend them together with the same parameters as described previously:





Please refer to the rock section to better understand the behavior of the sliders.

One difference with the rock layer is that ground layers 2, 3 and 4 have an additional section for controlling the layer altitude and blending properties:


Note: layer 0 has no height section as it always covers the entire map from the bottom to the top. It can still be discarded by the other layers using their minimum height (see below).

• Start: defines the start altitude of the layer
  
• End: defines the highest altitude of the layer
  Note: as layers 2, 3 and 4 have their own height sliders, you can decide that layer 4 will be below layer 2 and 3.
  
• Transition: as for the rock layer, this slider controls the smoothness of the transition of the layer with the others
  
• Perturbation: this parameter helps to break the linearity of layer transitions. As each layer is defined by a start and end altitude, transitions may be very visible and linear. To break this effect we add a noise that will change the altitude locally on a random basis (but still near the start and end values that were defined).
  
• Tiling: controls the tiling of the noise texture used by the Perturbation slider. It can be useful to change this setting to avoid tiling artifacts.

Here is an example with colored layers. For the purpose of this documentation all 4 textures of each individual ground layer were set to the same file:



And here is the output with all four layers being put on top of each other (in the correct order):


And here are the parameters used for the height sliders of each individual layer:
Layer 1: no parameters to set (remember that this layer covers the entire level)

Layer 2:

Layer 3:

Layer 4:

Note: the height sliders are artistic controls. You may find out that the values of the slider are not normalized or even difficult to interpret. Be aware that these controls were designed for visual interaction so you should always check the viewport when adjusting those values.
 
Finally here is an example with the same height settings but with transitions and perturbations for levels 2, 3 and 4:


You can notice that now layer 1 and 2 are blended together and that the other layers have smoothed transitions. The transition altitude also uses some perturbation so that the limits of each layer are more difficult to spot.

We encourage you to test those sliders by yourself starting with layer 1 and 2. It will be easier for beginning and you will be able to increase the number of layers once you’re used to the system.

Don’t forget that you can disable layers 2, 3 and 4 at any time by setting their “start height” slider to the maximum.
 

Once you’re finished editing the ground textures you can switch back to the “Normal” mode in the “Render Mode“ combobox.$
You will then notice that all your modifications do not appear on the terrain.

This is normal because everything that is changed in the “Material edition” mode needs to be backed into a final optimized diffuse texture.

To do so all you have to do is to click on the button.

After a short time you should now see that all your terrain modifications were baked and are now displayed in “Normal” mode. You are now sure that players will see the correct terrain materials.


The only ground parameters you can adjust in “Normal” mode are the detail maps.
First you will have to choose a detail map for each of the ground layers you use.

Each ground layer has a dedicated section for the detail map:


Important: only layer 1 has “Far Map Tiling” and “Near Map Tiling” sliders as these parameters are shared among all layers (see below).

If you click on the texture button, you will be able to change the detail map associated with the current ground layer.

Note: in the “<InstallDir>\Data\Gfx\Landscape\Textures\Ground” folder, you will find the detail maps used for the game:


You can also design you own detail maps. Just remember that these maps have to be of the same size and authored in grayscale (all channels must be the same).

The detail map will be added as an overlay on top of the baked diffuse texture. The important thing to remember is that each detail map will be masked out and will appear only in the places it belongs to (based on your ground layers setup).
 
Once you have selected the detail maps for each level, you can then setup the distances at which the maps will be visible. For this purpose you will use the Detail section that is common to all layers:


As mentioned earlier, ground materials are backed after edition to build a large diffuse texture that will cover the entire level. If we use only the diffuse texture, players will lack important details when going close to the ground:


The “Detail” panel’s near and far range gives you the ability to decide when the detail maps will appear depending on the camera position (there are only two parameters for all layers).

In order to avoid visible tiling of the detail maps, the game uses two different LODs based on the same texture.

The near range slider defines the distance from the camera at which the detail map with the finest tiling will start to fade to the coarsest detail map.

If you set the near range slider to a very small value you will obtain this result:


As you can see the camera must be very close to the terrain to see the finest detail map. You can also notice that the transition to the coarse detail map is very visible.

Now if we push the near range slider a little bit further, you can see that the result is much more pleasant:


The transition to the coarser detail map is now more subtle and was pushed away far in the distance.

The far range detail map slider controls the distance at which the coarse detail map will fade away. After this distance the player will only see the diffuse texture. Thus it’s important to setup the far distance as far as possible to always keep details on the terrain but avoiding too much tiling or flickering.

Here is a screenshot with the far range slider set to a low value (note that you will have to move the camera away from the ground to see the coarser detail map):


You can see that the diffuse texture is very visible starting in the middle of the image and going to the top. We lose details too early. Now here is the same viewpoint with a higher far value:


This time we keep lot more details far in the distance. In fact it’s difficult to spot the transition from the coarse detail map to the diffuse texture.

Near and far detail map sliders are artistic controls and should be tweaked precisely for each material.

Finally in the layer 1 Detail section you will be able to adjust the tiling of the near (finest) and the far (coarser) detail maps:


The tiling must be adjusted depending on the selected textures to avoid repeating patterns.
 
Baking the normal map texture
Like for the diffuse texture you can also bake the high resolution normal map texture that is responsible of the correct lighting of your terrain.

As seen in the Landscape editor chapter this process can be automatic or manual.

In the case you are loading a .r32 file without editing it, there are chances that the normal map won’t be updated:


Thus it’s important that you always check that your lighting is correct. In fact, it’s a best practice to bake the normal map after each landscape modification (or heightmap change) using the button.



You can now see the big lighting difference on the same viewpoint with a correct normal map.

Important: once you’re done editing your materials don’t forget to save them!

This step is required as the saved file will be used by final game level (.lvl file) to retrieve the detail maps and their associated parameters.

This editor is responsible of the environmental parts of the game level like atmosphere, lighting, water and sky cubemaps.



The load and save buttons in the toolbar allow to load or save environment files that will be later used for your levels.

An environment file contains all parameters of atmosphere and lighting but it does not contain the parameters for water and cubemaps. Those two features are stored with the .lvl file.

This way you can setup an environment that can work for multiple levels but still adapting water or sky on a per level basis.

The “Environment Editor” and “Time Slider” checkboxes allow opening or closing useful edition panels (see below).

The “Environment Editor” panel regroups all the settings of the previously mentioned environmental features:




Important: please note that the “Environment keys”, “General settings” and “Scattering” sections are all linked together. Every time you will select a key in this section it will update the “General settings and “Scattering” sections to previously defined values for this key.

There are a fixed number of keys for the entire day/night cycle in the game.

The environment keys section is pretty straightforward and only allows changing the current key and associated sun color.

In order to change Sun color, simply click on the colored rectangle in the “Sun color” column. Sun color is the direct lighting of the Sun on the map (and other elements like trees, buildings,… later in the game). Here are some examples of the effects of this parameter:






The Time Slider control at the bottom of the editor’s viewpoint allows you to have a dynamic preview of the day/night cycle at any time:


The Time Slider just goes through all the keys blending the parameters that were defined in the editor (this is the same as using the in-game panel but a bit more precise).

You can simply drag the slider or you can hit the play button to get a smooth animation.

Important: if you use the time slider and then want to edit a key, be sure to click again on the key in the “Environment keys” panel. Otherwise you will be editing current values that won’t be stored in the environment file and that will be lost. You always have to select a key before updating any value.

Important: don’t forget to select a key in the “Environment keys” section before changing those settings.



This section controls the sun position, the IBL maps as well as moon and stars parameters.

• Sun multiplier: this slider controls the Sun direct lighting intensity
  
• South Hemisphere: if checked the Sun will be flipped on the other side of the level (Sun trajectory is fixed above the map)
  
• Ambient Multiplier: controls the amount of ambient IBL lighting (defined by the CubeMap settings below).
  Note: IBL ambient is a lighting contribution that you can see in the shadowed parts of the terrain (or objects). It helps to keep details even if those zones are darkened so that you can still see the effects of normal mapping.
  IBL lighting is much more powerful than simple ambient term because the ambient color will be taken from a cube map depending on the terrain normal generating interesting color changes and simulating global illumination.
  It is a good practice to use an ambient cubemap that is close to the colors of your terrain and sky.
  
• CubeMap Settings:
  
  • Ambient: allows to select the ambient cube map file
    
  • You can find the default cube maps if the “<InstallDir>\Data\Engine\Skybox” folder.
    
  • AmbientTrees: trees are using a separate cube map for more artistic control. In most cases you can select the same cube map as for the “Ambient” parameter.
    
  • BlurPass: the ambient cube map needs to be blurred in-game otherwise you will get a metallic effect instead of smooth ambient lighting.
    The Blur pass parameters controls how many times the map will be blurred before being used.
    
  • BlurSize: defined the blur kernel size during a single blur pass.
    
  • Reflection: this parameter allows you to choose the cubemap that will be used for the building’s reflections in the game. There is no preview for this parameter in the editor.
    
  • TreesBlurPass: same as BlurPass parameter but for AmbientTrees cube map blur.
    
  • TreesBlurSize: same as BlurSize parameter but for AmbientTrees cube map blur.
• Moon size: this slider controls the size of the Moon. Please note that Moon is only present at night. You will have to select the “Night” key for example to see it in the editor.
  
• Moon blending: controls the blending of the Moon with the background sky. A low value will fade away the Moon and a high value will make it brighter.
  
• Stars flickering: this slider controls the stars flickering speed.
  
• Stars brightness: controls stars brightness at night.

Important: don’t forget to select a key in the “Environment keys” section before changing those settings.


The scattering panel controls the atmosphere and sky. CitiesXXL uses a simplified physics approximation of the sky and haze. The panel gives you an access to the parameters of this simulation and adds some artistic controls to it (for changing atmosphere colors).

• Settings
  
  • Sun size: controls the size of the Sun
    
  • Sun intensity: allows to lower the color contribution of the sky
    
  • Sun Turbidity: defines how dense the atmosphere will be.
• Sky Color: allows to change the color of the sky to make all kind of artistic colors:
  
  
  • R: controls the amount of red color in the atmosphere
    
  • G: controls the amount of green color in the atmosphere
    
  • B: controls the amount of blue color in the atmosphere
• Haze settings: the algorithm adds a haze effect on top of the sky. This section controls haze behavior.
  
  
  • Height: controls the maximum altitude of the haze
    
  • Intensity: controls haze intensity
    
  • Position: controls haze position relative to the horizon
    
  • Color: color picker for choosing a haze color.

To activate water on your level click on the checkbox left to the Load button and adjust water height with the Height slider:




Note: The water system automatically generates foam around the terrain for a more pleasant result.

You can load and save water parameters using the corresponding buttons. You can open existing water configurations that are located in the “<InstallDir>\Data\Gfx\Landscape\Water” folder.

Water is highly parameterized. Here is a detailed description of all the parameters:

• Color
  
  • Color picker: the color picker lets you choose any color for the base water color.
    
    
  • Alpha: this slider adjusts the global water transparency
    
  
  
• Transparency: this section gives more artistic control on the water transparency
  
  • Border: controls the transparency blending on the map borders
    
  • Depth: controls the transparency in deep water
  
  
• Normals: controls the water refraction and reflection perturbation.
  
  • Perturbation: defines the amount of normal perturbation that will give the impression of refraction
    
    
  • Normal map / Load button: the perturbation is based on a normal map. You can change the default map by using the “Load” button. Here is the default normal map:
    
  
  
• Specular: this section control the specular response of the water
  
  
  • Power: controls the specular power (or diffusion of the effet)
    
  • Intensity: controls the intensity of the effect
  
  
• Reflection: the checkbox enables or disables water reflections
  
  
  • Fresnel Bias: artificially moves the Fresnel zone
    
  • Fresnel Power: controls the power of the effect
    
  
  
• Speed: this section controls the speed of the water waves. Water waves are based on a multi octave normal map scrolling.
  
  • Base: the base slider controls the overall speed of the waves animation
    
  • Factor: the factor alters the speed of some of the octaves to make wave animation less directional and avoid visible scrolling.
  
  
• Scale: this section controls the size of the water waves.
  
  • Base: the base slider controls the global size of the waves
    
  • Factor: this slider scales the secondary octaves in order to add more ripples to the base waves
  
  
• Extents: this section allows adding a water extension plane on each side of your level. This may be very useful to give the impression of an infinite water surface:
  
  
  Simply check the required directions.
  
  
• Underwater texture: when infinite water planes are added in the previous section, the lack of terrain outside the level boundaries is pretty visible. To avoid this transparency effect you are able to select a texture that is closer to the terrain colors and that will be displayed under the water outside the level.
  
  
  Note: to see the underwater texture just use the flyby camera to go below the water surface.
  
  
  • UV: you have the ability to choose the tiling of the texture to better match the existing terrain diffuse texture
    
  • Texture: you can choose any texture to be displayer underwater outside of the level boundaries. Simply click on the load button to select a map.
  
  Note: you can reuse your ground textures for the underwater map.

 


This a new Cities XXL feature that allows replacing the procedural sky defined in the “Scattering” section by static cube maps. Those textures can be derived from real life photos and thus give more realistic results as well as additional weather features (clouds, rainbows,…)

The new system allows blending up to 4 cubemaps together during the entire day/night cycle.

Important: the textures cannot be selected or edited in the editor. The system relies only on file naming in the “<InstallDir>\Data\Gfx\Sky\Cubemaps” folder. The only thing you can do in the editor is to associate an existing sky with your level and have a preview of the final result.

The available cube maps will be listed in the “Sky” combo box.

Simply select the desired cube map to assign it to the level (don’t forget to save your .lvl file to make your choice persistent).



Please note that you can save an environment setup with a specific cubemap
This allows to match the color of the cube map textures with level’s lighting (Sun, ambient IBL, …).
The environment .xml file will be automatically saved in the “Cubemaps” folder with a “_Env” suffix.
 
Testing lighting with test building
In order to better test your lighting settings, we added a button that allows to spawn a building on the terrain.

You can find the button in the Options tab in the Objects section:


When you click on the button you will have to move the mouse to the viewport in order to see the new building. It will automatically follow the landscape:


You can end the building placement by cliking on the left mouse button.

By default the building won’t terraform the terrain in order to preserve your landscape.
You can always delete the buildings you place on the terrain by selecting them with the left mouse button and pressing the Delete key.

Note: this test building is described in the “<InstallDir>\Data\Design\Buildings\B_EditorTest.class” file. You can modify this file and change all the settings if required. Just remember that if you change the geometry, the corresponding sgbin file must be present in the “<InstallDir>\Data\Gfx\Building” directory otherwise it’s won’t appear or will be replaced by a placeholder.

This editor allows you to populate your levels with forests made of different trees or bushes species.


The editor comes with a sigle edition panel :


Forests are limited to four tree or/and bushes species which are mixed together.

In order to select trees or bushes you will have to drag and drop .png files from the “<InstallDir>\Data\Gfx\Trees\Forest” directory onto the “current Trees” list.

Note: you can search for *.png files in the root directory to obtain a tree gallery that will ease tree selection:


Once a tree or bush is added it will appear in the list with an instance counter.


Note: each line in the list (or tree/bush type) is limited to 10000 instances. Thus the total tree amount cannot exceed 40 000 instances.

Here is an example with four different trees:


If you click on the forest brush button you will see a dynamic preview of the trees placement on the ground:


You can notice that each tree specie has a dedicated colored box. At any time you can disable the placement of a specific tree by unchecking it in the current trees list:




You can notice that now there are no more dark blue cubes and the TulipPoplar won’t be spawned on the terrain.

Here is the result if you leave only one active tree type:




Once you’re happy with the tree placement, simply click on the left mouse button to plant the trees:


When trees are added to the level, the respective counters are updated to let you know the new tree counts:


Note: the forest brush system is fully dynamic and takes into account a lot of parameters like slope, water level, density. Thus if you try to brush trees on the same location, the brush will automatically discard trees to avoid overlaps according to your density parameters:


To remove trees from the landscape, simply use the right mouse button.

Important: please note that for tree deletion the brush uses only the size value. This means that you cannot lower density by deleting trees (you have to use the density slider when planting them):


Here are the available parameters when planting trees using the forest brush:


Softness: defines how trees are dispatched on the brush boundaries.


Size: size of the brush (minimum size means 1 tree)


Density: tree density (be aware that huge densities may have a performance inpact both in the editor and in-game).


Slope: defines the behaviour of trees on steep slopes.


Height Min/Max: defines random values for trees size. Those values are defined in poucentage of initial height.


If you modify the terrain elevations you will have to update the tree positions according to the new values.

You can use the button for this purpose.

Note: the replant tree button does not take water into account so you must be careful about this and finalise your water level before creating forests.

Particle systems may be placed on the terrain and saved with levels.


It may be helpful to analyse existing particle systems before you create your own.

To spawn a new particle system on the terrain, simply go to the “Existing Systems” gallery and select a particle system (ex: black_smoke) with the left mouse button. Then click inside the viewport and you will see a preview of the particle system bounding box as well as it’s main emitter position:


Note: mouse cursor is centered on the main emitter during system positionning.

Once you selected an appropriate zone simply click on the left mouse button to spawn the particle system:


Please note that if you click again with the left mouse button, you can spawn another system:


Once your finished you have to right click in order to disable particles placement.

You can select any system placed on the level by using the left mouse button. You can then move and rotate the particle system using it’s manipulator:


To add a different particle system simply select it in the gallery and follow the previous steps.


The particles “Select System To Edit” toolbar helps you manage the particles that are spawn in your levels:


From there you can select a system for edition (see next section) or delete selected systems or all systems.


To create a new particle system you have to click on the “new system” icon in the “Existing Systems” gallery:


Once clicked, go to the viewport and you will see a preview of the new particle system bounding box. Left click on the terrain to place it:


This will also open a new particle system editor in the Particles system tab:


Each particle systems has emitters. An emitter is the base element that will generate new particles. All the behaviour of the particles is defined on the emitters.


You can change the emitter’s name by double-clicking on it:


You can also interact with emitters through the palette that appears on the right:


Hide/Show emitter. Very useful if you are working on many emitters.
Duplicate emitter : copies all settings to a new emitter.
Delete emitter.
Move Up : changes the emitter’s rendering order.
Move Down : changes the emitter’s rendering order.

• Emission type: specifies the area of emission for new particles. The values can be:
  
  • Point: a single point in 3D space spawns new particles
    
  • Spray: particles are spawn along a direction vector
    
  • Box: particles are spawn inside a box
    
  • Sphere: particles are spawn inside a sphere
  
  
• Particle type: determines the orientation of the particles (billoboarding):
  
  • Camera Billboard: the particle will be a quad that always faces the camera
    
  • Oriented Billboard: the particle’s quad will have a fixed up vector to (0,0,1). The particles will still face the camera.
    
  • Follow path billboard: orients the particules on their random path (may be useful for waterfalls)
    
  • Clouds billboard: special billboarding mode for cloud like particles. Changes orientation depending on viewing angles.
  
  
• Emitter size: only used with Box and Sphere emission types. Defines the boudings of the emission volume.
  
• Direction: only used with Spray emission type. Defines the direction of the spray.
  
• Position offset: allows to easilly offset the emitter relative to the system’s position.
  Note: you can use this offset during edition to move the emitter away from the others in order to better see your modifications.

• Number particles: maximum particle count for the selected emitter (this setting may have a huge impact on game performance).
  
• Life time (sec): defines the particle life time in seconds
  
• Particle min size: minimum particle size (this value is used by the « Particle size evolution » gradient)
  
• Particle max size: maximum particle size (this value is used by the « Particle size evolution » gradient)
  
• Randomize size: allows to generate random sizes for emitter particles.
  
• Randomize life time: generated random life times based on the global life time value.
  
• Particle size evolution: you can use this gradient control to create custom curves for particle size evolution during particle life time. The gradient control represents the particle life time: the left border of the gradient represents the particle birth and the right side the particles death. The gradient is grayscale: white means 1 (or maximum size) and black means 0 (or minimum size).
  Note: you can add new keys by double-clicking on the gradient zone. Double-clicking on a marker with popup a color picker for color selection.
  
• Rotation particle: allows to rotate the emitted particles.
  
• Randomize rotation: uniform rotations may be too visible. You can break the rotation pattern using this slider.
  
• Speed: defines particles speed.
  
• Randomize speed: allows particles to have random speed based on the main speed value.
  
• Angle: used only for Spray emission type. Defines the angle of the spray (it’s width).

• Lighted particle: if checked the particle will be lighted with ambient and direct light
  
• Lighted 3D volume: special option to fake volume lighting
  
• Lighted ambient only: simplified lighting with ambient term.
  
• Reflection: tells if this emitter will be rendered in the reflection pass (water)
  
• Black Background: special mode for colored particles (like fire flames) to avoid losing original color on bright backgrounds (sky for example).
  
• Infinite projection: renders the particles like if they were on an infinite plane from the viewer (unused).
  
• Particle textures: allows to select up to four different textures for the particles shapes.
  
• Alpha Blending/Additive blending: this sliders allows you to control the amount of blending on the particles. You can choose intermediate values between pure alpha blending and additive blending.
  
• Color: describes the color variation of particles during their life time.
  Note: you can add new color keys by double-clicking on the gradient zone. Double-clicking on a marker with popup a color picker for color selection.
  
• Fade in: a grayscale gradiant that allows to control the particle transparency during their entire life time.

• Gravity: a vector that simulates gravity force. Set by default to Earth’s gravity.
  
• Wind: an additional vector to simulate wind on the level.
  
• Randomize wind: allows to randomize the wind effect.

• Dynamic: specifies if the particles will need position updates during their life time. Required if the emitter has to be attached to a moving object.
  
• Cycle: cycles particles life and death. When a particle dies it’s instantly replaced by a new particle. If not checked, dead particles are not replaced so that the system will disapear after the total life time.
  
• Birth: should particles spawn or be already placed in correct position.
  
• Death: dead particles are not replaced and disappear.
  
• Regular rating: constraints particles births regulary along total emitter life time.
  
• Slowdown: slows down particle velocity during it’s life time.
  
• Link to: enables this emitter to link to another one (may be usefull to spawn new particles after a certain amount of time. Ex: fireworks)
  
• Link to slider: allows to define the birth time of the current emitter based on the linked one (see fireworks system). If you link an emitter this slider will display useful values to synchronise both emitters:
  

Important: be careful when placing huge particle systems into the scene as there may be a high performance cost for them.

Particle systems are saved in the “<Install dir>Data\Gfx\Particles” directory. If you add new particles systems to your levels, be sure that you also include the .particles file with them.

Warning: some existing particle systems are already used in-game (plane_trail, smoke, smokebuilding01, volcano, falling_star, carlights, …). Be aware that if you modify them, it will have an impact on all existing levels.

Once your level is finished you have to save it into an .lvl file (this can also be useful during the edition process).

As mentioned in the Workflow section of this document, the .lvl file is an indirection file to the .land, material .xml and environment .xml files.

It also stores forests and particles internally. To make it simple: a .lvl is a game save file and is your entry point in the game.

Before saving your level make sure that you loaded the correct work files in the title bar:


Then simply click the Save As button on top of the editor:


Give the level a name and save it in the “<InstallDir>\Data\Level” folder where all game levels are located.

Now you are ready to equip your level with resource layers and make it available to the players.

Once you finished your level design, you are ready to prepare your level for the game. The first thing to do is to add resource layers in order to provide vital resources to the players.

Resource layers are simple grayscale PNG files that cover the entire level. White color values tell where a given resource can be found on the map.

In order to create new resource layers, you will need a level screenshot. To make the level shot, you can use the level shot button located in the editor’s Options tab:


Once you made your capture you can use it in you favorite DCC tool (typically photoshop or paint.net) as a mask to create new layers.

Layers must be 512x512 pixels (32bits) in size for performance reasons. You can check the “<InstallDir>\Data\Gfx\Landscape\Layers” directory to compare with existing levels. The level shot created from the editor already has the correct size.

All levels must be stored in the Layers directory to be later referenced in LUA (see next chapter)

You can preview your resource layers inside the editor using the Material tab.

Il the Render Mode combo box, select the SimLayer mode and click on the “click to select a layer image” button located just below the combo box:


Select the layer image you want to preview and you will see it rendered on the terrain:


Here you can see a preview of the water & beach layer.

The material editor also offers a tool that can help you to generate your layer masks.


It has mainly two options:

• Water & Beach: exports an 8 bit 512x512 png file of the water boundaries. You can use this mask in your DCC tool to generate the final layer image or to better follow the water boundaries.
  
• Terrain Layer: exports one of the four material layers as a mask. This option may be useful if you want to match a particular resource (like oil or agriculture) to a specific terrain material. Once again you can use the mask and modify it to generate the final resource layer.

For other layers like citylinks you can use existing layers from other maps or generate new ones.

Note: you are not forced to use this tool to generate your layers. You can start from the level shot and design them from scratch.

Once you finished to design your citylink and resource layers, you will have to link them with the level.

All layers are referenced in the “<InstallDir>\Data\Design\Script\SimInfo\Layers.lua” file.
Each level has a dedicated section that describes all the layers it provides.

Important: In order to not to overwrite the original file and to avoid file conflict with other maps from the community, please create the file with the following name convention: zzz_AuthorName_MapName_Layers.lua.

Important: the zzz_ prefix is important for the game initialization. It's to be sure that the scripts come after the original game scripts.

Here is an example:

Important: the level name on the first line must be lowercase otherwise your layers won’t be found !
The names on the left (keys) must be exactly the same for all your levels.
You can disable unused layers by commenting them with “--“:

The possible layer keys are:

• Sim_CityLinkInterCity_sea : port area layer
  
• Sim_CityLinkInterCity_rail : unused
  
• Sim_CityLinkInterCity_road : intercity roads layer
  
• Sim_CityLinkInterCity_highway : intercity highways layer
  
• Sim_Water: ground waters layer
  
• Sim_Oils: oil-producing areas layer
  
• Sim_Agri: fertile areas layer
  
• Sim_Environment: environment and holidays layers
  
• Sim_SeaSide: coastal area layer
  
• GemSki_Snow: snow area for gem ski
  
• GemSki_ContructArea: construction allowed area for gem ski

To add your new level to the game, please ensure that you prepared a thumbnail for it. You can use the editor to capture a view of your level using the Screenshot button in the Options tab:


Once you saved your screenshot on the disk, you will have to edit and save it to DDS format. The thumbnails must be 256x256 pixels and converted to DXT1 format (without mipmaps). The final image must be saved in the “InstallDir\Data\Interface\DDSTexture\Maps” directory:


You must follow the same format as the other map thumbnails. It’s also better to follow the same naming rules.

Next you will have to create two files in order to reference the new level and make it available in the game:

Important: In order to not to overwrite the original file and to avoid file conflict with other maps from the community, please create the files with the following name convention:
<GameDir>\Data\Design\UnProtectedScript\zzz_AuthorName_MapName_FullMapList.lua
<GameDir>\Data\Design\UnProtectedScript\zzz_AuthorName_MapName_MapList.lua

Important: the zzz_ prefix is important for the game initialization. It's to be sure that the scripts come after the original game scripts.

zzz_AuthorName_MapName_FullMapList.lua: this file will add your map to the list.
Example:

Note: the level name must be added without the .lvl extension.

<GameDir>\Data\Design\UnProtectedScript\zzz_AuthorName_MapName_MapList.lua: this file contains data for the map description that will appear in the map selection menu.
Here you have to match resources to the layers you previously added to your level (see “Adding resource layers” section).
Create the file like this:

Here is a description of the different entries:

• Flags: list of tags that will be used in the map selection filters (possible values are: BEAC_0, ISLA_0, DSRT_0 and SNOW_0 and match the four available filters in the menu).
  Note: if your leave this list empty, your level will disappear when filters are selected.
  
• Resources: this sections defines how many stars will be displayed for all four major game resources. The values range from 0 (no stars) to 3 (3 stars).
  
• Difficulty, Surface and TransportAvailability: pourcentage values displayed in the map description. These values should match your level’s topology.
  
• Image: this field references the previously created map thumbnail (no path required)

In order to be available on the planet, your level has to be assigned to available slots. All slots are listed in the “<GameDir>\Data\Design\Script\Network\offlinedata\PlanetSlotList_bup.xml” file.

The process of finding new slots is fully manual.

First you will have to select a slot ID and verify that it does not appear in the “<GameDir>\Data\Test\SlotMap.cxl” file.

It’s better to add multiple slots for you map so that you can be sure it will have available entries.

Once you have some unique unused slot IDs, you will have to create the file <GameDir>\Data\Design\UnProtectedScript\zzz_AuthorName_MapName_mapsavemgr.lua

Here is an example with three slots:

The text displayed in the map description panel can be localized for all Cities XXL languages.


For each language you will find a corresponding “AuthorName_MapName_MapNames.??” file in the “<GameDir>\Data\Localization\??\” folder where ?? must be replaced by the language code (for example en for english).

In each file there are three keys that you can create:
<LevelNameUppercaseWithoutExtension> : the name of the map (“The Big Island 03” in the previous screenshot)
<LevelNameUppercaseWithoutExtension>_DIFFICULTY: difficulty description
<LevelNameUppercaseWithoutExtension>_DESC: map detailed description
 
Here is an example for our level (MapsNames.en file):


Finally, here are all the files required for your levels (BigIsland_03 in this example) and that you will have to deploy to the game:

• "<GameDir>\Data\Gfx\Landscape\bigisland_03.land"
  
• "<GameDir>\Data\Gfx\Landscape\Layers\bigisland_03_*.png"
  
• "<GameDir>\Data\Gfx\Landscape\Materials\bigisland_03_mat.xml"
  
• "<GameDir>\Data\Gfx\Landscape\Water\bigisland_03.water"
  
• "<GameDir>\Data\Gfx\Sky\bigisland_03_env.xml"
  
• "<GameDir>\Data\Level\bigisland_03.commands.xml"
  
• "<GameDir>\Data\Level\bigisland_03.lvl"
  
• "<GameDir>\Data\Interface\DDSTexture\Maps\BigIsland_03.dds"
  
  
• Any .particles files in the “<GameDir>\Data\Gfx\Particles” folder if your levels brings new particle systems.
  
• Any new cubemaps in the “<GameDir>\Data\Gfx\Sky\Cubemaps” folder.
  
  
• "<GameDir>\Data\Design\Script\SimInfo\zzz_AuthorName_MapName_Layers.lua”
  
• "<GameDir>\Data\Design\UnProtectedScript\zzz_AuthorName_MapName_FullMapList.lua”
  
• "<GameDir>\Data\Design\UnProtectedScript\zzz_AuthorName_MapName_MapList.lua”
  
• "<GameDir>\Data\Design\UnProtectedScript\zzz_AuthorName_MapName_mapsavemgr.lua”
  
• "<GameDir>\Data\Localization\<LanguageCode>\zzz_AuthorName_MapName_MapsNames.<LanguageCode>”

where:

• <GameDir> - is the folder where the game is installed
  
• <LanguageCode> - is the 2 letter language code. For example "en" for English

Be sure to place all those files into the correct locations.

You may have to install the following dependencies (all setup files are provided with the editor inside the <Install dir>\_prereqs folder):

• DirectX SDK June 2010
  
• Sand dock, Sand ribbon & Sand bar.
  
• .NET Framework runtime
  
• Visual Studio 2010 redistributables

If you want to restore the original layout of the editor, you have to follow these steps:

• Close the editor
  
• Delete the file “<InstallDir>\Data_Editor\Editor\Layout\MapEditor.workspace”
  
• Make a copy of the file “<InstallDir>\Data_Editor\Editor\Layout\MapEditor.originalworkspace” and rename the copy to “<InstallDir>\Data_Editor\Editor\Layout\MapEditor.workspace”
  
• Launch the editor again.

The original layout should be restored.

Please check that your level has a dedicated section in the “<InstallDir>\Data\Design\Script\SimInfo\Layers.lua” file and that the level name is lowercase without extension.