Home /Modules/bash/city_model.hpp

city_model.hpp

bash/model-3D/city_model.hpp · 331 line(s) · c

#pragma once

// SleelaTerminal(TM) -- SLeeLa's terminal product, built on GNU Bash
// (GPL, (C) Free Software Foundation). SLeeLa-authored addition; the
// vendored GNU Bash sources keep their own GPL headers and copyright.
// Phraign(TM) City 3D -- sprawling city model for the Phraign frame renderer.
//
// A city is a square grid of blocks (default 64x64 = 4096, "~4000 square
// blocks"). Each block carries a building with an integer height. The model is
// generated per-user from a seed so a given user reproduces the same city, and
// it can be serialized to a portable text format that lives well on GitHub or a
// public server.
//
// This header defines the data model, the render/config options, and the
// public API. Rendering targets the Phraign native pixel frame
// (sleela::terminal::PixelTerminal), so the city is drawn on a per-pixel basis.
//
// See README.md and CONFIG.md for the system overview and config format.

#include <cstddef>
#include <cstdint>
#include <string>
#include <vector>

namespace sleela::city {

// ---------------------------------------------------------------------------
// Color
// ---------------------------------------------------------------------------

// A Phraign pixel value is a 32-bit RGBA word, packed 0xRRGGBBAA. Alpha 0xFF is
// fully opaque. This is the encoding City 3D writes into Phraign Pixel::value.
struct Color {
    std::uint8_t r = 0;
    std::uint8_t g = 0;
    std::uint8_t b = 0;
    std::uint8_t a = 0xFF;

    constexpr std::uint32_t rgba() const noexcept {
        return (static_cast<std::uint32_t>(r) << 24) |
               (static_cast<std::uint32_t>(g) << 16) |
               (static_cast<std::uint32_t>(b) << 8) |
               static_cast<std::uint32_t>(a);
    }
};

// The user-selectable color theme. Green is the default.
enum class Theme {
    Green,
    White,
    Blue
};

const char* themeName(Theme theme) noexcept;
bool parseTheme(const std::string& text, Theme& out) noexcept;

// A resolved palette derived from a Theme. The renderer shades building faces
// by tinting the base tone lighter (top / lit side) or darker (shaded side).
struct Palette {
    Color background;  // empty sky/ground behind the city
    Color ground;      // the ground plane / streets
    Color roof;        // building top face
    Color wall_lit;    // building side facing the light (brighter)
    Color wall_shade;  // building side away from the light (darker)

    static Palette forTheme(Theme theme) noexcept;
};

// ---------------------------------------------------------------------------
// Viewpoint / render configuration
// ---------------------------------------------------------------------------

// The camera is an oblique/dimetric projection: the city is seen from the top
// and off to one side at a slight angle. The viewpoint is fully described by a
// handful of scalars so it can be driven from a config file.
struct Viewpoint {
    // Oblique projection factors. Each unit of world Y (north/depth) shifts the
    // screen position by (tilt_x, tilt_y) pixels; this produces the "seen from
    // slightly to the side and above" look. Defaults give a gentle angle.
    double tilt_x = 0.55;  // horizontal skew per world-Y unit
    double tilt_y = 0.42;  // vertical foreshortening per world-Y unit (0<..<=1)

    // Pixels per world unit along X (east/west) and per unit of building height.
    double scale_x = 9.0;
    double scale_height = 1.1;

    // Pixels between block centers on the ground grid.
    double block_pitch = 9.0;

    // Screen origin (pixels) where world (0,0) ground point lands.
    double origin_x = 150.0;
    double origin_y = 380.0;
};

// Everything needed to render, resolved from a Config.
struct RenderOptions {
    Theme theme = Theme::Green;
    Viewpoint viewpoint{};
    std::size_t frame_width = 1024;
    std::size_t frame_height = 768;
    bool draw_bridges = true;
    bool draw_windows = true;
    bool draw_cylinders = true;  // render the cityscape-graph cylinder pairs
};

// ---------------------------------------------------------------------------
// Native legislature (the civic regime that shapes the city's lines)
// ---------------------------------------------------------------------------

// A person's *native legislature* is the defining characteristic of their
// nature and, in turn, their design. In City 3D it selects a civic regime whose
// rules produce the city's lines and linear outcomes: how regular the grid is,
// how strongly corridors run in straight lines, and how they are oriented and
// connected. It is a named, enumerated regime (not a numeric knob).
enum class Legislature {
    Federal,        // strong straight grid, balanced two-axis layout
    Parliamentary,  // orderly grid with a dominant primary axis
    Municipal,      // dense, regular local blocks (very grid-like)
    Bicameral,      // two strong axes -> pronounced crossing lines
    Unicameral,     // one dominant axis -> strongly linear, banded city
    Direct          // looser, more organic lines (least regimented)
};

const char* legislatureName(Legislature l) noexcept;
bool parseLegislature(const std::string& text, Legislature& out) noexcept;

// The linear "shape" a legislature imposes, resolved from the enum. These are
// the lines/linear outcomes the regime produces.
struct LegislatureProfile {
    double regularity = 0.7;      // 0 organic .. 1 perfectly regular grid
    double linearity = 0.6;       // how strongly corridors run in straight lines
    double axis_bias = 0.5;       // 0 favor one axis .. 0.5 balanced .. 1 other
    double connectivity = 0.6;    // how well corridors interconnect (bridges/roads)
    std::int32_t road_spacing_delta = 0;  // adjust road_spacing (tighter/looser)
    std::int32_t bridge_count_delta = 0;  // adjust bridge_count

