James Routley

ElCity is a small, turn-based city builder that runs entirely inside Emacs. The UI is ASCII-based and optimized for terminal Emacs sessions. The core simulation is deterministic and pure, while the UI handles rendering and input.

This is an excercise in implementing the “functional core / imperative shell” architecture in a moderately sized project that with a developed UI. Every tile type is defined through a DSL, with a strong separation between state and effects. Most functions in the core are either pure or pure-ish.

Benefits to this approach:

easy to debug
scalable in terms of code: reduced cognitive load on both people and LLMs
easy UX/UI as state is always localized
easy to extend (with some discipline)
easy to autotest

Emacs 30.1+
Optional: Eask for dependency management

Clone the repository and add it to your Emacs load path. Example with use-package:

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

If you are not using use-package, add the directory to load-path and require the entry point:

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

From the project root:

Or from Emacs: M-x elcity-start

The game is turn-based. Press n to advance one turn.
Funds increase each turn by: (Population / 2) + (Commercial level + Industrial level).
City Hall is the source of road connectivity and is unique and non-demolishable.
Roads are only connected if they trace through other roads to City Hall.
Power plants provide a Manhattan-radius of 6 tiles.
Zones grow by 1 level per turn if powered and road-adjacent.
Zones decay by 1 level per turn if they lose power or road adjacency.
Maximum zone level is 3.
Residential (R) supplies Workers in a radius and dislikes Pollution.
Industrial (I) supplies Goods and Pollution and requires Workers.
Commercial (C) requires Workers and Goods.

R select Residential and place once
C select Commercial and place once
I select Industrial and place once
r select Road and place once
p select Power plant and place once
h select City Hall and place once
SPC or RET place selected tool at cursor
d demolish at cursor
u undo last action
n advance one turn
Arrow keys move the cursor
o cycle overlays (goods, polution, connectivity, etc)

This is a simplified snapshot to show the general layout.

Funds: 1000 | Pop: 0 | Income: 0 | Turn: 0 | Overlay: none | Tool: none | Unpowered: 0 | Disconnected: 0 | Polluted: 0
Cursor: (0,0) | Tile: HH City Hall | Level: 0 | Build: N | Demo: N | Unique: Y | Cost: 150 | Pop: 0 | Inc: 0
Legend: R res  C com  I ind  == road  Overlay: Pwr Conn Poll Work Goods
Keys: R/C/I zone (select tool) | r road | p power | h city hall | d demolish | n next turn
Place: SPC/RET place selected tool | u undo
Overlay: o cycle (none/power/connectivity/pollution/workers/goods)
Move: arrows
   00 01 02 03 04 05 06 07 08 09
   +--------------------+
00 |HH==R0..PP..........|
01 |....................|
02 |~~~~~~..............|
   +--------------------+

Start with a custom map by calling elcity-start with a list of row strings.
Example call: (elcity-start '("H=R0" "...."))
Map tokens are defined in tile definitions.
Canonical tokens include .., ~~, ==, PP, HH, R0-=R3=, C0-=C3=, I0-=I3=.
Short aliases are also accepted: ., ~, =, P, H, R, C, I.
Default map rows live in elcity-maps.el (elcity-map-default-rows).
Default map size is set by elcity-core-map-width and elcity-core-map-height.

make test runs ERT tests.
make lint runs package lint, checkdoc, and byte compilation.
make compile byte-compiles non-test files.

elcity.el entry point that wires core and UI
elcity-core.el pure simulation and state transitions
elcity-tiles.el tile definitions and effect metadata
elcity-ui.el UI shell and input handling
elcity-maps.el map presets
test/ ERT tests

Show HN: Micropolis/SimCity Clone in Emacs Lisp