Tutorial 1: Essential skills

To access the tutorials in CityEngine, click Help > Download Tutorials and Examples.... After choosing a tutorial or example, the project is automatically downloaded and added to your workspace.

Set up a new project

Create a new project and scene

First, you'll create a new CityEngine project.

  1. Click File > New > CityEngine > CityEngine project.

    The Select a wizard dialog box appears.

    Select a wizard dialog box

  2. Click Next, name your project MyFirstCity, and click Finish.

    A new project is created and appears in the Navigator (by default, located in the upper left corner of the CityEngine window). The default folders that store your project data, such as assets, rules, and scenes, are already present, though empty.

    Next, you'll create a new scene.

  3. Click File > New > CityEngine > CityEngine scene.

    The CityEngine Scene dialog box appears. Name your scene myFirstCity_01.cej.

    CityEngine Scene dialog box

Copy rules and assets

Later in this tutorial, you'll need rule files and assets for the generation of the building models. You copy these files from the main Tutorial 1: Essential Skills project, which you should already have linked to your workspace.

Now you'll copy all necessary files from the downloaded Tutorial 1 project into your new project.

  1. Use copy paste (Windows and Linux: Ctrl-C and Ctrl-V/Mac OS: Command-C and Command -V) on your keyboard or from the right mouse button context menu.
    Navigator display of contents within the assets and rules folders copied to the MyFirstCity project folder
  2. Copy the contents of both the assets and rules folders.

    Your Navigator should look like the following screen shot:

    MyFirstCity folder contents displayed in the Navigator

First street layout

Random street grow

After the new project has been set up, you’re ready to start creating the first street layout in your newly created scene.

First, you'll create a street network.

  1. Click the viewport to make it the active window.
  2. Click Graph > Grow Streets.

    The Grow Streets dialog box appears.

    Grow Streets Basic Settings dialog box

  3. Keep the default settings for now.
  4. Click Apply, and close the dialog box.

    Approximately 500 streets were created, but you can't see them all in the viewport until you frame the view.

  5. Press the A key to frame all objects in the viewport. Your viewport should look similar to the following screen shot:
    Viewport Perspective View display of grown streets
  6. Your Scene Editor under the Navigator in your layout will now contain a new Streetnetwork layer, containing a network of blocks, graph segments, and shapes. It should look similar to the following screen shot:
    Scene Editor with the new Streetnetwork layer expanded to show objects

Navigation and selection


Navigating in the viewport is one of the most essential skills a CityEngine user has to learn. This section looks at the different navigation schemes available.

  1. Click Edit > Preferences > General > Navigation Devices > Mouse.
  2. The Current Mouse Scheme drop-down menu lists the available schemes of other 3D apps.
    Preferences for Mouse dialog box

