USING AND CREATING SIMULATIONS

Mankyu Sung, Aaron San Filippo

 

This document explains the mechanics of the crowd simulation project, including file formats, methods of conversion, and execution instructions.

Questions, comments, etc. should be directed to Aaron San Filippo (san-fili@cs.wisc.edu)

Please choose a section below:

Part 1: Creating and running simulation.

todo: add something here.

Part 2: Converting and playing back simulations

 

Sim and List file formats

Sim files define the movements and animations of a section of a simulation for all the characters in that simulation. a group of sim files makes up an entire simulation.

sim files have the extension .sim, .sim00, .sim01, etc. A list file is simply a text file that contains a list of sim files to load for a simulation. A typical sim file will look like this:

#time:xPos:yPos:Orientation:action

#60 40



100

1.13322 3.86406 7.0828 90.69 1

2.26644 3.83949 6.08311 105.69 1

3.39966 3.55701 5.12383 105.92 1

4.53288 3.27068 4.1657 45.92 1

5.6661 3.95729 3.43867 15.92 1

6.79932 4.91542 3.15234 16.15 1

7.93254 5.87239 2.86217 16.38 1



101

1.13322 27.4795 19.5525 2.3 1

2.26644 28.4781 19.4998 62.3 1

3.39966 28.9318 18.6087 47.3 1

4.53288 29.6007 17.8653 92.3 1

5.6661 29.548 16.8667 62.3 1

This is a sim file for 2 characters. The first line is a comment, the second line, "#60 40" is the size of the environment in "simulation units." The rest of the document contains N sections, separated by spaces, one for each of the N characters in the simulation. Each section begins with a number, starting with 100 and increasing. Then is one line for each "motion" in the simulation. The first number is the time that the motion starts, the next two numbers are the x and y coordinates where the motion begins, the next number is the rotation about the Z-axis. The orientation is defined so that zero rotation means the character is facing down the positive X axis. The last line is the number of the animation that the character should play during this motion.

A complete simulation contains several sim files, and one list file will contain this entire list. Here's a typical list file:



situationbitmap situation1.tga:this is a situation description

streetdemo.sim

streetdemo.sim00

streetdemo.sim01

You'll notice the first line says "situationbitmap ..." this is a description of a spatial situation, and always contains the line "situationbitmap" then the targa filename, a ":" and then the situation description

Converting models, textures, and animations to the Unreal format

Converting models and animations from Maya to the UnrealEd format is fairly straightforward, and well-documented on the Epic unreal technology website here. The animations in our simulation are collected into a file called crowdanims.ukx, and all the animations are numbered consistently with what the sim files request. So for instance, "1" is the name of the walking animation.

Converting textures is also very easy. Save a bitmap or targa file in RGB or RGBA color mode, then open the UnrealEd editor. There is a button near the top that looks like a texture, click it. There will be a "texture browser" open, and the file menu has an "import" option. There will be an option for "package" which should be "myLevel" if this texture is being imported directly into an environment. If this is a character texture, or some other type of dynamically loaded object, it should be saved into a package specific to that object. choose a name, and click OK. Now you have a texture ready for use!

Making environments with UnealEd

Making environments will involve many intricate details that will not be covered here; Epic's udn site also covers this area in great detail

