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 (email@example.com)
Please choose a section below:
todo: add something here.
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
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 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:
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
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.
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.
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.