    static LegislatureProfile forLegislature(Legislature l) noexcept;
};

// ---------------------------------------------------------------------------
// Year / IQ / legislature / quality / finality parameters
// ---------------------------------------------------------------------------

// Generation parameters that describe the *kind* of city to build. Three
// drivers shape the design: the Year (modernity), the person's IQ (design
// quality / order), and the person's native Legislature (the regime that
// produces the city's lines and linear outcomes). Buildings are generated
// around city-wide targets, then each building's finality (quality of
// condition) is computed from its attributes and these drivers, with weights.
struct CityParams {
    // The city's Year. A larger, more modern year makes the city newer: taller
    // buildings, more floors and windows, more glass, and better condition.
    // Concretely, modernity = clamp((year - year_baseline) / year_span, 0..1).
    std::uint32_t year = 2807;
    std::uint32_t year_baseline = 2000;  // year mapped to modernity 0
    double year_span = 1000.0;           // years above baseline for modernity 1

    // The person's IQ. This is *both* a person-level input and, in the project's
    // terms, a system design-quality metric (IQ = insight/quality, not a human
    // psychometric rating). A higher IQ yields a better-planned city: more order
    // and regularity, better connectivity, and higher baseline condition.
    // designQuality = clamp((iq - iq_baseline) / iq_span, 0..1).
    std::uint32_t iq = 130;
    std::uint32_t iq_baseline = 100;   // iq mapped to design quality 0
    double iq_span = 100.0;            // iq points above baseline for quality 1

    // The person's native legislature: the regime that shapes the city's lines.
    Legislature legislature = Legislature::Federal;

    // Building form targets (a building varies around these).
    double avg_floors = 14.0;         // target mean number of floors
    double floor_height = 3.0;        // world units per floor (height = floors*this)
    double windows_per_floor = 6.0;   // target windows on a visible face per floor

    // Street / bridge layout (real features).
    std::uint32_t road_spacing = 8;   // every Nth row/col is a road corridor
    std::uint32_t bridge_count = 6;   // number of bridges spanning the city

    // Finality weights: how much each factor contributes to a building's
    // quality-of-condition score (finality, 0..1). They are normalized, so only
    // their relative sizes matter.
    double w_year = 1.0;              // newer year -> higher finality
    double w_iq = 0.7;               // higher IQ (design quality) -> higher finality
    double w_floors = 0.6;           // more floors -> more "finished"/dense
    double w_windows = 0.6;          // more windows -> more modern/glassy
    double w_road_proximity = 0.8;   // closer to a road -> better serviced
    double w_bridge_proximity = 0.5; // closer to a bridge -> better connected

    // Distance (in blocks) at which road/bridge proximity benefit fades to 0.
    double proximity_falloff = 6.0;

    // General cityscape-graph dimensions (see CityscapeModel). Kept here so a
    // serialized city carries them and the graph is reproducible on reload.
    std::uint32_t radix = 3;      // branching base of the distribution graph
    double diameter = 24.0;       // radial reach from the center of centricity
    double randomness = 0.35;     // 0..1 seeded variability

    // Modernity in [0,1] derived from the Year.
    double modernity() const noexcept;
    // Design quality in [0,1] derived from the IQ.
    double designQuality() const noexcept;
    // The linear regime profile derived from the legislature.
    LegislatureProfile profile() const noexcept;
};

// ---------------------------------------------------------------------------
// Config file
// ---------------------------------------------------------------------------

// Parsed representation of a City 3D config file (simple key = value text).
// Unknown keys are ignored; missing keys keep their defaults.
struct Config {
    // Model
    std::uint32_t grid_cols = 64;   // 64 x 64 = 4096 blocks (~4000)
    std::uint32_t grid_rows = 64;
    std::uint64_t seed = 0;         // 0 => derive from user name
    std::string user;               // per-user identity

