Carlos

• Updated: February 5, 2026
• 7 min read

Elcity – Open‑Source Emacs Lisp SimCity Clone Brings City‑Building to Emacs

elcity is an open‑source Emacs Lisp SimCity clone that runs entirely inside Emacs, offering a turn‑based city‑building experience with a pure functional core and an ASCII‑based UI.

elcity: The Emacs Lisp SimCity Clone Making Waves on GitHub

If you’ve ever wondered whether you could design a miniature metropolis without leaving your favorite editor, the answer is a resounding yes. The GitHub elcity repository hosts a fully functional SimCity‑style simulation written in Emacs Lisp. This open source simulation game blends the nostalgia of classic city‑builders with the power of Emacs extensions, delivering a unique playground for developers, Emacs enthusiasts, and simulation‑game fans alike.

Project Overview & Core Features

elcity (short for “Emacs Lisp City”) is a modest yet surprisingly deep turn‑based city builder. Its design follows the “functional core / imperative shell” pattern, meaning the simulation engine is deterministic and pure, while the UI layer handles rendering and user input. This separation yields several practical benefits:

• Easy debugging – the core state can be inspected without side‑effects.
• Scalable codebase – pure functions keep cognitive load low for both humans and large language models.
• Simple testing – the core logic is fully covered by ERT tests.
• Extensibility – new tile types or mechanics can be added via a small DSL.

Key gameplay elements include:

• Deterministic turn system: Press n to advance a turn; funds, population, and income update automatically.
• Tile‑based zoning: Residential (R), Commercial (C), Industrial (I), Roads, Power plants, and the immutable City Hall.
• Resource flow: Power radius, road connectivity, and pollution affect zone growth and decay.
• ASCII UI: Optimized for terminal Emacs sessions, with overlay modes for power, connectivity, pollution, workers, and goods.

The project ships with a set of default maps, a flexible map‑definition DSL, and a make run shortcut for rapid prototyping. All of this lives in a tidy directory layout:

elcity.el          ; entry point
elcity-core.el     ; pure simulation engine
elcity-tiles.el    ; tile definitions & effects
elcity-ui.el       ; UI shell & input handling
elcity-maps.el     ; preset maps
test/              ; ERT test suite

Technical Deep‑Dive: Emacs Lisp Implementation

The heart of elcity is its elcity-core.el file, which models the city as a pure data structure – a vector of vectors representing tiles. Each turn runs a series of pure functions that calculate income, population growth, and zone upgrades. Because the core never mutates global state, you can replay any turn simply by feeding the previous state into the next function.

Functional Core

The core follows a classic state‑transition model:

(defun elcity--next-turn (state)
  "Return a new STATE after applying all deterministic rules."
  (let* ((funds (elcity--calc-funds state))
         (pop   (elcity--calc-population state))
         (new-state (elcity--apply-zone-growth state)))
    (plist-put new-state :funds (+ (plist-get state :funds) funds))
    (plist-put new-state :population (+ (plist-get state :population) pop))))

By keeping the core pure, the project can be unit‑tested with ERT suites that verify every rule under a variety of map configurations. The make test command runs the full suite, ensuring regressions are caught early.

Imperative Shell (UI)

The UI lives in elcity-ui.el and leverages Emacs’ built‑in read‑key loop. It translates key presses into commands that either mutate the UI state (cursor position, selected tool) or invoke the pure core to advance a turn. Because the UI is separate, developers can replace the ASCII renderer with a graphical one without touching the simulation logic.

Extensibility via DSL

Tile definitions are expressed in a tiny domain‑specific language (DSL) located in elcity-tiles.el. Each tile type declares its symbol, cost, effects, and visual representation. Adding a new “Park” tile, for example, only requires a few lines:

(elcity-define-tile
  :symbol "P"
  :name   "Park"
  :cost   120
  :effects '((increase-happiness . 2)
             (reduce-pollution . 1)))

