utrecht university crowd simulation unity3d plugin manual · the computations of the positions to...

1 | U U C S p l u g i n f o r U n i t y

Utrecht University Crowd Simulation Plugin for Unity3D: The Manual Version 2018-11-05. The most recent version is available at www.ucrowds.com.

This manual provides background information for the Utrecht University Crowd Simulation (UUCS) Unity3D plugin, version 1.2. The plugin is compatible with 64-bit Windows applications1. We optimized this version for Unity3D version 2018.2.10f1.

The UUCS plugin is a framework that provides advanced tools for simulating a crowd of agents, based on 10 years of research at Utrecht University and abroad. It embodies four main functionalities:

• Modelling the navigable environment and computing an exact navigation mesh;

• Setting up a scenario; • Performing an interactive simulation; • Making analyses.

The UUCS plugin allows programmers to develop applications that need realistic movements and behaviors of agents in virtual environments featuring e.g. big infrastructures, events or computer games. You can easily set up a crowd using the provided GUI, or use scrips that directly talk to the UUCS API.

In short, the plugin offers the following features.

1 We have also compiled the plugin for the following OS’s: iOS, Linux, MacOS and Windows. Please contact us at [email protected] if you are in need for one of these.

http://www.ucrowds.com/

https://www.staff.science.uu.nl/%7Egerae101/UU_crowd_simulation.html

mailto:[email protected]


Modelling the navigable environment

• Creating (static) 2D layers of walkable parts and obstructed parts • Performing Boolean operations on 2D polygons [new] • Composing a 3D multi-layered environment • Computing an exact navigation mesh

Setting up a scenario

• Placing building blocks, including start, goal and action areas • Creating agent2 profiles • Setting agent characteristics

Simulation

• Moving possibly thousands of agents in real time3 • Creating global indicative routes with some desired amount of clearance to

obstacles • Employing realistic collision avoidance • Incorporating social groups • Interpolating between individual and flowing behaviors • Re-routing based on local density information • Adding and removing dynamic obstacles • Adding your own behaviors

Toolkit

• Analyzing crowd density [new]

To demonstrate features of the plugin, we have also built several Demo scenes. You can find more information about the demos at the end of this manual.

We assume that all geometry has been modelled in meters, and, consequently, all distance-related parameters assume that one unit means 1 meter. For instance, the agent’s speed is measured in meter/second.

2 We use the terms agent, character, pedestrian interchangeably. 3 The number of real-time simulated agents is based on your device’s performance.


0. Background

Navigation mesh We developed a data structure that represents the walkable surfaces in virtual environments, and how to update this structure dynamically and efficiently when the environment changes. We refer to this structure as a navigation mesh, i.e. the Explicit Corridor Map. This is an exact decomposition of the walkable surfaces into simple, non-overlapping shapes, plus and underlying graph providing the global network, represented as a medial axis / generalized Voronoi diagram. The combination of the mesh and network enables efficient crowd simulations4. Please refer to Figure 1 for an example of such a navigation mesh for a simple 2D and 3D environment.

Figure 1: The Explicit Corridor Map navigation mesh displayed on top of two environments. (Left) This 2D environment consists of a bounding box and a red U-shaped polygonal obstacle. While being 2D, its obstacle vertices may live in a non-flat 3D world. The network graph consists of nodes (big black discs forming the decision points) and edges connecting the nodes. Closest-point connections to obstacles have been added to decompose the navigable environment into a (minimal) set of non-overlapping and fully covering, simple cells. (Right) A similar structure was computed for a multi-layered environment. Such an environment consists of 2D environments, stitched together in connections (red lines) that appear between shared pairs of obstacle vertices.

Crowd simulation framework Our crowd simulation framework breaks down movement in five steps, ranging from global (AI) planning to local animation, see Figure 2. This facilitates much control in each level as well as realistic crowd behaviors.

Let us visit each level of planning.