For those who have a 3D Connexion 3D Mouse (https://www.3dconnexion.com/), there are specific preferences for that.

Preferences for 3D Mouse dialog box

You'll focus on the default navigation scheme. The options are shown in the following table:

Navigation commandWindows and Linux keyboard shortcutMac OS keyboard shortcut

Tumble the view

Alt+left mouse button

Option+ lmb

Pan the view

Alt+middle mouse button



Alt+right mouse button (or use the mouse wheel)


  • For efficient navigation of the constant use of the frame key F, use the frame button in the viewport’s toolbar.
  • Use the tumble/pan/zoom based navigation as early as possible. After a few minutes, it will become natural to you.


To interact and edit the objects in your scene, you need to select them. Start the Selection Tool using the mouse button or press Q. Select the objects by clicking in the viewport.


The F9F12 keys toggle the visibility of the four main object types: Map Layers, Graph Segments, Shapes, and Models. Deactivating the visibility of other object types usually simplifies making proper selection.

Selection types

The selection types are described in the following table:

Selection typeResult

Single click

Selects a single object

Right-to-left rectangular selection

Selects all objects inside or touching the selection rectangle

Left-to-right rectangular selection

Selects all objects completely within the selection rectangle

The left-to-right rectangular selection is usually used to select tiny objects such as single Street Graph Nodes when there are many objects occupying the same space.

Modifier keys

While the Selection Tool is active, press Ctrl and Shift to either add or subtract from your selection. The modes are also listed in the Selection Tool submenu in the toolbar.

Selection context menu

Once you have a selection, the right mouse button context menu contains entries with which you can select additional elements.

Selection context menu

The selection items are described in the following table:

Selection modeSelection element(s)

Select Objects of Same Type

Types: shapes, graph nodes

Select Objects of Same Group:

In the same block/street

Select Objects with Same Rule File

Same rule file assigned (on all visible layers)

Select Objects with Same Start Rule:

Same start rule (on all visible layers)

Model generation with rules

3D model generation

CityEngine is a procedural modeling application. This means that CityEngine uses rules to generate the 3D model.

Model Generation diagram

Assign rules

In this tutorial, the rules are already provided. You'll use them now.

  1. Select one block, and change its subdivision parameters in the Inspector from Recursive Subdivision to Offset Subdivision as shown below:
    Inspector Block Parameters dialog box

    For more information on block subdivision and dynamic city layouts, see Tutorial 2: Terrain and dynamic city layouts.

  2. Select one shape within the block, and use the context menu to Select Objects of Same Group.
  3. Drag and drop the building.cga rule file onto the selected shapes (highlighted orange).
    Navigator displays

    After dropping the rule onto the shapes, the model generation is automatically started. Your first buildings appear. Make sure the visibility of models is activated by toggling with F12.

    Viewport perspective view of buildings generated after the rule on the shapes has been applied

    Generated models can also be deleted in the right mouse button context menu.

    Delete Models command in the context menu
  4. Select the footprint shape again, and click Ctrl+G (Mac OS: Command+G) or use the Generate button Generate on the toolbar to generate the model on the selected shape.

    New variations of the buildings can be created by changing the seed value.

  5. Use the Update Seed button Update seed on the toolbar or click Ctrl+Shift+G (Mac OS: Command+Shift+G).

    The following image shows an example of different seed values for height:

    Example of different seed values for height

  6. Manually edit the rule’s building height parameter in the Inspector:
    Inspector rules height parameter is set to 42

    Once you manually change attributes in the Inspector it will become bold and override the definitions of the rule.

  7. Reset the attributes to the building.cga rule definitions by right-clicking the arrow next to the attribute in the Inspector and choosing Reset user attributes.
    Reset user attributes

Rule editing

Explore a rule file

CityEngine’s rule system uses CGA code, a dedicated scripting language unique to CityEngine. Because CGA is a scripting language, it offers you a generic and flexible tool to create 3D models for all types of cities. From modern to contemporary, from ancient to futuristic, anything’s possible.

Explore the provided rule you've been using so far.

  1. Open the building.cga rule in the Rule Editor by either double-clicking the CGA rule file in the Navigator or using the Rule File link in the Inspector.
    Inspector shapes rule file building.cga
  2. Start editing the building.cga rule in the Rule Editor.

    Building.cga rule in the Rule Editor

Edit the rule file

  1. Inspect building.cga rule. the Height is defined as a random value between 15 and 25.
    attr height = rand(15,25)
    Building with random height value of 22.82

    The building has a random height value of 22.82.

  2. Change the random height values in the Rule Editor.
    attr height = rand(15,80)

    The height is now defined as a random value between 15 and 80.

  3. Save the rule.
  4. Regenerate the building by clicking Update Seed or pressing Cntrl + Shift + G on your keyboard.
    Building with random height value of 51.27

    The building now has a random height value of 51.27.


    The reason you use Update Seed is because the height is a random value and you need to update the random seed value when regenerating the building.

  5. Add roof geometry by adding a new Rule named Roof to the building.cga rule. To do this, do the following:
    1. Edit the Lot rule so it looks like this:
      Lot -->
       	case shapeType == "LotInner" : 
       	else :
       	  extrude(height) comp(f) { side :  Facade | top:  Roof }
    2. Add the Roof rule and define the shape as roofHip with an angle of 22.5 degrees..
      Roof --> roofHip(22.5) Shape
    3. Save the rule.
  6. Regenerate the building, but this time, click the Generate Models button Generate or press Cntrl + G on your keyboard. By doing this, you will keep the building height at 51.27 and see the new roof geometry.
    Building with random height value of 51.27 with roofHip roof