    // Year, quality targets, proximity/finality weights.
    CityParams params{};

    // General cityscape-graph dimensions live on `params` (radix/diameter/
    // randomness) so they serialize with the city. Convenience accessors:
    std::uint32_t radix() const noexcept { return params.radix; }
    double diameter() const noexcept { return params.diameter; }
    double randomness() const noexcept { return params.randomness; }
    bool draw_cylinders = true;   // render the mating cylinder pairs + links

    // Appearance / view
    Theme theme = Theme::Green;
    Viewpoint viewpoint{};
    std::size_t frame_width = 1024;
    std::size_t frame_height = 768;
    bool draw_bridges = true;
    bool draw_windows = true;

    // Persistence: where a saved model is meant to live.
    //   save_target: "github" | "server" | "local"
    std::string save_target = "local";
    std::string save_location;      // repo slug, URL, or path

    RenderOptions renderOptions() const noexcept;

    // Parse from text (config file contents). Returns true; malformed numeric
    // values keep the previous/default value. `error` receives a note when a
    // value could not be parsed (parsing still succeeds best-effort).
    static Config fromText(const std::string& text, std::string* error = nullptr);
};

// ---------------------------------------------------------------------------
// City model
// ---------------------------------------------------------------------------

// What occupies a grid cell.
enum class Cell : std::uint8_t {
    Building = 0,  // a lot with a building (height may still be 0 for empty)
    Road = 1,      // a street/road corridor
    Bridge = 2     // a bridge span (an elevated road feature)
};

// One grid cell: a building with quality attributes, or a road/bridge feature.
// The finality field is the building's quality-of-condition score in [0,1].
struct Block {
    Cell cell = Cell::Building;
    std::uint16_t height = 0;   // building height in world units (0 = empty lot)
    std::uint16_t floors = 0;   // number of floors
    std::uint16_t windows = 0;  // windows on a visible face (detailing cue)

    // Computed proximities, in blocks, to the nearest road / bridge.
    float road_distance = 0.0f;
    float bridge_distance = 0.0f;

    // Quality of condition ("finality") in [0,1]: how finished, modern, and
    // well-conditioned this building is. Higher = newer/better.
    float finality = 0.0f;

    bool isBuilding() const noexcept { return cell == Cell::Building; }
};

class City {
public:
    City() = default;
    City(std::uint32_t cols, std::uint32_t rows);

    std::uint32_t cols() const noexcept { return cols_; }
    std::uint32_t rows() const noexcept { return rows_; }
    std::size_t blockCount() const noexcept {
        return static_cast<std::size_t>(cols_) * rows_;
    }

    const Block& at(std::uint32_t x, std::uint32_t y) const;
    Block& at(std::uint32_t x, std::uint32_t y);

    // The generation parameters that produced (or should produce) this city.
    const CityParams& params() const noexcept { return params_; }

    // City-wide finality: the mean quality-of-condition over all buildings, in
    // [0,1]. Represents the city's overall "model of finality".
    double cityFinality() const noexcept;

    // Procedurally build the city from a seed and parameters. Lays roads and
    // bridges (real features), computes each building's proximity to the
    // nearest road and bridge, derives floors/windows/height from the Year, and
    // computes per-building finality. Same seed + params => same city.
    void generate(std::uint64_t seed, const CityParams& params);
    // Back-compat convenience: generate with default parameters.
    void generate(std::uint64_t seed) { generate(seed, CityParams{}); }

    // Serialize / deserialize a portable text form (see MODEL_FORMAT in .cpp).
    // Serialization writes format v2 (with attributes); deserialization reads
    // both v2 and the older v1 (height-only) format.
    std::string serialize(const std::string& user, std::uint64_t seed) const;
    static bool deserialize(const std::string& text, City& out,
                            std::string* user = nullptr,
                            std::uint64_t* seed = nullptr);

private:
    void computeProximities();
    void computeFinality();

    std::uint32_t cols_ = 0;
    std::uint32_t rows_ = 0;
    std::vector<Block> blocks_;
    CityParams params_{};
};

// Derive a stable 64-bit seed from a user name (used when config seed == 0).
std::uint64_t seedForUser(const std::string& user) noexcept;

} // namespace sleela::city