4 This navigation mesh was designed to be efficient due to having three unique features. That is, there are a (theoretically) minimal number of decision points in the graph (i.e. only O(n), where n is the number of vertices describing the obstacles. In comparison, its number of decision points are lower than in a triangle navigation mesh. In addition, the mesh allows to compute nearest obstacle points to an agent in (on average) O(1) time, making collision avoidance cheaper. Finally, the mesh handles variable agent discs as well paths with a variable amount of minimum distance to obstacles.


Figure 2. A five-level hierarchy for crowd simulation.

High-level planning: Agents determine their global actions, and each action results in a geometric path-planning query (i.e. “move from point A to point B”). In this phase, we support for instance social groups, large groups, and re-planning of agents when the navigation mesh changes or when crowd densities change.

Global route planning: Given the start and goal position of an agent (or a group of agents), we compute a so-called indicative route that the agent (or group of agents) should globally follow during the simulation. Our navigation mesh can generate various types of indicative routes, such as short paths with some amount of minimum distance to the obstacles, or paths that avoid areas with a high crowd density. Indicative routes can also be optimized for camera movement or stealth movement. In addition, you can provide your custom indicative routes.

Route following: In each simulation step, the agents compute an attraction point on their current indicative route, and they compute their preferred velocity (i.e. their preferred walking speed and direction). We have also developed a route-following method that allows agents to have personal preferences for different terrain types.

Local movement: In each simulation step, each agent converts its preferred velocity to an actual velocity that adheres local rules. These rules include resolving collisions with other (moving) agents, avoiding possible future collisions, adapting the velocity to the local crowd flow, and maintaining coherent social groups. When all velocities have been computed, the agents apply their velocity for one simulation step, and the next step begins.

Animation: In many applications, the crowd should be visualized smoothly in real-time. In our model, this task is delegated to Unity3D.

More information about the framework can be found in Chapter 10 of Wouter van Toll’s PhD thesis on Navigation for Characters and Crowds in Complex Virtual Environments.

https://www.staff.science.uu.nl/%7Egerae101/pdf/PhD_Thesis_Wouter_van_Toll_Navigation_for_characters_and_crowds_in_complex_virtual_environments.pdf


1. Crowd Simulation Environment The Crowd Simulation (CS) Environment is the starting point for setting up a simulation. The CS Environment manages all Layers, Walkable Areas, Obstacles, Characters, etc. It is also responsible for updating the simulation.

A CS Environment consists of one or more Layers. Layers hold all objects that describe the geometry of your simulation, Characters, Spawn Areas and more. You can create a Layer by making an object with a Layer script component and setting it as a child of the CS Environment. To these Layers you can add Walkable Areas that define the geometry your Characters can walk on. You can also add Obstacles that will be avoided by the Characters.

License The plugin needs your license information. Before you use the plugin, please contact us via [email protected] to receive a user account. You can set your password via an API call. The user ID, user email address, user password, license ID and license key are necessary to activate a machine and validate the license key, which can be input through the shown GUI window or a scripting API (see Figure 3). The crowd simulation functions in the plugin cannot be used without valid license information.

Figure 3. A part of the UUCS GUI.

The plugin will generate a fingerprint code locally to identify your machine. Please do not upload it online or share it with others through any way such as Git. This code should be kept carefully in your local folder. Deleting the code or storing more than one code may limit the number of machines on which the plugin can run.

Settings Before starting the simulation, it is possible to change several settings.

Default Control Mode: This refers to the default control mode of characters. For the character without specified control mode, the plugin assigns the default control mode to it. UUCS Only mode indicates that the plugin computes the characters’

mailto:[email protected]


velocities and positions itself. By using the UUCS Velocities with Unity Position mode, the plugin computes the characters’ velocities, feeds them to Unity3D, and defers the computations of the positions to Unity3D. As an example, this allows you to connect Unity3D’s physics engine easily with the UUCS plugin, or to program and use your own collision-avoidance method. The last mode, i.e. UnityOnly mode, indicates that characters are completely controlled by Unity3D. The plugin still takes these characters into account while simulating other characters so that characters in other control modes can deal with e.g. collision avoidance. Note, while the simulation runs, you can change each agent’s control mode.

TimeStep: The fixed time step of the simulation, in seconds. Every time the simulation is updated, it is advanced by this value. Under UUCSOnly control mode, a value of 0.1 seconds is generally a value that gives accurate results for pedestrians that typically walk with a speed between 0.2 m/s and 2 m/s. Having a smaller time step yields smarter (but less human-like) collision-avoidance behaviors, but takes more time to compute. For instance, a value of 0.05 will lead to a simulation that roughly takes up twice as much CPU time. We do not advise to use a smaller time step to create smoother animations. For that, use interpolated motions. Smaller time steps may be needed though when the character’s speed is higher than 2 m/s. Under UUCS velocity mode, you may need a bigger time step such as 0.2 or 0.3.

Seed: The random seed for the simulation. Set it to -1 for a random seed. The seed is used for instance to compute random free character positions within a spawn area.

Thread Count: The number of threads used by the simulation. Set this value to 1 to disable multi-threading, or to a value above 1 to specify the number of threads. With a value of -1, the optimal number of threads is determined automatically.

Build on Start: When the application is started or an Environment is created at runtime, the navigable environment is immediately built and the simulation is immediately started. If this option is disabled, you can manually override the default behavior of the Environment.

States To create a fully functioning crowd simulation, the CS Environment needs to go through several states. In these states, all Walkable Areas and Obstacles are converted to a navigation mesh and all required initializations are performed. When the Build-on-Start option is enabled, this will happen automatically when you run your game. When you do not use this option (for example, because you wish to extend the framework), you will need to go through the different states manually by calling the appropriate methods.

There are different states:

Editing: In the Editing state, the settings mentioned above can be changed.


Modelling: In the Modelling state, all Layers and their Walkable Areas and Obstacles are gathered. Their meshes are filtered; see the Walkable Area and Obstacle class for how their meshes are filtered.

Simulation Created: The resulting geometry of the previous state is converted to a triangle mesh representation from which the Navigation Mesh can be generated.

Navigation Mesh Generated: All geometry is converted to the Navigation Mesh that is used internally.

Simulation Prepared: The simulation is initialized and ready to run. At this point, Characters can already be added to the simulation.

Simulation Running: The simulation is running. All Characters, Spawn Areas, etc., are updated.

Simulation Paused: The simulation is paused. It can be restarted again by calling the RunSimulation Method.

Simulation Destroyed: The simulation is ended and destroyed.

Errors The CS Environment reports errors when it encounters problems. Which errors are reported can be changed by configuring the ErrorLevel. There are four different levels:

High: Every error throws an exception.

Medium: Critical errors throw an exception, and other errors display a message in the console.

Low: Every error displays a message in the console.

None: No exceptions are thrown and no messages are displayed.

API

Although with just the GUI you can already set up an entire crowd simulation, it is often useful or even necessary to use code to control your simulation. The UUCS Framework is easily accessible using its API. All classes are located in the UUCS.Framework namespace.


2. Layer A Layer describes the walkable geometry of the simulation. This geometry is defined by adding Walkable Areas and Obstacles to the Layer: objects with a mesh and a Walkable Area or Obstacle component. These meshes are allowed to have 3D-coordinates. However, all geometry within a Layer is ‘flattened’ when the navigation mesh is computed. That is, the Walkable Areas are merged together by projecting them onto the ground plane. The Obstacles are then subtracted from the Walkable Areas, resulting in the final walkable geometry (and corresponding navigation mesh).

3D Environment To create a 3D walkable environment, you need to create multiple Layers. On each Layer, you can then add Walkable Areas. Note, these areas are not automatically connected to other Layers, so characters will not be automatically able to walk from one to another Layer. You can fix this by using Connections.

Connections To allow Characters to walk from one Layer to another, Connections between Layers need to be defined. Currently, Connections are only supported through the Scripting API and are not accessible yet through the GUI.

Connections can be added during the Modelling state. Usually, the Environment goes through all states automatically when the application starts. To prevent this, you need to disable the Build On Start property. To add Connections and build and run the Environment, you need to call several methods.

To go through the Modelling state, you need to call the Build method. With the AddConnection method, you will then be able to add connections between Layers. Once you have done that, you can go through other Environment states by calling methods CreateSimulationEnvironment, ComputeNavigationMesh, PrepareSimulation and RunSimulation. An example project is included in the plugin.

Figure 4. Two walkable areas that are placed on separate (differently colored) layers.


Connections have two constraints. First, the connection should be shared exactly by the same edge on both Walkable areas residing in the two Layers. Each end of the edge must end up in an obstacle’s vertex. Second, the first Layer parameter you pass to the AddConnection method should lie to the left of the line defined by the Start Point to the End Point. If these constraints are not met, characters will not be able to move between the two layers.

We are aware that this process is cumbersome and prone to errors. Therefore, we are working on an extension to the UUCS engine, which can automatically extract a multi-layered navigation mesh from an arbitrary 3D polygonal input mesh. We refer the reader to the below figure for an impression of this process. This process fixes mesh errors, computes intersections, removes polygons that are too steep, carves out areas where the characters would bump its head, creates a valid triangle navigation mesh, decomposes the environment into a small set of layers and connections, and finally, produces a multi-layered Explicit Corridor Map.

Figure 5. A polygonal environment is converted into an exact multi-layered navigation mesh.


3. Walkable Area

A Walkable Area can be made a child of a Layer to define the walkable geometry of the CS Environment. The Mesh of the Walkable Area object then becomes part of the Layer together with the other Walkable Areas on the same Layer. Overlapping areas are allowed and merged so that Characters can walk from one Walkable Area to the other.

When where is a (very) tiny gap between two Walkable areas, a character cannot directly bridge this gap. You need to resolve this modelling error manually.

Filtering Before the Mesh of a Walkable Area is added to the CS Environment, it is filtered. All geometry that does not point upwards is ignored. If you would add a Walkable Area with a sphere Mesh, only the upper half of the geometry will be used. The bottom half of the sphere is filtered because it points downwards. Triangles that are too small (e.g. triangles that have an area of nearly zero) are filtered out as well.

Figure 6. Two walkable areas on the same layer that will be merged into one walkable area.


4. Obstacle To make some parts of the Walkable Areas unreachable, for example because there is a car blocking the road, it is possible to add Obstacles to the Environment. You can add Obstacles by making an object with an Obstacle script a child of a Layer. There are several methods to define the area of the Obstacle which will be non-walkable. Please refer to Figure 7 for an example.

Mesh: The first option you have is to use a 3D model. By giving the Obstacle a Mesh Filter, the Mesh geometry is projected onto the ground plane, its union is formed, and this union is used to make the Walkable Areas unreachable on the same layer. The Mesh is filtered in the same way as for Walkable Areas.

Convex Hull Mesh: When you enable this option, the convex hull is calculated and then added as an obstacle to the Environment.

Primitives: Such a primitive does not need a Mesh, but it generates a basic obstacle, for example in the shape of a circle.

Figure 7. Three different ways of computing an obstacle’s footprint for a given mesh: Mesh, Convex Hull Mesh, and Primitives.

Removable Obstacles Normal Obstacles cannot be added or removed during runtime. They are completely static. To create dynamic Environments, you can use Removable Obstacles. Removable Obstacles can be added and removed (and enabled or disabled) once the simulation is running. Characters will automatically start moving around the Removable Obstacles.

Removable obstacle is only permitted to have a convex shape, so the Convex Hull Mesh option is checked in default. In addition, they are not permitted to intersect with other (static or dynamic) obstacles. In the current implementation, they may cause the main application to stall when too many updates are requested simultaneously.


5. Character You can make any object a Character by adding a Character script to it. You can give each Character a goal. They will automatically find a path to that goal, if such a path exists in the walkable space.

Character Profiles To control the properties of Characters, you can give them a Character Profile. Character Profiles can be created and edited from the UUCS Character Profile window.

A Character Profile has many different properties. The two most important properties are the Radius and Preferred Speed in m/s. They control the size of the Character and the speed at which the Character will try to move. To ensure the Character behaves realistically, you may need to set the Radius to the physical body size of your Character.

There is a large number of properties that control the way Characters find their way to their goal positions or areas. Changing these is usually not necessary. The default values may already give good results.

Character Control Mode You can indicate three ways in which a Character is controlled: by the UUCS only, by UUCS Velocities with Unity Positions, or by Unity.

UUCS: Such a character indicates that the character is completely controlled by the UUCS plugin. The character’s position is updated directly by UUCS in each time step.

UUCS Velocities with Unity Positions: In this mode, the UUCS plugin computes the desired velocity for this character in each time step, while Unity3D physics engine is in charge of updating the character's position and reporting it back to the engine.

Unity Only: You can take full control of a Character and move it in a specific direction instead of letting it follow a path. You would typically use this for the Player object that has to be controlled with the user's input, while still being part of the simulation. Normal Characters (for example NPCs) still avoid such characters.

Character Groups Characters can be added to a Character Group. Characters in such a group share their goal position and try to stay together, forming a social group. This means, whenever you change the goal of a Character, that all other Characters, who belong to the same group, will start moving towards that new goal as well. In the Character Setting, if you give the same Group Name to several Characters, then the UUCS plugin will bundle them together into one group.

Similar to Character, a Character Group also has options Control Mode and Initial Goal Area. Through assigning values to these options, the corresponding values of children Characters in the Character Group will be automatically assigned.


Figure 8. Three Character Groups walking on a layer.

A Character Group works best if the group size is between 2 and 4. In the future, we add the functionality that a big group is automatically split up in sub-groups.

You can make a Character Group by adding a script to an empty object with Character children. If the Character Group object does not have any Character child, the group will not work.

Note, we modelled a character group as a social group. Consequently, characters have a wish to stay together. If one member stays behind, the rest will wait. Consequently, the waiting members may block a certain passage.

Set Height If you want the Characters to always walk on the floor (instead of the projected navigable mesh), you can set Set Height to true. The Y-offset is the height offset when the Character moves on the walkable area.


6. Spawn, Goal, and Activity Areas Instead of adding Characters in the Unity Editor or through the Scripting API, you can use Spawn Areas and Goal Areas. These objects automate the spawning of Characters.

Spawn Area: You can use such an area to automatically instantiate Character prefabs. They can create Character Groups at regular intervals with random Character prefabs. Character Groups with size 1 (actually a Character), 2, and 3 can be directly assigned. Other Group member combinations could be implemented through a script. You can also set a limit to the number of Characters a Spawn Area can create.

Figure 9. The spawn area GUI.

Goal Area: You can immediately give a Goal Area to a character by selecting one in the Spawn Area settings. If you select multiple Goal Areas, Characters are given a random destination. You can also set a limit on the number of Characters a Spawn Area can create.

Activity Areas: Such an area defines a region within your scene for which the Characters can be retrieved that entered, left or is residing within this area. Activity Areas are especially useful to trigger location-based events within your application.

As shown in Figure 10, the activity area records that the purple Character is inside the rectangular area and the yellow Character has just entered the area.

Figure 10. An activity area


7. The GUI window

Creating and Modelling Objects The GUI for setting up a crowd simulation environment consists of three stages:

1. No active Environment is present in the hierarchy: each simulation needs an Environment object since this is the root of the simulation. If there is no active Environment object, the GUI displays the layout for creating an Environment object;

2. An active Environment has been found in the hierarchy: the GUI displays the option for creating and modelling crowd simulation objects;

3. Unity enters play-mode: the GUI becomes inactive and stops updating the crowd simulation objects.

The figure below displays the workflow of the GUI.

Figure 11. Workflow of the GUI.

Highlighting Surface Area The GUI contains an option to display the highlight area of the current layer. This option creates a clear 2D representation of the Walkable Areas, the Obstacles, and the Spawn, Activity and Goal Areas in the scene. For Obstacles that lie partially outside of a Walkable Area, the highlight mesh of the obstacle may stick out a little of the Walkable Area due to visualization purposes. The Walkable Area’s highlight


surface has a green color; Obstacles are red, Spawn areas are magenta and Goal areas are blue.

The GUI contains three options for the highlight area:

Toggle on/off: the GUI contains a toggle for turning the highlight area on or off.

Re-compute: since we do not update the highlight area in real-time (because the computational complexity for larger scenes may be high), there is a button to re-compute the highlight area, e.g. for when an object is moved.

Toggle render meshes: toggle the render meshes of the layer objects for more clarity.

Figure 12. An example of how the highlight-area functionality looks like.

Multiple Environments You can create multiple Environment objects in the hierarchy. The GUI uses the most bottom one from the hierarchy, because of how we search through the hierarchy on setup of the GUI.

The crowd simulation plugin only accepts one Environment. When multiple environments are detected, the GUI will display a warning message.


8. Character Profiles Each character in the UUCS Unity Plugin has exactly one character profile. These profiles can be added, deleted and edited in the character profile window of the UUCS Unity Plugin.

Figure 13. The Character Profile GUI.

The profiles are saved in one single file. There is no practical limit for the number of profiles in one file. Only one profile file can be loaded into the plugin at the same time. In the character profile many properties are defined. To save time, a profile can be given a parent. If a parent is assigned to a profile, it will inherit the same properties as its parent, except the properties that are explicitly changed in the child.

Loading and saving When opening the Unity plugin for the first time, a file called characterprofiles.cfg will be made automatically with the basic character profiles in it. To save this file with a different name, press the Save as… button. To load a different file, press the Load button. To simply save the file, press the Save button.

Creating a new character profile To create a new character profile, it is necessary to open the 'Create new character profile' fold out. When folded out, a name can be given to the profile. Here, it is also possible to select whether the profile should be based on another profile or should just have the default values. When a parent is selected, the details of this profile can also be edited. After pressing the ‘Create’ button, the profile will be added and the file will be saved.


Editing character profiles To edit a character profile, the first thing that needs to be done is to open the Character Profiles fold out. After that, the profile that needs to be edited can be opened. Here it is possible to edit all the properties. If a property is edited, the properties of its children are also automatically updated, except the properties that were edited by a user.

Properties Character profiles have the following properties:

Basic You have access to the following options:

Name: The name of the profile. Must be unique.

Parent: Optional. If a profile has a parent, all its the properties are inherited, except the ones that are explicitly changed.

Radius: The radius of the disc (in meters) around the character. The character will always try to keep this distance from each other and objects. Users are encouraged to keep the radius low. You may need to keep this value always coherent to the physical body size of the Character.

Preferred Speed: The speed of the character in meters per second. The character will try to walk in this speed but will slow down if the space is too crowded. We calibrated the internal engine to work well with speeds up to 2 m/s.

Trace Path: A true or false value that defines whether the character will save its path to the memory.

Advanced Streams Model Options You have access to the following options:

Use Streams: A true or false value that defines whether the character will use the ‘streams’ method. This method interpolates between individual (preferred) movement, and collective (flow-based) movements.

Internal Motivation: The value of the internal motivation of the character according to the ‘streams’ method. The value ranges from 0 to 1. This property is only used if the Use Streams property is set to true.

Deviation Minimum: The minimum of the deviation (in degrees) of the character according to the ‘streams’ method. This property is only used if the Use Streams property is set to true.

dMax: The value of the ‘dMax’ (in meters) of the character according to the ‘streams’ method. This property is only used if the Use Streams property is set to true.


Streams Viewing Angle: The value of the field of view (in degrees) of the character according to the ‘streams’ method. This property is only used if the Use Streams property is set to true.

Advanced Path Planning Method Options You have access to the following options:

Path Planning Method: The method of path planning that the character should use. There are three different implementations available:

ECM Medial Axis: The Explicit Corridor Map method is used to compute a corridor, and then the medial axis is used as an indicative route.

ECM Side Preference: The Explicit Corridor Map method is used to compute a corridor, and then a fractional side of the corridor is used as an indicative route.

ECM Short Path with Clearance: The Explicit Corridor Map method is used to compute a corridor, and then a short path with a preferred amount of clearance (distance) to obstacles is used as an indicative route.

Side Preference: The value of side preference the character considers during path planning. The side preference defines the bias for walking along a certain “side” of the corridor. The value ranges from -1 to 1. A value of -1 corresponds to the left side of the corridor and 1 corresponds to the right side. This property is only used if the Path Planning Method property is set to ECM Side Preference.

Side Preference Noise: The maximum noise value that is added or removed to the side preference at each point on the indicative route during path planning. This property is only used if the Path Planning Method property is set to ECM Side Preference.

Preferred Clearance: The distance in meters that the character prefers to keep from obstacles. This property is only used if the Path Planning Method property is set to ECM Side Preference or ECM Short Path with Clearance.

Density Weight: The sensitivity to density-based delay that the character considers during path planning. A value of 0 means that the character chooses the shortest path on the medial axis. A value of 1 means that the character chooses the (expected) fastest path on the medial axis. A higher value means that the character will be more sensitive to expected delays.

Density Viewing Distance: The path length in meters along which the character can use density information during path planning.

Density Re-planning Time: The number of seconds after which the character should re-plan its current path. A value of 0 or less means that the character will not re-plan its path.


Advanced Plan Method Options You have access to the following options:

Path Follow Method: The method of path following that the character should use. There are two different options:

• IRM: The Indicative Route Method (IRM) of Karamouzas et al. is used to compute attraction points.

• MIRAN_Unweighted: The Modified Indicative Routes Method (MIRAN) of Jaklin et al. is used to compute attraction points; weighted region exclusive.

• MIRAN_Weighted: The Modified Indicative Routes Method (MIRAN) of Jaklin et al. is used to compute attraction points; weighted region inclusive.

Sampling Distance: The sampling distance in meters that the character uses during path following. This property is only used if the Path Follow Method property is set to MIRAN.

Look-ahead Distance: The look-ahead distance in meters that the character uses during path following. In MIRAN this is called the shortcut parameter. This property is only used if the Path Follow Method property is set to MIRAN.

Advanced Collision Avoidance Options You have access to the following options:

Collision-Avoidance Method The method of collision avoidance that the character should use. There are five different options:

• None: No collision avoidance is used. • Velocity-Based Karamouzas: The velocity-based approach to collision

avoidance by Karamouzas and Overmars is used. • Vision-Based Moussaïd: The vision-based approach to collision avoidance by

Moussaïd et al. is used. • ORCA: The ORCA method by van den Berg et al. is used for collision

avoidance. • Vision-Based SGN: The Social Groups and Navigation (SGN) vision-based

approach to collision avoidance by Kremyzas et al. is used.

Max Neighbours: The maximum numbers of nearest neighbors that the character checks during collision avoidance. The recommended value is 5. This property is only used if the Collision-Avoidance Method property is set to Velocity Based Karamouzas.

Radius Personal Space: The radius (in meters) of the personal space of the character during collision avoidance. This property is only used if the Collision Avoidance Method property is set to Velocity Based Karamouzas.


Viewing Angle: The angle (in degrees) of the field of view of the character during collision avoidance. This property is only used if the Collision-Avoidance Method property is set to Vision Based Moussaïd or Vision Based SGN.

Advanced Group Forces Options You have access to the following options:

Group Forces Method: The method of group forces the character should use. There are three different options:

• None: No group forces are used. • Moussaïd: The group forces method by Moussaïd et al. is used. • SGN: The Social Groups and Navigation (SGN) method of Kremyzas et al. is

used to compute group forces.


9. Toolkits Under the ToolBox folder, you can find some useful scripts, which might be helpful to build a perfect crowd simulation environment or do crowd density analysis.

Polygon Process When you want to build an obstacle with a customized shape, you may want to use some polygon process functions to operate your polygon. Five functions, i.e. polygon subtraction, polygon union, polygon simplification, polygon convex hull and building mesh, are offered in PolygonProcess.cs. It should be noted that polygon subtraction and polygon union return vertices of triangles, rather than vertices of polygons. You can build a mesh based on these triangles through the function BuildMeshWithTriangles.

Figure 14. With Polygon subtraction, you can easily build an obstacle with walkable holes.

Density Map You can analyze pedestrian flows and crowd densities by the Density Map tool. By directly dragging a DensityMap prefab into the scenario, as a child of a layer, a crowd density grid will be automatically calculated during the simulation.

Figure 15. The density map GUI.

It has the following properties:

Boundary: If this option is disabled, the program will decide the measurement range based on the layer boundary. Otherwise, you can specify a measurement range yourself.


Low-, average- and high-density map: Check these three boxes depending on your needs. Only the enabled density map will be calculated during the simulation. You can disable unnecessary density maps to increase the simulation performance.

Draw density map: A density map could be obtained by an array of grid data. Moreover, you can export a density map as a PNG-image file, where a high-density grid has a lighter color and a low-density grid has a darker color. The images are stored in the folder StreamingAssets/UUCSFiles.

Automatic save: If you check this box, the density maps will finish calculation when the simulation ends. If you turn on the draw function, you will get density map images. Otherwise, you can get the data of the density maps after a specified time.

Figure 16. Low, average and high density maps of one simulation.


10. Example demo’s

A simple crowd In this scene, we set the Default Control Mode in Environment Settings as UUCS Only. The Time Step, the Seed and the Thread Count were assigned as 0.1 -1, 0, respectively.

Three planes were connected to represent the Walkable Area in a layer. Obstacles (red) in cube and sphere shapes were placed on the way between a Spawn Area (light blue) and a Goal Area (light green).

Figure 17. A screenshot of the Basic scene example.

There were five types of characters in the Spawn Area’s Character prefabs, i.e. normal character, characters with slower and faster walking speeds, and characters with bigger and smaller body radius. All characters generated by the Spawn Area had the same Goal Area.

Figure 18. A small crowd in the Basic scene example.


During the simulation, we could find that individuals with higher speeds (in blue) reached the Goal Area earlier than others did. However, when the fast character walked with other characters, its speed slowed down to stay coherent with others. Once the character had reached its goal position, it stopped moving.

Dynamic obstacles, social groups, and a playable character In this scene, we set the Default Control Mode in Environment Settings as UUCS Velocities with Unity Positions. The Time Step, the Seed and the Thread Count were set to 0.3, -1, 0, respectively.

Figure 19. A screenshot of the Advanced scene example.

Figure 20. A removable obstacle was placed at the middle of the ramp.

Please refer to script LifeLine.cs. It shows how a removable obstacle was placed at the middle of the ramp, and how it was added or removed to the environment every 20 seconds.


A playable Character (in pink), whose Control Mode was switched to Unity Only, could be operated by the user (see script PlayerCharacter.cs). When you click your left mouse button, the playable Character will directly move to the corresponding position on the walkable area and other Characters will keep distances from it. However, this Character moved to the target position without considering Obstacles since it was excluded from the path planning. If you would like to take the walkable environment into account, you can switch the Control Mode of the playable Character to UUCS Velocities with Unity Positions or UUCS Only.

The orange and yellow Characters were given the same Group Name, i.e., Group 2, so they were bundled in the same Group. The Characters in green, blue and purple had the same parent, i.e., a Character Group object, so they were also in the same Group. The Characters in the same Group always kept close to each other and moved to the Goal Area together.

Figure 21. Simulating social groups.

During the simulation, when the removable obstacle was not in the scene, Characters could move in the middle of the ramp. However, once the removable obstacle appeared, Characters could only avoid collision with it and detoured to the Goal Area.

Multi-layered Scene In this scene, we built ramps between two walkable areas, which we separated into two layers. The Spawn Area was located at the ground layer and the Goal Area was placed at the first layer. Two layers were connected through script Connection.cs. The Connection script was attached to the Environment object. It had four properties set using the Unity Inspector, i.e., two layers and the connection points. We disabled the Build On Start option in the Environment Settings such that we set up the environment in the Start function in Connection Script. Between the function Build and the function CreateSimulationEnvironment, we inserted function AddConnection. The positions of the Start Point and the end Point were measured carefully to ensure the two layers connected well. As shown in the followed screenshot, Characters moved from one layer to another layer and finally reached their goal positions.


Figure 22. Crowd simulation in a multi-layered environment.

In the future, we will add some functionality to automatically extract all walkable areas from a given 3D environment, avoiding the burden to model intricate multi-layered environments by hand:

Figure 23. A (multi-layered) view into the future of this engine. We are currently making a tool for automatically extracting the walkable surfaces of any 3D environment.

utrecht university crowd simulation unity3d plugin manual · the computations of the positions to...

Documents