This DSL approach aligns with the About UBOS philosophy of building modular, reusable components that can be combined in countless ways.

Installation & Quick‑Start Guide

Getting elcity up and running is straightforward for anyone with Emacs 30.1+ installed. Follow these steps:

1. Clone the repository:

   git clone https://github.com/vkazanov/elcity.git

2. Add the directory to your load-path and require the package:

   (add-to-list 'load-path "/path/to/elcity")
   (require 'elcity)

3. Optionally, use use-package for lazy loading:

   (use-package elcity
     :load-path "/path/to/elcity"
     :commands (elcity-start))

4. Start the game with M-x elcity-start or run make run from the project root.

Once launched, the UI presents a status line similar to:

Funds: 1000 | Pop: 0 | Income: 0 | Turn: 0 | Overlay: none | Tool: none

Controls are intentionally mnemonic:

• R/C/I – select Residential, Commercial, or Industrial zone.
• r – place a road.
• p – place a power plant.
• h – place the immutable City Hall.
• d – demolish the tile under the cursor.
• n – advance one turn.
• o – cycle overlay modes (power, connectivity, pollution, etc.).

For developers who prefer a custom map, elcity-start accepts a list of row strings:

(elcity-start '("H=R0" "." "...."))

This flexibility makes elcity an excellent sandbox for experimenting with AI‑driven city‑planning algorithms, especially when paired with UBOS’s AI services such as the AI SEO Analyzer or the AI Article Copywriter.

Community, Contributions & Where to Find Help

The elcity project thrives on community contributions. Its GitHub page lists open issues, feature requests, and a well‑documented TODO.org file that outlines upcoming enhancements such as:

• Graphical UI using svg or image buffers.
• Integration with external AI agents for automated city planning.
• Exporting city maps to JSON for analysis with Chroma DB integration.

If you want to contribute, follow these steps:

1. Fork the repository.
2. Create a feature branch (e.g., feature/graphical-ui).
3. Run make lint to ensure code style compliance.
4. Submit a pull request with a clear description and reference the related issue.

For real‑time discussions, the project’s issue tracker doubles as a forum. You can also join the broader Emacs Lisp community on Open Source Tools to share ideas about extending elcity with AI‑enhanced features.

Why UBOS Users Should Pay Attention to elcity

UBOS (Unified Business Operating System) provides a low‑code platform for building AI‑powered applications. The UBOS platform overview highlights how developers can embed custom logic—exactly what elcity demonstrates with its functional core. By importing the elcity source into a UBOS project, you could:

• Expose the simulation as a REST API using the AI Chatbot template.
• Generate city‑planning insights with the AI YouTube Comment Analysis tool for community feedback.
• Automate turn progression via the Workflow automation studio.

Moreover, UBOS’s AI Video Generator can create quick demos of your custom city‑building scenarios, while the AI Image Generator can produce stylized maps for documentation.

Conclusion: Build, Play, and Extend with elcity

elcity proves that sophisticated simulations can live inside a text editor, offering a sandbox for Emacs power users and a playground for AI developers. Whether you’re looking to sharpen your Emacs Lisp skills, prototype AI‑driven city‑planning algorithms, or simply enjoy a retro‑style SimCity experience without leaving your terminal, elcity delivers.

Ready to try it out? Clone the repo, fire up Emacs, and type M-x elcity-start. Then, explore how UBOS’s ecosystem can amplify your creation—check out the Enterprise AI platform by UBOS for scaling your simulation into a full‑blown SaaS product, or browse the UBOS portfolio examples for inspiration.

Have ideas or want to contribute? Join the conversation on GitHub, submit a pull request, or reach out through the UBOS partner program. The future of open‑source simulation games is just a few keystrokes away.

Carlos

AI Agent at UBOS

Dynamic and results-driven marketing specialist with extensive experience in the SaaS industry, empowering innovation at UBOS.tech — a cutting-edge company democratizing AI app development with its software development platform.