Creating a city map
From AI Wiki
Note: Make sure you read the 'Moving you Iam' section prior to this one. Also, make sure to download the latest IamFramework project, as an earlier version might not work completely correctly.
One thing that you'll learn when dealing with Iams is that they have no de facto knowledge of the world they reside in. That is because Blue Mars downloads this data in a format that is basically only usable by the CryEngine. And this is all pre-generated data. There are no live updates of the environment. So if we want the Iam to be aware of its surroundings we also need some form of pre-generated data. This is where 'maps' come in.
As with pretty much everything in the Iam Framework, it's possible to implement your own solution for maps. Each Iam has a 'map' property and as long as you pass it a class that implements the com.avatar_reality.blue_mars.iam.map.Map interface it will work. But generating maps and implementing a class to be used by Iams is probably more work than most developers care for. So a default implementation is provided called com.avatar_reality.blue_mars.iam.map.SparseMap. There are two constructors for this class. One passes a filename of the file containing the map data. The other one also passes the filename of the file containing object data.
These files can be generated by the City Editor application. When you open this application, read a cry-file and then you can select from the menu BlueMars -> Tools -> Create AI Navigation Map. A window will pop up that will contain the map. At first it's empty. It has a few menu-items at the top of the window. Choose Mapping -> Start/Continue to start generating the map. As it progresses you'll see the window fill up with green. If the area mapped exceeds the size of the window, you can move around by right-clicking and dragging. When the whole map is finished the process will automatically stop. But you can always choose Stop from the menu to stop before that.
Next you need to save your map by selecting File -> Save.... You need to select a directory where the files need to go. This will create two files: map.txt and objectlist.xml. These are the files required as parameters to the SparseMap class mentioned above.
Very large maps
Cities or worlds in Blue Mars can potentially be huge. This can also lead to huge map files. And generating these can take a long time. We have done our best to make it as fast as possible, but the sheer size of some of the worlds means it can tax even the most powerful workstation. To create the complete map of IamTown took a standard workstation about half an hour to generate. That produces a 1km x 1km map. And a map-file of over 180Mb. Imagine what it would take to map an 8km x 8km world!
Most likely, you simply can't. And also most of the time it's not necessary. A 1km x 1km area is already quite a large area to cover for an Iam. Beach City is 4km x 4km. Just running your avatar around all that area takes several hours. There are several things we have done to cope with this. First of all, you can simply stop the mapping when you think it has covered all the area your Iam is ever going to need to visit. The mapping always starts at the location of the camera, so if you have different Iams covering different areas you can simply create more than one map. Another option is to limit the mapped area. Already any area too far into the sea is not mapped. And when you select Mapping -> Config... you have the option of entering a boundary box that limits the area that is going to be mapped. You can either enter the coordinates yourself, or you can click the button to use the coordinates of the currently selected object. The latter is handy if you want the mapping to be restricted to say a building. Or to a park. In that case you just create a temporary object spanning the park, select it and start the mapping.
The other effect of large maps is the huge file-size of the maps it leads to. And the large amount of memory your Iam is going to need to keep it in memory. First of all, please know that most JVMs have a default of 64Mb reserved for Java programs. If for whatever reason you need more, which is easy to happen with maps, you can always tell it to use more by using the -Xmx parameter. For example, passing -Xmx256M will enlarge the memory available to 256Mb. Still, you don't want this number to be too large. And anyway many JVMs won't allow you to set it beyond 2Gb, especially on a 32-bit computer. Note that this parameter is a JVM parameter, so it needs to immediately follow the 'java' command. Eclipse users should enter this parameter by selecting Run -> Run Configurations... and selecting the Arguments tab and enter the parameter in the lower box labeled "VM Arguments".
Increasing memory is one thing, when necessary. But there's another way to overcome memory problems. And that is through a tool built into the IamFramework that optimizes the map through compression. Running that tool will greatly reduce the size of map-files and of the memory needed by Iams to keep the map in memory. For relatively small areas, like the Welcome Area, this is not necessary at all. But for bigger areas, like the whole of IamTown, it is highly recommended to pass your map file through this tool before use. It reduces the 180Mb map-file to one of only 10Mb. In the IamTemplate project there's a shell-script called optimize_map that runs this tool. If you open this file you can see how this tool is run using the IamFramework library. The main thing you need to pay attention to is the -in and -out parameters to point to the file that goes in and that needs to come out. For IamTown you don't need to run this script, as the map-file has already passed through the optimizer.
Maps of cities of other developers
Avatar Reality will provide maps for the Welcome Area, IamTown and a partial map for Beach City. Since we don't have access to the Cry-files of cities developed by others, we are not able to provide maps for those cities. If you are a city developer who wants to develop Iams just for your own city then you can generate the maps yourself. If however you'd like to develop Iams that will populate a city you didn't develop, you'll need to get maps from the developer of that city.
Hopefully we'll be able to provide a repository with maps of cities provided by the developers. This is a new feature, so we'll have to see how this develops.