From Blue Mars Developer Guidebook
REVISION NOTES:Set up a City - First step is creating the editable city files using the City Editor. This includes setting the terrain size, water depth, and max height, terrain texture layers, environment settings, and vegetation groups. Then either import or paint height map, terrain layers, and vegetation. Next step is setting up blocks within the city, and exporting them so that other people can build their parts of the overall city.
"Cities" are the unit of Blue Mars' 3d environment. City does not imply it has to be urban, it can be all wilderness, or even zero gravity in space.
They are delivered to users in a data package of up to 250MB size with a .pak file extension. This is actually an encrypted 7zip archive, and contains all the unique data for the city. Data common to all Blue Mars users, such as default avatar animations are installed as separate .pak files with the basic software installation, and data common to multiple cities from the same company are delivered as a shared .pak.
The "City Editor" is the main program used to create and modify city data. It is a "what you see is what you play" type of editor, using the same underlying graphics engine as the user software. At any point you can switch from editing to preview mode, and test your work with an avatar. The City Editor includes many features, but this page will mainly cover those for initial setup of a city. Many functions require the RollupBar or Material Editor windows, these can be opened from the View menu.
Directory Structure Setup
Before you do anything else, set up your directory structure for your city. The Blue Mars programs (the editors and the game client), look in specific places to find files.
General Attraction Submission Format - This page has the official instructions, but more explanation follows:
To make it more clear, Company Name needs to be 1-6 uppercase characters like MYCOMP. - Make a top level folder C:\Program Files (x86)\Blue Mars City Developer Tools\Game\Levels\MYCOMP. This mirrors the structure under Blue Mars\Game\Levels where the downloaded cities end up)
- Under ...\Levels\MYCOMP create two more folders: Common and MYCOMP_MyCityName
Under Common, make subfolders named Textures, Libs, Materials, Objects, Scripts, Entities (if you have downloaded the sample data, you can see how it is arranged under the AR\Common directory). Then put all your common assets that you might share with more than one city in the Common folders. This should be most of your data even if you have once city.
Under MYCOMP_MyCityName, that is where you save the MYCOMP_MyCityName.cry file. That is the main file that the City Editor opens when you edit. The other files that are specific to one city will either be placed there automatically, or you should put them there manually.
The automatic ones include:
- level.pak - which includes the terrain map plus other specific level setup data
- MYCOMP_MyCityName.bak & bak2 - which are backups of the .cry file. You should make your own backups somewhere else though, of your entire project folder.
- Layers folder - which holds setup for any blocks you create
- Blocks folder - which holds any imported block data from whoever edits a block file
- level.cfg and MyCityNameTOD.tod - which hold any custom settings you might want to have
- terraintexture.pak - which appears to hold the terrain tiles you paint before they get turned into the generated terrain texture.
If you make custom assets for just that city, then again set up subfolders for Textures, Sounds, Prefabs, Objects, Materials, Libs, Entities, etc as needed
Make sure all your assets used in a city are somewhere in the Common or city folders, and that all the file pointers point to the right ones, and not anything under Objects\MyData, or they will not get packed for upload or shared with a block developer. The exception is any assets you point to in the C:\Program Files (x86)\Blue Mars City Developer Tools\Game\AR_Common.pak file. That is the top level Common assets, which any Blue Mars city level can access. If you open that .pak file up, you will again see the same folder structure for materials, Objects, textures, etc.
When Blue Mars runs in game mode, it treats all Common.pak files in the correct path to your city as part of the folder structure, as if the assets are under the city folder. Anything not in the path to your city cannot be found. Another way to say it is when a city loads, it loads the .pak file for the city itself, plus all common.pak files and common folders found higher in the directory tree up to the Game level.
Note, .pak files are actually 7zip archives, so you can use that program to open them and see what is inside. Once they are uploaded to Blue Mars, and then sent to players, they are encrypted. So they are still 7zip archives, but they cannot be opened by players to protect developer content.
Terrain Map Setup and Painting
The terrain map is normally the first thing to set up for a city, since everything else will be built on top of it. The terrain map size is the product of terrain heightmap resolution (from 128x128 to 4096x4096 points) x grid spacing (1 to 8 meters per unit). Although larger resolutions and spacing are available in the settings, the editor will crash at terrain locations above +8196m in X or Y. Therefore presently maps from 128x128 to 8196x8196m are possible. You can place objects beyond the edge of the terrain map, and into negative X and Y locations. They just will not have the built in terrain under them. You can simulate it with shaped objects and (possibly) voxels.
The maximum elevation of the terrain map defaults to 256m. To change it, use the City Editor main menu: Terrain > Edit Terrain command to open the Terrain Editor Window. Then Modify Menu > Set Max Terrain Height to change the value up to 8196m. Note that altitudes higher than the view distance can cause graphics artifacts when viewing items far below. The minimum elevation is zero meters, and normally the camera view will not go underground.
The terrain map is defined by several components. The "heightmap" defines the elevation (height) of the ground surface at each point on the grid. In addition, each point is "painted" by one of 15 terrain layers. (The 16th is probably assigned to "holes" in the map). Terrain layers consist of a close up material with up to 3 sub-materials for X,Y, and Z axes, a color overlay per point, and a distance texture for viewing at distances. The distance texture allows viewing terrain at larger distances with a low overhead, since it is a simple color map. The detail texture can use the full set of material features, including bump and normal maps. The close up and distance textures are "blended" by distance from the camera viewpoint. Also the terrain layers are blended horizontally between grid points when they change.
The underlying terrain can be overlaid with "roads" and "decals", which are objects that lay flat to the terrain surface and provide spot details close up, while the basic terrain layers fill in the main areas. Decals and roads have 16 SortPriority levels, to define stacking order when multiple items overlap.
Caves and tunnels under the terrain are possible using the terrain hole and voxel tools. Voxels (3d pixels) are patches of higher detail volumes which can be used where needed, letting the main grid spacing be lower to save memory. Voxels can sit on top of the base terrain (or even float above it), or hollow it out below but not below the minimum of 0. Terrain holes can be created with the RollupBar > Terrain > Holes function. As the name indicates, it removes squares from the terrain map, and allows avatars and objects to go under the terrain map.
New Map Creation
In the City Editor, use File > New to create a new map. Enter the name, heightmap resolution, and grid spacing. For production cities (ones that will go live on Blue Mars servers) there are strict naming conventions and folder structure that must be followed. Details can be found on the (need reference) page. The map will not be visible until you save it the first time. There are three main ways to set the elevations across the whole the map:
(1) Open Terrain > Edit Terrain and use Terrain brush tool on the right to paint an elevation map of your design, (2) Use Edit Terrain > Tools > Generate Terrain to make a random terrain map. (3) Import a heightmap in greyscale .bmp format from an external source using Edit Terrain > File > Import Heightmap. The bitmap must be the same size as your heightmap grid.
Small scale details can be adjusted later in the perspective view with RollupBar > Terrain Tab > Modify button.
When setting up a new city, your perspective view at this point may be all black (no sky loaded), or all white (no terrain texture loaded), since the terrain file has not been saved and loaded yet.
Use File > Generate surface texture (4096 or less to start with), to load the default texture and water. Default water height is 15m above grid 0 height. This can be changed in the edit terrain window. Default camera position is 0,0,1 (shown in the console on top right). You can use the mouse or arrow keys to move your view, or use Display > Goto Position and enter XYZ coordinates with spaces.
Use File > Save, & restart city editor to reduce memory. Do this often when doing lots of editing. The default terrain is white, follow Map Painting instructions below to change the default to something else.
Terrain Map Painting
The City Editor shows two different views of the surface texture. You paint the map in editing mode. At that time it shows your inputs. Then you export a "baked" surface texture using File >Generate Surface Texture, and then save it. The next time you start the editor, it will open with the last generated output texture, but as soon as you start painting again, it will switch back to showing the input tiles you paint on. The editing mode contains tiles (sections of the map) which can vary in resolution from each other and from the exported surface texture.
Setting Up the Terrain Painting Tiles
Use Terrain Menu > Export/Import to see current terrain tile layout. You can also export and import color .bmp distance textures from other programs using this function. To change the tiling pattern, use Terrain Menu > Texture to open Layers window, then File > Refine Terrain Texture Tiles in the layers window to split them into 4 parts each. This cannot be undone so think carefully before you do it.
Then under RollupBar > Terrain Tab > Layer Painter, click Tiles Resolution (bottom) Change button. Zoom your view back to see a large part of your city. Move mouse onto perspective view, and a map tile will be highlighted in green, and read out the resolution on the ground. Click an area, and a popup window will let you change the resolution. The painting resolution should be at least as high as your final map output you want, though you can generate lower detail terrain textures while working to save time. You can use lower tile resolution on areas that do not need the extra detail, such as underwater. Once you have your tile resolutions set up, you can create painting layers. Use caution when creating very high detail or many tiles. The City Editor can crash if you do too much. Also high detail maps use up more of your city data allowance.
Setting Up Your Terrain Layers
The default layer seems to cause some errors, so make new ones. Use Terrain > Texture menu to open the window. To add a new layer, click Layer Tasks > Add Layer, then in the Layer column, double click the name in bold and give it your own name. You can have a maximum of 15 layers, so plan to use these for the main landscape areas. Smaller areas can be filled in with roads and decals, both of which can lay flat on the terrain surface.
There are two textures for each layer, distance and detail, which appear at different view distances. The reasons for having two textures is the distance one is a simple uncompressed image, while the detail one is a full material with all the bump, normal, etc maps that can be applied to it. This lowers the workload on the graphics engine in drawing background terrain in the distance. Also the distance layer is at a different scale and can preserve some details when the detail texture would be blurred by distance into a uniform color. The distance layer is selected with the thumbnail image under the layer column, then Layer texture > Change Layer texture on the tasks to the left.
The two types of textures blend at a normal distance of 100 meters. You change this value from the Rollup Bar, select Terrain tab -> Environment button and look for DetailLayersViewDistRatio. A value of 1 = 100 meter blend distance, and scales if you change it.
The distance texture must be uncompressed .dds format. Using Photoshop Nvidia Plugin, the 220.127.116.11 ARGB 32bpp Unsigned option works. The DXT1 or DXT3 compressed format work for other material textures. For the detail texture, click the name under the Material column. The Material Editor tab will appear at the bottom. You can use one of the pre-set AR materials under the folder view on the left at: materials > ar > common > terrain. Click one of them, then go back to Terrain Texture Layers tab, and click Layer Tasks > Assign Material. The item under the Material column should change to the one you selected.
If you want to create your own: right click Material Editor left pane and select add new material from the context menu, then set Material Settings > Shader to Terrain.layer on the right. At the least set the Texture Maps > Diffuse to your chosen texture, and Texture Maps > UV Modifier > Tiling > TileU and TileV. The numbers indicate how many repeats per Unit of surface texture. For example, if your city is 2048x2048, and you set up File > Generate Surface Texture at 4096x4096, then your unit will be 0.5 meter. If you set your U and V repeats at 0.25 then it will map the texture at 0.5/0.25= 2 meters per repeat. So smaller numbers will make the detail texture larger on the ground.
You can also modify an existing terrain material, by right clicking on an existing one, selecting Copy, then clicking somewhere in your City folders and choosing Paste, then save under a new name. Once copied, you can then change it's details.
The other columns on the Terrain texture Layers Tab let you filter when the layer can be applied, by height and slope angle, another Detail Scale multiplier, and what axis the detail is projected from (Z for flat surfaces).
Painting the Terrain
Once you have all your layers set up, you can now go to View Menu > Show RollupBar > Terrain (2nd tab) > Layer Painter button. This works like spray paint. The radius sets the size of a green circle for spraying, and hardness controls how strongly the color filter is applied. You can select your terrain texture from the list at the bottom. This should match the names you set up in the Layers window.
If the PaintLayerID box is off, it will only affect the color, not the texture map, turning it on will change the texture. The small color box under "to Layer" is a color mixer that overrides the base color of your Diffuse texture. If you want to match an existing color, you can use the eydropper to click on something and pick up its color. This tint is temporary while you are using the current layer. To save it click the "to layer" button. This can be used to mass paint an area with your main tint, and then spot paint variations with temporary changes.
Now hover over the area to paint, and click or click-drag to paint spots or larger areas. When done, make sure to click the Layer Painter button again to turn it off, so you don't paint other stuff you don't want to. The green circle will follow your mouse and paint anything it touches. On starting the City Editor, it appears to load your generated texture, but when you paint, it changes any areas you are working on to the "painting level" tiles until you do your next generated texture. Your painting level and the generated texture can be different resolutions and look quite different.
Saving & Exporting Your Map
Modifying terrain heights and layer painting eats up memory. You should have the stats console on which will tell you current memory used. Periodically save and generate surface texture, then restart the editor if you notice the memory used getting high. When you finish working, use File > Generate Surface Texture, then File > Save, to save your work as an output texture. Although the painting tiles are saved automatically as you work, they are not loaded when you start the editor or export the city file, the last generated texture is. Some backups are automatically generated of your city data, but a good file backup plan should be in use beyond this. A lot of work goes into setting up a city, and you are responsible for keeping the original files.
While working, you can generate the surface texture at a lower resolution to see the results faster, and only export a high detail one for a final export. The maximum resolution is the same as the number of height grid points on your terrain. The "Calculate Terrain Sky Accessibility" will adjust the terrain color based on how many objects, such as trees, are shading it. This takes a very long time to calculate compared to not selecting it, so leave that towards the end when you are doing your final map.
Setup for Game Mode
Certain items are required for a city to run properly with users. Place one each of RollupBar > Objects > Entity > Others > Spawn Point and ... > Others > AR > ARDefaultCamera on your map, this determines the default start location for users. Put them close together. Objects in general are added by click-drag from the RollupBar to the perspective view, then click once to drop in place. Once you have these items, use File > Save, then File > Export to Engine. Then you can use Blue Mars > Export > Check City in BlueMars, which will open the login page and let you use your regular avatar to test your city.
Export and Sharing Your City
IMPORTANT: Make sure all model, animation, texture, etc files used in your city are located within your company common or city directories under \Game\Levels, and that references within the city editor in the RollupBar and Material Editor point to the correct locations within that directory.
Assuming you are using the correct directory structure, and COMP is your company name:
File > Save and File > Export to Engine
Blue Mars > Export > Export CTY and Export Common CTY. This will create two .cty files.
To share with other developers for testing:
Use 7Zip and open COMP_CityName.cty, within that archive, go to COMP_CityName folder and copy level.pak and COMP_CityName.pak to an outside folder named the same as COMP_CityName folder.
Open COMP_Common.cty, within that archive, go to COMP folder and copy COMP_Common.pak to an outside folder named the same as the COMP folder. Place the COMP_CityName folder inside the COMP folder, and then send this set of files to whoever needs to test/visit your city in developer mode.
Place the set of folders under Blue Mars City Developer Tools\Game\Levels Create a windows shortcut that points to the \Bin32\BlueMars.exe in your developer directory, and add the following after the program name: -devmode +ar_startlevel COMP_CityName Where the last part substitute your actual company and citynames as used in your .pak file
Specific Item Setup
Static High Clouds: Use RollupBar > Objects > Misc > DistanceCloud
Assign Material in Material Editor from the directory Materials/AR/Common/Clouds/DistanceClouds
Choose a Diffuse texture for it from the folder Game/Textures/AR/Common/Clouds
Scale the cloud item very large and move it up high (1000m)
Adjust the Shader Params in the material to suit. They are specific to the "Distanceclouds" shader
Use Edit > Clone to make a few copies and spread them around the sky
If you want more than one type of high clouds, copy the default DistanceClouds material and past it into your city common directory with a new name, then make the custom cloud type.
Moving Clouds: See notes under [Content Creation]. Under RollupBar > Entity Properties, the SpaceLoopBox is the volume in the sky the cloud will move through. When it reaches the end, it will vanish and re-appear at the starting point (where the object XYZ handles are located). Even though there is a Cast Shadow entity parameter, I think most clouds are too high for it to have an effect. Also, under the Material settings, the "Common.Cloud" shader has specific Shader Params that you can adjust, though we are given about 15 preset kinds in the AR/common/clouds materials directory.
Glass Type Surfaces: Create an object such as thin block for window or mirror. For shiny floors and walls, place the thin reflective layer over the main object surface so the underlying texture shows through. With the object selected set
RollupBar > Brush Params:
- CastShadowMaps: False
Use the following Material settings as a guide:
Shader: Ar_mirror or Ar_glass
Surface Type: mat_glass_fine
Opacity: adjust as needed for the transparencey you want
Diffuse Color: Use from white to slight blue or purple for window glass, but adjust as needed
Specular Level: 1 for windows, 1.5-2 for mirrors
- Diffuse: game/textures/defaults/white.dds for plain glass, or a patterned texture for other glass surfaces
Open the + sign to the left of the Diffuse label for subheadings:
+ Textype: Auto 2D-Map (click + next to Diffuse to open subheadings)
+ TexGenType: Sphere Map
- Bumpmap: game/textures/defaults/white_ddn.dds
- Environment: game/textures/ar/common/environment/ar_default_env.dds
- Opacity: if you are using a patterned glass such as stained glass, use a copy of the Diffuse texture with an alpha channel to define the transparent areas.
- Tint Amount: 0.1-0.4 for clear glass
- Reflection Amount: 5 for window glass
- Fresnel bias: 0.2 for glass, high for mirror
- Fresnel scale: ~5 for glass
Shader Generation Params
- Environment Map: On
- Refraction Map: On for more reflection
Metallic Type Surface:
In the Material Editor, under the Material Settings > Texture Maps:
For Diffuse, use a picture of a metallic surface, such as shiny copper.
For Specular, use a random greyscale reflection map, that varies from black to white, this will give highlights as you move around the object. Click the + sign next to the Specular heading, and use TexType=Auto 2D-Map & TexGenType=Sphere Map.
Under Material Settings > Lighting Settings, Set Glossiness=70 & Specular Level=15 (these are values that looked good to me, adjust to suit yourself).
To create a spherical light source with a dropoff in intensity with distance use these settings:
Use RollupBar > Objects > Entity > Lights > ARSpotLight and place where you want it
- Active = True (turns the light on)
- Radius = Typically 8 for indoor light (in meters)
- Diffuse = choose a color
- DiffuseMultiplier = Typically 5 for indoor light
- HDRDynamic = Typically 2 for indoor light
- Specular Multiplier = 1
- Cast Shadow = True if you want shadows to be cast by objects within the light radius
- Texture = blank for all directions lighting. Have not figured out how to use this for a directional light
- Light Style = 0 for steady light, 1-36 = various flashing & flickering patterns
Time of Day
This is in the Terrain menu pulldown. On the right are settings for how the lighting is done throughout the day. On the left are settings for how time changes during the day.
Game speed is measured in hours of game time per second of real time. That is, if the speed setting is .001, for each second of real time, 1/1000th of an hour will pass in the game. If the game were to run in real time, that is one real day was the same length as one game day, each game hour would have to take 3600 real time seconds (60 sec per minute X 60 minutes per hour). To do that, for each real time second, 1/3600th of a game hour would have to pass, so the speed would be set to .000278 (decimal equivalent of 1/3600). To have the game day last 6 hours of real time it would have to run 4 times faster than real time, so each game hour would have to take 4/3600 real time hours. To do this the speed would be set to .001111.
Note that when using the Time of Day flowgraph node, the TOD setting is in hours and fractions, so 6.5 is 6:30 AM and 17.75 is 5:45 PM.