Formats

The files G1 World writes for a game engine to read, field by field

This page is the agreement between G1 World and an engine. A file that keeps it can be read by any engine, for Griffintown or any other city. It is a draft: version 0.7 (0.2 added the measured heights of G1b; 0.3 heights in the frame and the terrain grid; 0.4 roofs from the 2016 3D buildings; 0.5 the greybox block in the frame and areas.geojson; 0.6 areas painted into the ground, ground_kinds.png, and no top_m; 0.7 flat_ground.geojson in place of ground_kinds.png). Each file states its version, and the version changes whenever a field is added, renamed or changes meaning.

Rules for every file

Rule In practice
one frame coordinates in metres from the origin in frame.json; x east, y north, z up
ids are kept every element has an id and a source naming the system row it came from
numbers are numbers in GeoJSON, a number is never written as text
missing is missing in GeoJSON, an unknown value is null; in CSV, an empty cell. Never 0, never a guess
status beside the value where a value can be measured or assumed, a _status field says which, and a _rule field says how
core fields and local fields an engine needs only the core fields. Local fields carry what one city’s sources give, and another city may leave them out

The G1 tests check these rules on every build (G1 World, T9).

frame.json

Field Type Meaning
format text situ-g1
format_version text 0.7
z_origin_m_above_sea, terrain number, text z in every file is metres above this height; the name of the terrain grid
made date when the files were written
crs text the map projection of the sources; Griffintown: EPSG:32188
origin two numbers the frame’s origin in that projection, in metres
axes, units text x east, y north, z up; metres
storey_height_m, storey_height_from, storey_height_by_use number, object the height per storey used where only storeys are known: for all uses, how many buildings it came from, and by use
greybox object drawing choices made for the first engine plugins, withdrawn on 2026-10-28 (G7): ground (flat or terrain, ledger W26) curb_height_m, the height of sidewalks and islands above flat ground (W27, an assumption), ground_grid_deg, the direction of the flat ground’s grid in degrees counter-clockwise from east (W28, the main street direction; a look only), and ground_pieces, the file of flat ground pieces by kind (W30)
height_source object how many heights come from each source
counts object how many of each element the files hold

blocks.geojson: buildings

One Polygon per building, in the frame.

Field Core Type Meaning
id, source yes text the building, and the row it came from
height_m yes number or null height in metres; null when no source gives one
height_status yes measured, assumption or unknown how the height was obtained
height_rule yes text the rule in words
height_source no text or null surface model 2015, OpenStreetMap or storeys; null when unknown
height_2015_m, present_2015 no number or null; yes, no or unclear what the 2015 surface measured on the outline, and whether a building stood there
roof_form, roof_faces, roof_source no text or null; number or null flat, mixed or pitched, how many roof faces, and their source; null where no roof is known
height_2016_m, cover_2016 no number or null the 2016 model’s roof top above the 2015 terrain, and the share of the outline its parts cover
ground_m no number or null the ground’s height above sea level under the building, from the 2015 terrain
year_built no text or null the tax roll’s year built, as given (a range when the roll gives several)
base_z, top_z yes number or null each building is a separate structure: its base (the lowest ground along its outline) and its top, in metres above the z origin
door_x, door_y yes number or null the door, in the frame
door_rule yes text how the door was placed (in Griffintown, an assumption)
footprint_m2, storeys no number or null from the sources
use, public_use, public_use_reason no text what the sources record of the building’s use
door_street, door_segment, door_m no text, number the street the door faces and its distance
dwellings no number or null homes in the building

ground.geojson: streets and junctions

LineStrings for street segments and Points for junctions, told apart by element.

Field Core Type Meaning
id, source, element yes text street segment or junction
from, to yes (segments) text the junction ids at each end
walk yes (segments) true or false open on foot
car_from_to, car_to_from yes (segments) true or false open to cars in each direction
length_m yes (segments) number length in metres
vertex_z, z yes list of numbers or nulls; number or null ground height at each vertex of a segment, or at a junction
street, class_name, zone no text name, the city’s road class, inside the area or on its edge
kind, segments_meeting no (junctions) text, number the kind of junction, and how many segments meet there

props.csv: objects in the street

Field Core Meaning
prop, source yes the prop, and the system rows behind it
class yes the game class: tree, lamp, seat, table, bike rack, hydrant, bin, camera, water, shelter, crossing mark, work zone
x, y, z yes position in the frame; z empty where the terrain is unknown
kind, segment, street no the source’s kind; the nearest street
detail, setting, size, size_unit no what the source says of it (a tree’s species and trunk size, for instance)
date, date_kind, status no dates and status from the source (a road work’s permit dates)
last_seen_in_photo, possibly_gone no for objects found in street photos

surfaces.geojson: sidewalks and islands

Field Core Type Meaning
id, source, kind yes text sidewalk or island
width_m no number or null width in metres
type, material, built, street, segment no text what the city’s file says

areas.geojson: what the flat ground is

Polygons where the ground is neither street, sidewalk nor building, from OpenStreetMap (ODbL). Ledger W29 to W31.

Field Core Type Meaning
id, source, kind yes text green, play, plaza, parking, bike or water
walkable yes true or false false for water
area_m2, osm no number, text the piece’s area; the OpenStreetMap element it comes from
width_m, width_from no number or null, text bicycle bands: the width and where it comes from (W31); null where bands of different widths merge

flat_ground.geojson: the flat ground by kind

The flat ground of the study area plus a margin, cut into pieces (W30). Each piece is one kind, not classified or an area kind; no two pieces overlap; each is one outer ring, exact to the millimetre; neighbouring pieces share their corners (no corner lies inside another piece’s edge). With building outlines and raised surfaces the pieces cover the extent. An engine draws every piece at z 0 with one shared grid.

Field Core Type Meaning
id, kind yes text G00001…; not classified, green, play, plaza, parking, bike or water
area_m2 no number the piece’s area

terrain_2015.png and terrain_2015.json

A 16-bit greyscale picture: one pixel per metre, rows running south. Each value is centimetres above the z origin; 65535 means no terrain is known there.

Field in the json Meaning
first_pixel_centre_frame the frame position of the centre of the top-left pixel
cell_m the pixel size in metres
z_origin_m_above_sea, units, nodata how to turn a value into a height
known_share the share of pixels with a known height

roofs_2016.geojson

One 3D Polygon per roof face, [x, y, z] in the frame (z above the z origin).

Field Core Meaning
building yes the G1 outline the face belongs to
part yes the 2016 building part, as tile and id

ledger.csv and checkpoints.csv

File Fields Meaning
ledger.csv id, kind, layer, decision, touches, alternative every decision, with its kind: source observation, researcher decision, assumption or gap
checkpoints.csv kind, id, x, y, question what a person should look at, and where

Planned files

Files for routes and recorded journeys will be added here, each with its version, once the stage that writes them is built (The game, stage by stage).