However, there are some special considerations when creating an environment to work with the crowd simulations. The first is scale. Typically, a bitmap which defines a floor plan in the original simulation will be needed to get a general idea of the shape of the environment. In this case, the bitmap will need to be imported as a texture and placed in a box. The best way to do this is as follows:

  1. Record the dimensions of the original bitmap (for example, in the sim file shown above, the environment bitmap is 60x40
  2. Make sure that the edges of the bitmap are clearly marked. You may need to draw a line around the edge so that when it tiles as a texture, there won't be any confusion
  3. In unrealEd, create a box, which is the width and height of the bitmap, times the scale factor from "simulation units" to unreal units. The scale factor is 54.0
  4. Make sure the box is aligned so that the upper-left-hand side of the box is at the very center of the world, looking down in the top viewport in UnrealEd. If you have trouble finding the center, add something like a light, go to its properties under "movement"  and set its location to {0,0,0}. This will make it obvious where the center is.
  5. Go to the side viewport, and make sure that the bottom of the box is also at the very center of the world.
  6. Take the original bitmap, and resize the canvas size (easy to do in photoshop) so that the dimensions are  powers of 2. Make sure not to resize the image itself, as this will distort the picture and the environment won't match up. We must do this step because the engine only recognizes powers of 2. So if your original floor plan was 13x20, make the dimensions 16x32
  7. Now resize the bitmap to a reasonable scale so that when it's stretched over the environment, filtering won't make the edges too blurry. For example, if the original image was 60x40, you would probably resize the canvas so that it was 64x64, then resize the entire image to 512x512.
  8. Now import the texture into unrealEd after converting it to RGB mode if necessary (grayscale images WILL NOT WORK), and scale/rotate/shift the texture so that it fits exactly inside the box. This can be tricky. You can edit these properties by right-clicking on the surface and going to "surface properties." You may have to manually scale the image, and probably rotate it 90 degrees to make it work. The important thing is that the upper-left-hand side of the bitmap is in the absolute center of the world, so that the simulation will match up.
  9. Now you're ready to create an environment that will match up with the simulation. Just build everything along the lines that the bitmap defines, and everything should work fine. White indicates where the characters can walk, black is a wall or some other type of obstruction.
  10. If you want to add still camera views to the simulation, add any actor (InterpolationPoint works nicely) and put Cam in the tag property (under actor properties\events)

Writing unreal Script files

Unreal script is the language of the unreal engine. Everything technical must be implemented using UnrealScript files, which are then compiled, and then executed at runtime. The udn site defines the language, which is very similar to java/c++. In most cases for this project, We'll be using the CitizenGenerator2.exe program to write the scripts for us.

For our simulations, each character will have a unique unreal script file, which defines the movements that it will execute during the simulation. the naming convention we use for characters is CitizenNNNXXX_.uc

where NNN is the name of the simulation (which is always the same as the List file's name) and XXX is the number of the character in the simulation.

every character is derived from the class citizen.uc, which tells the engine what animations and models to use, how to interpret the motions, etc. In addition, each simulation has a "Manager" file associated with it, which spawns all the characters, and controls restarting the simulation etc. The naming convention for these files is CitizenManagerNNN.uc where NNN is the name of the simulation list file. Each Citizenmanager is derived from the class _CitizenManagerBase.uc

Using the "CitizenGenerator2" program to write character scripts

The program CitizenGenerator2.exe is used to automatically write unreal script files for a given simulation. It will ask for the directory where all the simulations are created, the name of a list file, and the "Z height" of the characters. The Z height will depend on the environment. These can also be passed as command line arguments, in this manner:

CitizenGenerator2.exe simfilesdirectory listfilename actorzheight

 The original simulation assumes that everything happens on the XY plane, but the environment's floor may be offset from this. The CitizenGenerator will look for the list file, and parse each .sim file it contains. It will create a derived CitizenManager class, and write however many character scripts the sim files define. The derived CitizenManager class must then be added to the environment (In unrealEd, find the actor in the actor browser, then add one to the level) and everything should work automatically from there. The citizenGenerator2.exe file must be placed in the directory directly above the classes directory, and will place all the scripts there.

After generating the scripts, it will be necessary to compile the scripts by running UCC.exe in the UnrealEngine2Runtime/system directory, with the command line option "make" Alternatively, you can run the Buildall.bat file to automatically delete the obsolete classes and recompile them, or go.bat to automatically write the classes and build them as a single step.

Using the gui-based converter to write character scripts

As an alternative to the command line program, you can use the gui-based simulation converter which is inside of the crowd simulation system. Simply open up the simulation system, and load up a simulation as usual. Then use the Save/Load -> convert for game engine, to convert the sim files into the unreal format. After this is done, go back to the Save/Load menu, and select "compile for unreal." This will bring up a window with the following options:

After filling out all of these options, hit "Go!" and the simulations should all be converted and all the character scripts will be written into the correct folder in the UnrealEngine2\Research\Classes folder. After the scripts are generated, they will stilled have to be compiled into the unreal format.(see the last section, "Using the CitizenGenerator2 program" for how to do that.

 

Playing back simulations with the Unreal Runtime engine

After the environment has been build, the scripts generated and compiled, and the manager class added to the environment, the environment will be ready for playback. Open the environment map in the engine runtime, and you should see the characters walking around automatically. There are keys to control the simulation, which can be configured in the Settings menu

Where [X] must be configured in the settings menu before use.