[008] How to Understand CGA Rule Structure in CityEngine (Beginner Guide)

Struggling to understand how CGA rules actually connect to the CityEngine interface? CGA rules define attributes, constants, and functions that directly control 3D geometry and automatically generate UI elements inside the CityEngine Inspector panel. In this tutorial, you will quickly learn the basic structure of CGA (Computer Generated Architecture) and how attributes, constants, and rules directly control both 3D geometry and the Inspector panel.

Below is a simple CGA code example to help you quickly understand the overall structure.

If you have studied any programming language, you will likely grasp the general structure, even if you don't know the exact meaning of every single line.

# Building color
@Color
attr BD_color = "#00ffff"

# Number of floors
@Range(min=1, max=5, stepsize=1)
attr BD_floor = 3

# Floor height
@Range(min=3, max=5, stepsize=0.1)
const floor_Height = 3

# Total height calculation
bd_height = BD_floor * floor_Height

# Apply height and color
Lot --> extrude(bd_height) color(BD_color)

# Alternative lot
Lot1 --> extrude(bd_height * 2) color(BD_color)

# Style preset
style Floor_5_Red_Building
attr BD_floor = 5
attr BD_color = "#ff0000"

If we map this CGA code to the CityEngine interface, you will see that the vast majority of the code directly corresponds to UI elements in the Inspector panel.

[img 1 : Visual diagram mapping CGA code lines to CityEngine Inspector UI elements]

💡 Practical Tip: When you define an attr, CityEngine automatically creates a UI control for it in the Inspector panel, bridging the gap between developers and designers.

Key Elements of CGA Rules

Here are the most frequently used elements you need to know:

Comments (# or /*...*/): Used for explanations. Always document your logic, as humans are forgetful creatures.
import: Used to reference other .cga files, allowing you to separate functions cleanly.
attr (Attribute): Editable variables. These values are exposed and can be controlled in the Inspector panel.
const (Constant): Fixed values that are not exposed to the UI.
@ (Annotations): Modifiers for attributes that add UI behaviors like sliders, color pickers, or file explorers.
Functions: Declared with an = sign without attr. These handle internal calculations (like bd_height above) and do not appear in the UI.
--> (Rule): The core mechanism that generates actual 3D geometry in the viewport.
style: Preset combinations of attributes. It acts as a template so you can apply multiple settings at once.

How CGA Works (Simple Flow)

The overall workflow of CGA coding is actually quite straightforward:

Create variables → Process them via functions → Apply them to rules.

CGA is not overly complex once you understand this flow. Instead of memorizing syntax, focus on frequently reviewing example source codes to see how data flows from attributes to final geometry.

The Real Challenge: Scope

The hardest part of CGA in CityEngine is understanding Scope.

Scope defines how objects are oriented and transformed in 3D space. It is notoriously difficult because you often need to check the Model Hierarchy panel to fully understand what is happening.

Understanding scope is what truly separates beginners from advanced users. You might even develop a habit of muttering, "Please, let me just code without touching the scope..."

Next Steps

In practical work where everything must be drawn exactly according to CAD blueprints, automated roads might not be strictly necessary, but they are a core feature of CityEngine.

Next, we will explore how to generate basic roads.

In Lecture [009], we will cover Street Creation.

To evaluate visual impacts and identify CCTV blind spots using 3D spatial data, see [007] Viewshed Analysis (Viewshed Creation)

To learn how to automatically generate street networks, see [009] How to Generate Basic Streets in CityEngine

To understand the fundamental node-based tree structure of rules, see [006] Understanding the Basic Concepts of Procedural Modeling in CityEngine
If you want to understand why CGA coding feels difficult at first, see [017] Why Understanding Workflow Matters Before Learning CGA in CityEngine
If you want to start learning procedural modeling from the basics, see [023] Let's start Learning CGA in CityEngine

If you have any questions, please leave a comment. Let's solve them together!

[A Quiet Thought]

"Programs must be written for people to read, and only incidentally for machines to execute."
— Harold Abelson, Structure and Interpretation of Computer Programs

Continue Learning

Explore complete tutorial collections for CityEngine and Global Mapper.

🏙 CityEngine Tutorial 🗺 Global Mapper Tutorial

CUBIZEN: Global Mapper, CityEngine & Creative Tech