# Assistant conversation BKZ48W

- Canonical URL: <https://m.sheaf.less.rest/BKZ48W>
- Resource IRI: <https://m.sheaf.less.rest/BKZ48W>
- Type: assistant conversation
- Mode: chat

## Transcript

### 1. User

So I think I added a way for you to look at the code repository for the software project, so can you look around and see how it seems?

### 2. Assistant tool calls

#### Tool call: `list_documents`

```json
{}
```

### 3. Tool result: list_documents

FOLDERS
- Accounting Algebra & Property Theory
- Living Structure, Wholeness & Beauty
- Living Structure, Wholeness &amp; Beauty
- ontology
- Procedural Generation & Co-Creation
- Roads, Trails & Movement
- Scenario-Based & Behavioral Programming
- Technology, Scale & Conviviality
- Terrain, Hydrology & Erosion
- Water Simulation & Rendering

Accounting Algebra & Property Theory (4)
- #GANFP9 A Fundamental Duality in the Mathematical and Natural Sciences: From Logic to Biology - 2024 | David Ellerman | 53 pp.
  Micro abstract: Traces an overlooked subset–partition duality—from logic and category theory through entropy and quantum indefiniteness to selectionist and generative mechanisms in biology.
- #NBH3BE Algebraic Models for Accounting Systems - 2010 | Derek J. S. Robinson, José García Pérez, Robert A. Nehmer, Salvador Cruz Rambaud | World Scientific | 255 pp.
  Micro abstract: Develops accounting theory algebraically: balance vectors as modules, transactions as a group, and whole accounting systems as automata with quotients, homomorphisms, and decision algorithms for audit and control.
- #7ESDBJ Economics, Accounting, and Property Theory - 1982 | David P. Ellerman | Lexington Books | 110 pp.
  Micro abstract: Ellerman's vector-accounting monograph: double entry generalized to property vectors ("accounting without valuation"), grounding a property-theoretic account of appropriation, the firm, and goodwill.
- #C8FHDZ On implication and negation in partition logic - 2025 |  , David Ellerman | Open Journal of Mathematical Sciences | 9 pp. | doi:10.30538/oms2025.0250
  Micro abstract: Develops implication as a refinement-sensitive operation on set partitions, showing how relative negation yields local Boolean cores within the non-distributive algebra of partitions.

Living Structure, Wholeness & Beauty (9)
- #MH5J8D Beautimeter: Harnessing GPT for Assessing Architectural and Urban Beauty Based on the 15 Properties of Living Structure - 2025 | Bin Jiang | AI | 12 pp. | doi:10.3390/ai6040074
  Micro abstract: Presents Beautimeter, a GPT-based tool that scores buildings and urban scenes against Christopher Alexander’s 15 properties of living structure to assess their coherence and beauty.
- #XW22YY Generative Codes: The Path to Building Welcoming, Beautiful, Sustainable Neighborhoods - 2005 | Brian Hanson, Christopher Alexander, Maggie Moore Alexander, Michael Mehaffy, Randall Schmidt | Center for Environmental Structure | 21 pp.
  Micro abstract: Argues that living neighborhoods arise from generative codes: ordered, participatory steps that let buildings and public spaces unfold from local people, land, and context.
- #SKRF4C Geography as a Science of the Earth’s Surface Founded on the Third View of Space - 2022 | Bin Jiang | Annals of GIS | 14 pp. | doi:10.1080/19475683.2021.1966502
  Micro abstract: Recasts geography around an organismic view of space, using scaling and spatial dependence to understand—and deliberately create—places with greater living structure.
- #PXG56P Harmony-Seeking Computations: A Science of Non-Classical Dynamics Based on the Progressive Evolution of the Larger Whole - 2009 | Christopher Alexander | Unpublished manuscript | 66 pp.
  Micro abstract: Proposes harmony-seeking computation as a creative process that repeatedly strengthens latent centers in a configuration while preserving and deepening the larger whole.
- #MJKTBB Living Images: A Recursive Approach to Computing the Structural Beauty of Images or the Livingness of Space - 2023 | Bin Jiang, Chris de Rijke | Annals of the American Association of Geographers | 19 pp. | doi:10.1080/24694452.2023.2178376
  Micro abstract: Measures an image’s structural beauty by recursively extracting its nested substructures, revealing a compact hierarchy that also captures visual saliency.
- #3XSLTA Structural Beauty: A Structure-Based Computational Approach to Quantifying the Beauty of an Image - 2021 | Bin Jiang, Chris de Rijke | Journal of Imaging | 15 pp. | doi:10.3390/jimaging7050078
  Micro abstract: Proposes a quantitative measure of structural beauty based on how many substructures an image contains and how strongly they form a hierarchy across scales.
- #ZU8GZV Structure-Preserving Transformations - 2002 | Christopher Alexander | The Nature of Order, Book Two: The Process of Creating Life | 4 pp. | doi:10.2307/j.ctv27ftw6c.5
  Micro abstract: Explains structure-preserving transformations: incremental changes that extend the centers and relationships already present in a place rather than weakening its wholeness.
- #AULNWD The Nature of Poetic Order - 1998 | Richard P. Gabriel | Warren Wilson Alumni Conference, Mount Holyoke | 99 pp.
  Micro abstract: Gabriel's slide essay relating poetry's formal order to Christopher Alexander's ideas of generative structure, exploring how constraint and pattern produce living order in creative work.
- #BYG3BQ Wholeness as a Hierarchical Graph to Capture the Nature of Space - 2015 | Bin Jiang | International Journal of Geographical Information Science | 14 pp. | doi:10.1080/13658816.2015.1038542
  Micro abstract: Models spatial wholeness as a hierarchical graph of mutually reinforcing centers, using PageRank and scaling depth to quantify the life of parts and wholes.

ontology (2)
- #CGE2NC Against Fantology - 2005 | Barry Smith | Experience and Analysis | 22 pp.
  Micro abstract: Critiques the idea that first-order logic reveals reality’s ontology, tracing its atomism, timelessness, Booleanism, and reductionism before proposing a six-category ontology and an enhanced Davidsonian formal language.
- #JZG4PM Against Fantology Again - 2016 | Ingvar Johansson | The Theory and Practice of Ontology | 12 pp.
  Micro abstract: Extends the critique of fantology through default ontologization, arguing that Quine’s canonical notation is incoherent about classes and excludes intentional phenomena and distinct modes of existence.

Procedural Generation & Co-Creation (14)
- #ABD2B8 Between Tech and Art: The Vegetation of Horizon Zero Dawn - 2018 | Gilbert Sanders, Guerrilla Games | Game Developers Conference (GDC) 2018 | 87 pp.
  Micro abstract: A production breakdown of Horizon Zero Dawn’s vegetation pipeline, covering global wind simulation, layered foliage motion, coverage-preserving alpha mipmaps, shading, asset LODs, placement, and cascaded shadows.
- #4TH488 Explainable AI for Designers: A Human-Centered Perspective on Mixed-Initiative Co-Creation - 2018 | Antonios Liapis, G. Michael Youngblood, Jichen Zhu, Rafael Bidarra, Sebastian Risi | 2018 IEEE Conference on Computational Intelligence and Games (CIG) | 8 pp. | doi:10.1109/CIG.2018.8490433
  Micro abstract: Defines explainable AI for game designers, mapping co-creative systems by their explainability, initiative, and domain overlap so explanations serve concrete design tasks.
- #9NQ94D Extracting Physics from Blended Platformer Game Levels - 2020 | Adam Summerville, Anurag Sarkar, Joseph C. Osborn, Sam Snodgrass | Joint Proceedings of the AIIDE 2020 Workshops (CEUR Workshop Proceedings, Vol. 2862) | 7 pp.
  Micro abstract: Infers playable jump physics from generated platformer levels, including hybrid physics models for levels that blend the geometry and style of multiple games.
- #66Q3W3 Ghost of Tsushima: Procedural Grass - 2021 | Eric Wohllaib, Sucker Punch Productions | Game Developers Conference (GDC) 2021 | 55 pp.
  Micro abstract: Explains Ghost of Tsushima’s compute-driven grass pipeline, from tiled placement and culling to indirect drawing, cubic Bézier blade geometry, variable LOD, wind animation, and material shading.
- #QHMFH2 Improved Alpha Testing Using Hashed Sampling - 2019 | Chris Wyman, Morgan McGuire | IEEE Transactions on Visualization and Computer Graphics | 12 pp. | doi:10.1109/TVCG.2017.2739149
  Micro abstract: Develops hashed alpha testing, a stable quasi-random thresholding method that preserves distant alpha-mapped foliage and hair while controlling flicker, anisotropy, and interactions with TAA and alpha-to-coverage.
- #7GR3AQ Procedural Content Generation through Quality Diversity - 2019 | Ahmed Khalifa, Antonios Liapis, Daniele Gravina, Georgios N. Yannakakis, Julian Togelius | 2019 IEEE Conference on Games (CoG) | 8 pp. | doi:10.1109/CIG.2019.8848053
  Micro abstract: Argues for quality-diversity algorithms in procedural generation, producing broad collections of varied, playable content while exposing the design space for exploration and co-creation.
- #CQBDX4 Procedural Content Generation via Machine Learning (PCGML) - 2018 | Aaron Isaksen, Adam Summerville, Amy K. Hoover, Andy Nealen, Christoffer Holmgård, Julian Togelius, Matthew Guzdial, Sam Snodgrass | IEEE Transactions on Games | 15 pp. | doi:10.1109/TG.2018.2846639
  Micro abstract: Defines and surveys PCGML: generating functional game content directly from models trained on existing examples, with uses spanning creation, completion, repair, critique, and compression.
- #EARFEK Procedural Generation of Villages on Arbitrary Terrains - 2012 | Adrien Bernhardt, Adrien Peytavie, Arnaud Emilien, Eric Galin, Marie-Paule Cani | The Visual Computer | 10 pp. | doi:10.1007/s00371-012-0699-7
  Micro abstract: Presents a three-stage procedural model that grows terrain-responsive village roads and settlements, partitions land into plausible parcels, and generates slope-adapted buildings with open shape grammars.
- #EDURTK Real-Time GPU Tree Generation - 2025 | Bastian Kuth, Carsten Faber, Dominik Baumeister, Max Oberberger, Pirmin Pfeifer, Quirin Meyer, Seyedmasih Tabaei | High-Performance Graphics – Symposium Papers | 10 pp. | doi:10.2312/hpg.20251168
  Micro abstract: Introduces a GPU work-graph pipeline that generates, animates, edits, and continuously LODs detailed seasonal trees every frame, replacing gigabytes of baked geometry with kilobytes of parameters.
- #GBXEP3 Realistic Modeling and Rendering of Plant Ecosystems - 1998 | Bernd Lintermann, Matt Pharr, Oliver Deussen, Pat Hanrahan, Przemyslaw Prusinkiewicz, Radomír Měch | Proceedings of SIGGRAPH ’98 | 12 pp. | doi:10.1145/280814.280898
  Micro abstract: Presents a foundational pipeline for authoring plant ecosystems through terrain design, ecological simulation, procedural plant models, approximate instancing, and efficient rendering of billion-primitive scenes.
- #BDBBL6 Real‐time Realistic Rendering and Lighting of Forests - 2012 | Eric Bruneton, Fabrice Neyret | Computer Graphics Forum | 11 pp. | doi:10.1111/j.1467-8659.2012.03016.x
  Micro abstract: Combines detailed z-field trees with terrain shader-maps to render immense forests in real time, preserving sun, sky, canopy, and ground-lighting effects through seamless, scale-consistent transitions.
- #PQ68ZH Responsive Real-Time Grass Rendering for General 3D Scenes - 2017 | Klemens Jahrmann, Michael Wimmer | Proceedings of the 2017 Symposium on Interactive 3D Graphics and Games (I3D ’17) | 10 pp. | doi:10.1145/3023368.3023380
  Micro abstract: Renders every grass blade as responsive tessellated geometry on arbitrary 3D surfaces, with per-blade wind, gravity, and collision physics plus aggressive culling that retains dense fields in real time.
- #WZ8DHP Runtime Evaluation of Procedural Content Generation in an Endless Runner Game Using Autonomous Agents - 2026 | Rishabh Kar | arXiv | 25 pp. | doi:10.48550/arXiv.2605.01783
  Micro abstract: Integrates procedural generation and validation in an endless runner, using aerial and ground agents to detect blocked or unnavigable content before the player reaches it.
- #NRBMD5 Towards Friendly Mixed Initiative Procedural Content Generation: Three Pillars of Industry - 2020 | Frederic Fol Leymarie, Gorm Lai, William Latham | Proceedings of the International Conference on the Foundations of Digital Games (FDG '20) | 4 pp. | doi:10.1145/3402942.3402946
  Micro abstract: Distills three requirements for industry-friendly co-creative PCG tools: preserve designer control, keep feedback loops short, and fit into existing production pipelines.

Roads, Trails & Movement (8)
- #G3TBNG A Sequential Two-Step Algorithm for Fast Generation of Vehicle Racing Trajectories - 2016 | J. Christian Gerdes, John Subosits, Nitin R. Kapania | Journal of Dynamic Systems, Measurement, and Control | 12 pp. | doi:10.1115/1.4033311
  Micro abstract: Generates near-optimal racing trajectories quickly by alternating between a minimum-time speed profile and a convex path update that reduces curvature.
- #B6P8L4 Active walker model for the formation of human and animal trail systems - 1997 | Dirk Helbing, Frank Schweitzer, Joachim Keltsch, Péter Molnár | Physical Review E | 34 pp. | doi:10.1103/physreve.56.2527
  Micro abstract: Models trail systems as self-organization: walkers reinforce attractive routes while unused traces fade, producing dendritic ant trails and low-detour pedestrian networks.
- #V4TQYB Interactive procedural street modeling - 2008 | Eugene Zhang, Gregory Esch, Guoning Chen, Pascal Müller, Peter Wonka | ACM Transactions on Graphics | 10 pp. | doi:10.1145/1360612.1360702
  Micro abstract: Lets designers generate and edit large street networks through tensor fields, combining procedural speed with brush-like global and local control over street patterns.
- #UYLTYJ Modelling the Evolution of Human Trail Systems - 1997 | Dirk Helbing, Joachim Keltsch, Péter Molnár | Nature | 11 pp. | doi:10.1038/40353
  Micro abstract: Shows how pedestrian trails emerge through feedback between destination-seeking walkers, existing paths, and vegetation recovery, yielding a compromise between directness and shared infrastructure.
- #GY93FG Mountain Trail Formation and the Active Walker Model - 2009 | J. P. Hague, S. J. Gilks | International Journal of Modern Physics C | 22 pp. | doi:10.1142/S0129183109014059
  Micro abstract: Extends the active-walker model to steep terrain, explaining zigzag mountain trails through slope avoidance, directional persistence, and mutual reinforcement by ascending and descending walkers.
- #LXV9AT Principles of Trail Layout and Design - 2019 | California State Parks | California State Parks Trails Handbook | 64 pp.
  Micro abstract: A field-oriented guide to durable trail design, emphasizing curvilinear alignment, natural drainage, sustainable grades, control points, and close reading of landform and soils.
- #XDEFZS Procedural Generation of Roads - 2010 | A. Peytavie, E. Galin, E. Guérin, N. Maréchal | Computer Graphics Forum | 10 pp. | doi:10.1111/j.1467-8659.2009.01612.x
  Micro abstract: Automatically routes and constructs roads with an anisotropic shortest-path method that weighs slope and obstacles while treating surface segments, bridges, and tunnels consistently.
- #ARP5U7 The Topography of Minoan Peak Sanctuaries - 1983 | A. A. D. Peatfield | The Annual of the British School at Athens | 8 pp. | doi:10.1017/s0068245400019729
  Micro abstract: Argues that Minoan peak sanctuaries were chosen for visibility and proximity to local settlements, forming a beacon-like sacred network whose contraction tracked settlement abandonment rather than cultic collapse.

Scenario-Based & Behavioral Programming (8)
- #P2W4J5 Adaptive Behavioral Programming - 2011 | David Harel, Nir Eitan | 8 pp. | doi:10.1109/ictai.2011.109
  Micro abstract: Adds reinforcements to live sequence charts and BPJ so scenario-based programs can learn from their environment, specifying goals to pursue and scenarios to avoid, with modular learning decompositions.
- #XQ5NKX Challenges in Modeling and Unmodeling Emergence, Rule Composition, and Networked Interactions in Complex Reactive Systems - 2023 | Assaf Marron, David Harel, Guy Frankel, Irun Cohen, Smadar Szekely | 8 pp. | doi:10.5220/0011728900003402
  Micro abstract: Position paper on modeling emergence, rule composition, and networked interactions in complex reactive systems, introducing "unmodeling"—explicitly excluding entities and behaviors from model execution.
- #D4VB7S Distributing Scenario-Based Models: A Replicate-and-Project Approach - 2017 | Assaf Marron, Daniel Gritzner, David Harel, Guy Katz, Joel Greenyer, Shlomi Steinberg | MODELSWARD 2017 | 16 pp. | doi:10.5220/0006271301820195
  Micro abstract: Distributes scenario-based models by replicating the full specification on every component and projecting it per component, mimicking centralized behavior while sharply reducing synchronization.
- #CSJARA Enhancing Scenario-Based Modeling Using Large Language Models - 2026 | Assaf Marron, David Harel, Guy Katz, Smadar Szekely | Communications in Computer and Information Science | Springer Nature Switzerland | pp. 43-68 | 26 pp. | doi:10.1007/978-3-031-96841-9_3
  Micro abstract: Extended methodology for combining LLM chatbots with scenario-based modeling: iterative generation of stand-alone scenarios checked by analysis and human review, framed as a step toward Wise Computing.
- #3JCRAD On Augmenting Scenario-Based Modeling with Generative AI - 2024 | Assaf Marron, David Harel, Guy Katz, Smadar Szekely | MODELSWARD 2024 | 12 pp. | doi:10.5220/0012427100003645
  Micro abstract: Outlines a structured method for using generative-AI chatbots in modeling: iteratively generate scenario-based model fragments, then analyze and inspect them to converge on an accurate system model.
- #QV3BWZ On tracing reactive systems - 2011 | David Harel, Shahar Maoz | Software &amp; Systems Modeling | 22 pp. | doi:10.1007/s10270-010-0151-2
  Micro abstract: Introduces model-based trace visualization and exploration for reactive systems, using scenario-based (LSC) abstractions and the Tracer prototype, demonstrated on a PacMan game.
- #TDS4H2 Relaxing Synchronization Constraints in Behavioral Programs - 2013 | Amir Kantor, David Harel, Guy Katz | LPAR 2013 (Logic for Programming, Artificial Intelligence, and Reasoning) | 17 pp. | doi:10.1007/978-3-642-45221-5_25
  Micro abstract: Proposes eager execution for behavioral programs: fast b-threads run ahead when synchronization outcomes are predictable, improving performance, modularity, and distributability, shown in a C++ BP framework.
- #M5788P Towards Behavioral Programming in Distributed Architectures - 2015 | Amir Kantor, Assaf Marron, David Harel, Gera Weiss, Guy Katz, Guy Wiener | Science of Computer Programming | 58 pp. | doi:10.1016/j.scico.2014.03.003
  Micro abstract: Extends behavioral programming to distributed architectures: b-threads as Erlang processes, eager execution to relax synchronization, and modular distributed execution, demonstrated on simulations and a quadrotor.

Technology, Scale & Conviviality (2)
- #WYH36B The City as Convivial Centre - 1974 | Leopold Kohr | Tract, no. 12 (Gryphon Press) | 18 pp.
  Micro abstract: Kohr's essay arguing that cities exist for convivial life rather than economic function, and that human-scale size is what lets a city serve as a centre of leisure, culture, and encounter.
- #67REFX The Question Concerning Technology - 1977 | Martin Heidegger | The Question Concerning Technology and Other Essays (Harper & Row) | 23 pp.
  Micro abstract: Heidegger's essay on the essence of technology as Enframing (Gestell), a mode of revealing that reduces the world to standing-reserve, and on art as a possible saving power.

Terrain, Hydrology & Erosion (8)
- #NV2YRW FastFlow: GPU Acceleration of Flow and Depression Routing for Landscape Simulation - 2024 | Aryamaan Jain, Bernhard Kerbl, Brandon Finley, Guillaume Cordonnier, James Gain | Computer Graphics Forum | 13 pp. | doi:10.1111/cgf.15243
  Micro abstract: A GPU framework for routing surface flow through terrain and its depressions fast enough to make erosion, river, lake, and ecosystem simulations interactive.
- #2284QZ From features to fingerprints: A general diagnostic framework for anthropogenic geomorphology - 2019 | Damian Evans, Erle C Ellis, Giulia Sofia, Paolo Tarolli, Wenfang Cao | Progress in Physical Geography: Earth and Environment | 34 pp. | doi:10.1177/0309133318825284
  Micro abstract: Integrates geomorphology, archaeology, and high-resolution remote sensing into a framework for reading anthropogenic landforms as landscape-scale sociocultural fingerprints.
- #96ZMGK Large Scale Terrain Generation from Tectonic Uplift and Fluvial Erosion - 2016 | Adrien Peytavie, Bedrich Benes, Guillaume Cordonnier, Jean Braun, Marie-Paule Cani, Éric Galin, Éric Guérin | Computer Graphics Forum | 11 pp. | doi:10.1111/cgf.12820
  Micro abstract: Generates large, controllable mountain terrains by coupling user-painted tectonic uplift with fluvial erosion, then turning the resulting stream graph into detailed landforms.
- #K82AS7 Legacy sediment: Definitions and processes of episodically produced anthropogenic sediment - 2013 | L. Allan James | Anthropocene | 11 pp. | doi:10.1016/j.ancene.2013.04.001
  Micro abstract: Broadens legacy sediment to episodically produced anthropogenic alluvium and colluvium, and explains its deposition, storage, and remobilization through sediment delivery–transport capacity dynamics.
- #DWXKYQ Physically-based analytical erosion for fast terrain generation - 2024 | Boris Gailleton, Guillaume Cordonnier, Petros Tzathas, Philippe Steer | Computer Graphics Forum | 14 pp. | doi:10.1111/cgf.15033
  Micro abstract: Turns the stream power law into an interactive terrain tool, replacing thousands of erosion time steps with analytical solutions and a direct control for landscape age.
- #MTDKDE Priority-Flood: An Optimal Depression-Filling and Watershed-Labeling Algorithm for Digital Elevation Models - 2014 | Clarence Lehman, David Mulla, Richard Barnes | Computers & Geosciences | 17 pp. | doi:10.1016/j.cageo.2013.04.024
  Micro abstract: Introduces Priority-Flood, a simple, optimal algorithm that removes drainage-blocking depressions from elevation models and can also derive watersheds and flow directions.
- #AK7NGE Procedural Riverscapes - 2019 | A. Peytavie, B. Benes, E. Galin, E. Guérin, J. Gain, T. Dupont, Y. Cortial | Computer Graphics Forum | 12 pp. | doi:10.1111/cgf.13814
  Micro abstract: Builds editable, animated riverscapes from bare terrain by carving hydrologically plausible channels and blending real-time procedural water primitives instead of simulating fluids.
- #DMTA8Y Terrain Generation Using Procedural Models Based on Hydrology - 2013 | Adrien Peytavie, Bedřich Beneš, Jean-David Génevaux, Éric Galin, Éric Guérin | ACM Transactions on Graphics | 10 pp. | doi:10.1145/2461912.2461996
  Micro abstract: Generates controllable, multiscale terrain from a sketched drainage network, representing rivers and landforms as an editable hierarchy of continuous procedural primitives.

Water Simulation & Rendering (12)
- #RBS5K6 A Layered Particle-Based Fluid Model for Real-Time Rendering of Water - 2010 | Daniel Scherzer, Florian Bagar, Michael Wimmer | Computer Graphics Forum | 7 pp. | doi:10.1111/j.1467-8659.2010.01734.x
  Micro abstract: Renders particle-based water and volumetric foam in real time using perspective-aware surface smoothing, physically guided foam formation, and layered depth compositing.
- #C4AY2M A Survey of Ocean Simulation and Rendering Techniques in Computer Graphics - 2011 | B. Crespin, D. Ghazanfarpour, E. Darles, J.-C. Gonzato | Computer Graphics Forum | 17 pp. | doi:10.1111/j.1467-8659.2010.01828.x
  Micro abstract: Surveys ocean graphics from spectral deep-water models to near-shore fluid simulation, then covers the foam, spray, and light transport needed for convincing rendering.
- #WZMZGY Advected river textures - 2009 | Dirk Arnold, Stephen Brooks, Tim Burrell | Computer Animation and Virtual Worlds | 11 pp. | doi:10.1002/cav.288
  Micro abstract: Combines a 2D Navier–Stokes solver, hydrostatic pressure columns, and advected procedural textures to render detailed, terrain-responsive rivers at real-time frame rates.
- #92XRH7 Lagrangian Texture Advection: Preserving both Spectrum and Velocity Field - 2011 |  Qizhi Yu, E. Bruneton, F. Neyret, N. Holzschuch | IEEE Transactions on Visualization and Computer Graphics | 13 pp. | doi:10.1109/tvcg.2010.263
  Micro abstract: Advects fluid textures with deformable particle grids, preserving both the input texture’s visual spectrum and exact motion along the velocity field without cumulative stretching.
- #8SERGP Real-time Breaking Waves for Shallow Water Simulations - 2007 | Markus Gross, Matthias Müller-Fischer, Nils Thürey, Simon Schirm | 15th Pacific Conference on Computer Graphics and Applications (Pacific Graphics 2007) | 8 pp. | doi:10.1109/PG.2007.33
  Micro abstract: Adds real-time overturning waves to shallow-water heightfields by detecting steep fronts and spawning connected particle sheets that collapse into splashes and foam.
- #CWC7H9 Real-time Rendering of Enhanced Shallow Water Fluid Simulations - 2013 | Antonio Susín, Jesús Ojeda | Computers & Graphics | 9 pp.
  Micro abstract: Builds a real-time rendering pipeline for shallow-water simulations, adding fine surface detail, advected foam, photon-based caustics, and screen-space reflection and refraction.
- #MVUJ8Z Real-time Rendering of River Networks - 2010 | Quintijn Hendrickx, Rafael Bidarra, Ruben M. Smelik | Proceedings of the ACM SIGGRAPH Symposium on Interactive 3D Graphics and Games | 1 pp.
  Micro abstract: Renders branching river networks efficiently with quadratic Bézier curves, GPU distance fields, and streaming normal maps instead of dense geometry or particle simulation.
- #5MGCZ5 Real-time River Representation by Dynamic Control of Data on Waves - 2008 | Makoto Kosugi, Nobuhiko Mukai, Yasuhiro Kato | 4 pp. | doi:10.3169/itej.62.2063
  Micro abstract: Dynamically switches river-wave models by viewing distance, preserving nearby reflection and wave detail while retaining wind-driven motion across the full landscape.
- #XDESU9 Scalable real‐time animation of rivers - 2009 | Eric Bruneton, Fabrice Neyret, Nicolas Holzschuch, Qizhi Yu | Computer Graphics Forum | 11 pp. | doi:10.1111/j.1467-8659.2009.01363.x
  Micro abstract: Animates rivers across vast terrains by computing steady flow locally and advecting fine surface detail only where visible, at a screen-space sampling density.
- #869NHK Very Fast Real-Time Ocean Wave Foam Rendering Using Halftoning - 2011 | Ian Parberry, Jennifer R. Alford, Mary Yingst | Proceedings of the 6th International North American Conference on Intelligent Games and Simulation (GAMEON-NA) | 7 pp.
  Micro abstract: Uses a spectrally controlled halftone mask to make texture-based ocean foam dissipate as clumped bubbles that pop, rather than merely fading transparently.
- #A2QB8L Water Flow in Portal 2 - 2010 | Alex Vlachos | ACM SIGGRAPH 2010 Course: Advances in Real-Time Rendering in 3D Graphics and Games | 54 pp.
  Micro abstract: Explains Portal 2’s production-friendly water shader: artist-painted flow maps advect layered normal maps, while offsets and noise suppress repetition and pulsing on limited hardware.
- #PBM2TC Water surface wavelets - 2018 | Chris Wojtan, Matthias Müller-Fischer, Miles Macklin, Nuttapong Chentanez, Stefan Jeschke, Tomáš Skřivan | ACM Transactions on Graphics | 13 pp. | doi:10.1145/3197517.3201336
  Micro abstract: Represents water waves as spatially varying directional amplitudes, enabling vast interactive simulations with fine detail, moving obstacles, solid coupling, and direct artistic control.

### 4. Assistant tool calls

#### Tool call: `search_text`

```json
{
  "limit": 15,
  "query": "README main function module"
}
```

#### Tool call: `search_text`

```json
{
  "limit": 15,
  "query": "terrain generation source code"
}
```

### 5. Tool result: search_text

{"error":"\"no function clause matching in String.replace/4\""}

### 6. Tool result: search_text

Exact matches

1. Source file: CMakeLists.txt
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/Q01ha2VMaXN0cy50eHQ#content
   Size: 32165 bytes, 849 lines
   Matching excerpt:
      cmake_minimum_required(VERSION 3.24) set(MOPPE_IOS FALSE) set(MOPPE_TVOS FALSE) set(MOPPE_MOBILE_APPLE FALSE) if(CMAKE_SYSTEM_NAME STREQUAL "iOS") set(MOPPE_IOS TRUE) set(MOPPE_MOBILE_APPLE TRUE) elseif(CMAKE_SYSTEM_NAME STREQUAL "tvOS") set(MOPPE_TVOS TRUE) set(MOPPE_MOBILE_APPLE TRUE) endif() # Ninja and Makefiles otherwise default to an unoptimized build. Keep symbols # for useful crash reports while making the normal desktop build representative # of real gameplay performance. if(NOT CMAKE_CONFIGURATION_TYPES AND NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "Build type (Debug, Release, RelWithDebInfo, or MinSizeRel)" FORCE) set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS Debug Release RelWithDebInfo MinSizeRel) endif() # Without an explicit target, Xcode uses the installed SDK version as the # minimum OS, making device builds uninstallable on slightly older iPhones. if(MOPPE_MOBILE_APPLE AND NOT DEFINED CMAKE_OSX_DEPLOYMENT_TARGET) if(MOPPE_TVOS) set(CMAKE_OSX_DEPLOYMENT_TARGET "16.0" CACHE STRING "Minimum supported tvOS version") else() set(CMAKE_OSX_DEPLOYMENT_TARGET "15.0" CACHE STRING "Minimum supported iOS version") endif() endif() project(mo
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/Q01ha2VMaXN0cy50eHQ#content"]

2. Source file: docs/terrain-expressions.md
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy90ZXJyYWluLWV4cHJlc3Npb25zLm1k#content
   Size: 34566 bytes, 640 lines
   Matching excerpt:
      # Terrain expressions, recipes, and pipelines Moppe's portable terrain subsystem separates six kinds of value: 1. `ScalarField` is a lazy expression DAG. 2. `GeologicalSource` retains the recipe and selected field to materialize. 3. `TerrainTransform` describes a terrain-to-terrain operation. 4. `TerrainProgram` composes one source with an ordered transform sequence. 5. `WorldRecipe` binds a program to its physical world and water datum. 6. `TerrainView` lends materialized samples to readings and analyses. The game, Terrain Lab, unit tests, and command-line tools share these types. None of them contains renderer or platform graphics API state. ## Scalar-field graph `ScalarField` is a small handle to an immutable `std::variant` node. Child links are `std::shared_ptr<const Node>`, so reusing a field creates a DAG without copying raster data. Reference counting is sufficient because the graph is acyclic. Current nodes cover constants, coordinates, arithmetic, fused multiply-add, sine, smoothstep, Perlin noise, fractal Brownian motion, and ridged noise. Seeds and fractal parameters are explicit graph data. `MultiplyAdd` is a semantic node because the historical generator relied on fuse
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy90ZXJyYWluLWV4cHJlc3Npb25zLm1k#content"]

3. Source file: docs/engine-atlas.md
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9lbmdpbmUtYXRsYXMubWQ#content
   Size: 12609 bytes, 224 lines
   Matching excerpt:
      # Moppe engine atlas This is the reader's map of the current engine after RFC-0001. It names the values that make up a world, the mutable state that rides it, the immutable reading that presents a frame, and the CMake targets that carry those boundaries. Read it before the detailed subsystem documents; the `current-engine-refactoring` track is retained as the history of how this shape was reached, not as the architecture reference. ## One world, one frame The main flow is data and borrows, not a generic scene graph or an ownership diagram for CMake: ```mermaid flowchart LR recipe["WorldRecipe + TerrainProgram"] --> build["GeneratedWorld::Builder"] build --> world["GeneratedWorld"] world --> session["GameSession"] world --> view["FrameView"] session --> view view --> scene["world, actor, water, effect, HUD presentation"] scene --> renderer["render::Renderer"] renderer --> metal["Metal backend"] renderer --> webgpu["WebGPU backend"] app["application: loading, input, mode selection"] --> build app --> session app --> view ``` `GeneratedWorld` is the stable owner of one completed landscape. `GameSession` is the mutable life played on that landscape. `FrameView` is a new immutable readi
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9lbmdpbmUtYXRsYXMubWQ#content"]

4. Source file: docs/project.org
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9wcm9qZWN0Lm9yZw#content
   Size: 39327 bytes, 737 lines
   Matching excerpt:
      #+title: Moppe project #+startup: overview * Purpose Moppe is currently a motorcycle game and a laboratory for generated worlds. It has several inherited or experimental modes, but the main line of work is the random world: generate a landscape, understand how it formed, render it convincingly, and ride through it. The immediate goal is not yet to build a large game around that world. It is to make the world coherent enough that riding it produces places worth noticing: waterways that make sense, terrain with a readable history, and routes and obstacles that arise from the land rather than being scattered on top of it. The more speculative ambition is an inhabited procedural world. The [[file:../ideas/second-author.md][second-author notes]] explore how geology might eventually support paths, roads, centers, and settlements. The [[file:../ideas/tending-the-world.md][tending-the-world essay]] develops the related possibility that riding, interpreting, and changing the landscape could become one continuous form of play instead of a game/editor split. The [[file:../ideas/structure-of-space.md][structure-of-space notes]] explore an irregular cellular tissue between smooth terrain fields
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9wcm9qZWN0Lm9yZw#content"]

5. Source file: docs/renderer-design.md
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9yZW5kZXJlci1kZXNpZ24ubWQ#content
   Size: 32316 bytes, 534 lines
   Matching excerpt:
      # Moppe rendering & platform architecture Status: current Metal/backend implementation record. This document preserves the port's technical decisions and implementation detail; the [engine atlas](engine-atlas.md) is the current map of source ownership, state, and CMake targets. A playable browser backend now implements the same renderer contract through WebGPU; see [WebAssembly and WebGPU](web.md). Android remains a future possibility. ## Port goals and retained constraints 1. Render through Metal on macOS and iOS with one shared game codebase. 2. Keep the game's look and feel: same pass order, same haze/lighting math, same HUD, same physics. 3. Abstract the renderer and platform behind small, game-shaped interfaces so a WebGPU (or other) backend is an additive job, not a rewrite. 4. Refactor as we go: split the 4000-line main.cc into modules, remove dead code, de-boost, kill hidden global state where cheap. 5. Modernize where it pays: vertex-pulled terrain from a height texture (replaces ~100 MB of CPU-built triangle-strip soup), an explicit post chain, background-thread world generation with a loading screen (required on iOS anyway). ## Review amendments (adopted) A three-lens ad
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9yZW5kZXJlci1kZXNpZ24ubWQ#content"]

6. Source file: docs/refactoring-seams.md
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9yZWZhY3RvcmluZy1zZWFtcy5tZA#content
   Size: 10376 bytes, 191 lines
   Matching excerpt:
      # Refactoring seams RFC-0001 established these boundaries one at a time. This page preserves the observable contracts that survived those moves; it is a characterization baseline, not a second architecture proposal or a current work plan. The [engine atlas](engine-atlas.md) is the reader-facing map of the resulting ownership and target shape. ## Surface `map::Surface` is the materialized ground reading over one `SurfaceDomain`. Its `SurfaceAtlas` owns geometry plus named optional hydrology, geology, ecology, and use sections; `game::SurfacePresentation` is the only bridge that turns them into renderer lanes. | Contract | Characterization owner | | --- | --- | | Continuous elevation and normal reads agree with the authoritative heightmap, including the periodic seam. | `surface_reconstruction_matches_bounded_heightmap_interpolation` and `surface_reconstruction_matches_periodic_seam_interpolation` in `tests/map/surface_test.cc` | | Mutating the heightmap does not change surface reads until `Surface::refresh`; refresh clears dependent materialized sections. | `surface_refresh_is_an_explicit_materialization_barrier` and `surface_presentation_is_the_numeric_bridge_for_typed_sections` in
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9yZWZhY3RvcmluZy1zZWFtcy5tZA#content"]

7. Source file: ideas/reading-map.md
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/aWRlYXMvcmVhZGluZy1tYXAubWQ#content
   Size: 61127 bytes, 1041 lines
   Matching excerpt:
      # A reading map for inhabited procedural worlds *Papers, books, talks, tools, and playable arguments around Moppe's longer roads.* ## How to use this map This is not a literature review and certainly not a syllabus. It is a map of nearby intellectual country: work that might sharpen Moppe's terrain system, its paths and riding, and the more speculative idea of a game about tending an inhabited world. The categories overlap. Christopher Alexander leads toward graph theory; graph theory leads toward cellular meshes; meshes lead toward Townscaper; Townscaper leads toward mixed-initiative creation; a motocross jump leads from level design into optimal control. Those crossings are part of the point. Entries marked **begin here** are especially good first encounters. A paper is not included merely because its method should be implemented. Some are useful as vocabulary, some as provocations, and some because they expose a productive difference between their problem and ours. Links were checked in July 2026. Where a stable DOI or author-hosted copy was available, it is preferred over an aggregator; books without a useful open edition are named without pretending that a product page is a sc
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/aWRlYXMvcmVhZGluZy1tYXAubWQ#content"]

8. Source file: ideas/watersheds-of-execution.md
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/aWRlYXMvd2F0ZXJzaGVkcy1vZi1leGVjdXRpb24ubWQ#content
   Size: 13418 bytes, 287 lines
   Matching excerpt:
      # The watersheds of execution *Notes toward reading a program as a landscape of paths, catchments, and moving attention.* ## The resemblance Moppe's terrain machinery and its source-code analysis have arrived at nearly the same object from opposite directions. The hydrology begins with a field, derives a drainage graph, accumulates contributing area, finds catchments and confluences, and asks where water is likely to travel. The program begins with source files, derives a call graph, accumulates structural importance, finds communities and bottlenecks, and asks where execution is likely to travel. This is not only a convenient metaphor. Both are directed systems whose local structure produces larger paths: ```text terrain program cell or drainage node function downhill connection call catchment entrypoint reachability region contributing area transitive callers confluence high fan-in discharge call frequency or PageRank sediment load carried complexity watershed divide module or community boundary closed depression recursive component ocean return from the outermost entrypoint ``` A river is not bad because it carries a great deal of water, and a function is not bad because it has 
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/aWRlYXMvd2F0ZXJzaGVkcy1vZi1leGVjdXRpb24ubWQ#content"]

9. Source file: moppe/game/terrain_lab_model.hh
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvZ2FtZS90ZXJyYWluX2xhYl9tb2RlbC5oaA#content
   Size: 3544 bytes, 102 lines
   Matching excerpt:
      #ifndef MOPPE_GAME_TERRAIN_LAB_MODEL_HH #define MOPPE_GAME_TERRAIN_LAB_MODEL_HH #include <moppe/map/terrain_evaluator.hh> #include <cstddef> #include <memory> #include <optional> #include <vector> namespace moppe::game { // The CPU-side state of one Terrain Lab session. It owns replayable // checkpoints and the original map snapshot; the renderer and its UI only // observe this state and decide how to present it. struct TerrainLabEvaluationProgress { enum class Phase { Idle, Materializing, Applying }; Phase phase = Phase::Idle; std::size_t source_rows_completed = 0; std::size_t source_rows_total = 0; std::size_t completed_stages = 0; std::size_t total_stages = 0; std::size_t current_stage = 0; bool evaluating () const noexcept { return phase != Phase::Idle; } }; class TerrainLabModel { public: TerrainLabModel () = default; TerrainLabModel (const TerrainLabModel&) = delete; TerrainLabModel& operator= (const TerrainLabModel&) = delete; TerrainLabModel (TerrainLabModel&&) = delete; TerrainLabModel& operator= (TerrainLabModel&&) = delete; ~TerrainLabModel (); // Borrow the map for a Lab session. A caller may supply any field // evaluator, including none for a portable CPU-only session.
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvZ2FtZS90ZXJyYWluX2xhYl9tb2RlbC5oaA#content"]

10. Source file: moppe/game/game.cc
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvZ2FtZS9nYW1lLmNj#content
   Size: 120359 bytes, 2929 lines
   Matching excerpt:
      // The game: the port of main.cc's MoppeGLUT application class onto // the platform/render abstractions. World generation runs on a // background thread behind a loading screen; the frame follows the // exact pass order of the GL build's render_scene(). #include <moppe/platform/platform.hh> #include <moppe/profile.hh> #include <moppe/render/renderer.hh> #include <moppe/render/text.hh> #include <moppe/game/blob_shadow.hh> #include <moppe/game/chase_camera.hh> #include <moppe/game/cinematic_flight.hh> #include <moppe/game/dust.hh> #include <moppe/game/forest.hh> #include <moppe/game/frame_view.hh> #include <moppe/game/game_session.hh> #include <moppe/game/generated_world.hh> #include <moppe/game/glider_render.hh> #include <moppe/game/graphics_benchmark.hh> #include <moppe/game/graphics_settings.hh> #include <moppe/game/hud.hh> #include <moppe/game/input_frame_adapter.hh> #include <moppe/game/inspector_ui.hh> #include <moppe/game/river_surface.hh> #include <moppe/game/stars.hh> #include <moppe/game/surface_presentation.hh> #include <moppe/game/terrain.hh> #include <moppe/game/terrain_lab.hh> #include <moppe/game/tree_stand.hh> #include <moppe/game/vehicle_render.hh> #include <moppe/ga
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvZ2FtZS9nYW1lLmNj#content"]

11. Source file: moppe/terrain/world_recipe.cc
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvdGVycmFpbi93b3JsZF9yZWNpcGUuY2M#content
   Size: 3372 bytes, 78 lines
   Matching excerpt:
      #include <moppe/terrain/world_recipe.hh> #include <stdexcept> #include <utility> #include <variant> namespace moppe::terrain { namespace { float normalized_water_datum_for (spatial_extent_t extent, meters_t water_datum) { return meters_value (water_datum) / extent_value (extent)[1]; } void set_program_water_datum (TerrainProgram& program, float datum) { program.source.sea_level = datum; for (TerrainTransform& transform : program.transforms) if (auto* analytical = std::get_if<AnalyticalErosion> (&transform)) analytical->sea_level = datum; else if (auto* orogeny = std::get_if<OrogenyEvolution> (&transform)) orogeny->evolution.sea_level = datum; else if (auto* trails = std::get_if<TrailFormation> (&transform)) trails->sea_level = datum; } } WorldRecipe::WorldRecipe (spatial_extent_t extent, int resolution, Topology topology, Seed seed, meters_t water_datum, TerrainGenerationProfile generation_profile, TerrainProgram terrain_program) : m_extent (extent), m_resolution (resolution), m_topology (topology), m_seed (seed), m_water_datum (water_datum), m_generation_profile (generation_profile), m_terrain_program (std::move (terrain_program)) { if (m_terrain_program.seed != m_seed) throw std:
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvdGVycmFpbi93b3JsZF9yZWNpcGUuY2M#content"]

12. Source file: moppe/terrain/editor.hh
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvdGVycmFpbi9lZGl0b3IuaGg#content
   Size: 3456 bytes, 90 lines
   Matching excerpt:
      #ifndef MOPPE_TERRAIN_EDITOR_HH #define MOPPE_TERRAIN_EDITOR_HH #include <moppe/terrain/program.hh> #include <cstddef> #include <optional> namespace moppe::terrain { // A small adapter over the TerrainTransform variant. It deliberately has // no transform-specific switchboard: each alternative supplies the editing // operations, so adding a transform means adding its own local semantics. class TerrainTransformEditor { public: explicit TerrainTransformEditor (const TerrainTransform& transform) : m_transform (&transform) {} explicit TerrainTransformEditor (TerrainTransform& transform) : m_transform (&transform), m_mutable_transform (&transform) {} std::size_t property_count () const; TransformProperty property (std::size_t index) const; float normalized_property (std::size_t index) const; bool set_normalized_property (std::size_t index, float value); bool adjust_natural_property (std::size_t index, int direction); // Some transform edits carry a source-wide invariant. The program // editor consumes this capability without knowing transform alternatives. std::optional<float> source_sea_level () const; private: void require_mutable () const; const TerrainTransform* m_transform; Terrain
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvdGVycmFpbi9lZGl0b3IuaGg#content"]

13. Source file: moppe/terrain/river.hh
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvdGVycmFpbi9yaXZlci5oaA#content
   Size: 857 bytes, 20 lines
   Matching excerpt:
      #ifndef MOPPE_TERRAIN_RIVER_HH #define MOPPE_TERRAIN_RIVER_HH #include <moppe/terrain/terrain_view.hh> namespace moppe::terrain { // Hydraulic geometry for the visible water surface. Orogeny owns the // valley shape; these laws only decide how much of its drainage axis reads // as running water. Keeping them outside a terrain transform prevents the // renderer from depending on the retired raster channel carve. meters_t river_width (square_meters_t contributing_area) noexcept; meters_t river_depth (square_meters_t contributing_area) noexcept; // A visible channel begins when the width law reaches two terrain cells. // Expressing that threshold through the source grid keeps the same physical // river network across generation profiles. square_meters_t visible_river_minimum_area (const TerrainGrid& grid) noexcept; } #endif
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/bW9wcGUvdGVycmFpbi9yaXZlci5oaA#content"]

14. Source file: plan/done/rfc-004-erosion-performance.md
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/cGxhbi9kb25lL3JmYy0wMDQtZXJvc2lvbi1wZXJmb3JtYW5jZS5tZA#content
   Size: 5693 bytes, 114 lines
   Matching excerpt:
      # RFC-004: The erosion performance path - Status: Superseded on 2026-07-16 - Area: terrain simulation, performance - Interacts with: RFC-001 (reduces droplet load), RFC-003 (ledger on GPU) ## Problem This proposal is retained as a historical design record. RFC-001's orogeny model replaced droplet erosion in ordinary world generation, and the unused droplet implementation was removed. None of the droplet GPU work below is on the active roadmap; source-field acceleration remains independently useful. World generation time is dominated by terrain work that the codebase has already architected for acceleration but not yet wired up. The pointwise source field runs on the CPU interpreter during the loading screen even though a Metal evaluator exists and is ~10x faster; droplet erosion runs serially inside its lockstep batches even though the batch structure was explicitly designed as a GPU work boundary (`docs/terrain-expressions.md`: "lower a whole lockstep batch to a GPU compute kernel"). ## Current situation Three distinct tiers, smallest first: 1. **Wiring gap.** Terrain Lab injects the accelerated evaluator (`moppe/game/terrain_lab.cc:508` calls `platform::create_field_evaluator()`)
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/cGxhbi9kb25lL3JmYy0wMDQtZXJvc2lvbi1wZXJmb3JtYW5jZS5tZA#content"]

15. Source file: tests/terrain/world_recipe_test.cc
   Resource: https://m.sheaf.less.rest/3CV92Z/source-files/dGVzdHMvdGVycmFpbi93b3JsZF9yZWNpcGVfdGVzdC5jYw#content
   Size: 2357 bytes, 56 lines
   Matching excerpt:
      #include <moppe/map/generate.hh> #include <moppe/map/terrain_evaluator.hh> #include <moppe/terrain/world_recipe.hh> #include <tests/test.hh> #include <cmath> #include <variant> MOPPE_TEST (world_recipe_binds_physical_world_to_its_program) { using namespace moppe; using namespace moppe::terrain; const WorldRecipe recipe = make_world_recipe (spatial_extent_in_metres (Vec3 (5000, 320, 5000)), 33, Topology::Torus, Seed { 77 }, 50.0f * mp_units::si::metre, TerrainGenerationProfile::Fast); MOPPE_CHECK (recipe.resolution () == 33); MOPPE_CHECK (recipe.topology () == Topology::Torus); MOPPE_CHECK (recipe.seed () == Seed { 77 }); MOPPE_CHECK (recipe.generation_profile () == TerrainGenerationProfile::Fast); MOPPE_CHECK_NEAR (recipe.normalized_water_datum (), 50.0f / 320.0f, 0.0f); const TerrainProgram& program = recipe.terrain_program (); MOPPE_CHECK (program.seed == recipe.seed ()); MOPPE_CHECK_NEAR ( program.source.sea_level, recipe.normalized_water_datum (), 0.0f); const auto& orogeny = std::get<OrogenyEvolution> (program.transforms.front ()); const auto& trails = std::get<TrailFormation> (program.transforms.back ()); MOPPE_CHECK_NEAR ( orogeny.evolution.sea_level, recipe.normalized_water
   Read the complete file with read blocks=["https://m.sheaf.less.rest/3CV92Z/source-files/dGVzdHMvdGVycmFpbi93b3JsZF9yZWNpcGVfdGVzdC5jYw#content"]

Approximate matches

1. Source: Large Scale Terrain Generation from Tectonic Uplift and Fluvial Erosion (#96ZMGK), Adrien Peytavie, Bedrich Benes, Guillaume Cordonnier, Jean Braun, Marie-Paule Cani, Éric Galin, Éric Guérin, p. 1
  Context:
    #A48PSA Large Scale Terrain Generation from Tectonic Uplift and Fluvial Erosion
      #X3SQUZ 2. Related Work
  Score: 0.026
  Related excerpt #4V6QB9:
      Procedural terrain generation is usually based on fractals and these approaches are among the most commonly used in computer graphics. Fractal-based methods exploit the observation that primary terrain features repeat at different scales. Ebert et al. [EMP + 02] provide an overview of these methods, including various noises, such as the fractional Brownian motion [MVN68] and the adaptive subdivision method [FFC82]. These algorithms only provide indirect control over the resulting terrain by modifying the input parameters of the algorithm [SBW06]. Moreover, they lack geological realism because the distribution of generated structures follows stochastic patterns observed only on relatively new mountain ranges. The geological structures formed by fluvial erosion, such as networks of parallel valleys, are not captured by these methods.

2. Source: Large Scale Terrain Generation from Tectonic Uplift and Fluvial Erosion (#96ZMGK), Adrien Peytavie, Bedrich Benes, Guillaume Cordonnier, Jean Braun, Marie-Paule Cani, Éric Galin, Éric Guérin, p. 6
  Context:
    #A48PSA Large Scale Terrain Generation from Tectonic Uplift and Fluvial Erosion
      #A8NK92 6. Results
        #CBX4QV 6.2. Rendering
  Score: 0.019
  Related excerpt #W29Q2Q:
      The second interactive rendering method consists in defining the surface of the terrain as an elevation function defined as the sum of Gaussian kernels centered at each node multiplied by the node height. The height is then normalized by the sum of the kernels at that point. This results in a smoother geometry than the Phong tessellation, but it is harder to emphasize the water network.

3. Source: Real‐time Realistic Rendering and Lighting of Forests (#BDBBL6), Eric Bruneton, Fabrice Neyret, p. 4
  Context:
    #ZX2JYE Real-time Realistic Rendering and Lighting of Forests
      #Y8VXY9 4. Our Model
  Score: 0.015
  Related excerpt #DJL33M:
      framework of [BN08]. This method uses a dynamic quadtree on CPU, with GPU producers and caches to generate and store the terrain data for the currently visible quads. We extend it with new producers and caches for our forest data. More precisely, for each new visible terrain quad, and depending on its level in the quadtree (see below), we produce on GPU either a set of seeds to instantiate trees, or a coverage map tile for our shader-map representation (see Fig. 3):

4. Source: Terrain Generation Using Procedural Models Based on Hydrology (#DMTA8Y), Adrien Peytavie, Bedřich Beneš, Jean-David Génevaux, Éric Galin, Éric Guérin, p. 6
  Context:
    #RULAFW Terrain Generation Using Procedural Models Based on Hydrology
      #NDTMMW 7 Terrain Tree Definition
  Score: 0.028
  Related excerpt #BFJ7G2:
      The terrain is stored in a novel hierarchical representation where its surface is defined procedurally as a continuous function h(\mathbf{p}) : \Omega \rightarrow \mathbf{R} . We define h using a construction tree whose leaves are

5. Source: Terrain Generation Using Procedural Models Based on Hydrology (#DMTA8Y), Adrien Peytavie, Bedřich Beneš, Jean-David Génevaux, Éric Galin, Éric Guérin, p. 2
  Context:
    #RULAFW Terrain Generation Using Procedural Models Based on Hydrology
      #3G9YBV 3 Algorithm Overview
  Score: 0.026
  Related excerpt #YVP4AW:
      In the last step, the algorithm gathers information from the previous steps and generates the continuous-terrain model. We propose a novel procedural terrain representation that defines the terrain as a construction tree. The leaves are parameterized primitives that define different terrain features, such as hills, mountains, valleys, and different types of rivers. The inner tree nodes combine the primitives by blending, adding, subtracting, or carving. This approach creates a memory efficient representation of large terrains, comprising numerous levels of details.

6. Source: Terrain Generation Using Procedural Models Based on Hydrology (#DMTA8Y), Adrien Peytavie, Bedřich Beneš, Jean-David Génevaux, Éric Galin, Éric Guérin, p. 7
  Context:
    #RULAFW Terrain Generation Using Procedural Models Based on Hydrology
      #SZAWPC 8 Results
  Score: 0.02
  Related excerpt #ARNY9X:
      has native multiresolution support. We can visualize the terrain at multiple scales, and we can use view-dependent clipping algorithms or resource-dependent strategies. The vector-based primitive description of the generated terrain is compact (average of 1 \text{ km}^2 \approx 1.5 \text{ kB} ) and allows the storage of large terrains as shown in Table 3. Even if the construction tree describe the whole domain, the user can evaluate only a portion of the landscape. Hoya Island (Fig 17-B) has an area of 3368 \text{ km}^2 and is composed of 81853 primitives using 8,180 kB. A 30 \text{ km}^2 portion of the terrain represents only 2068 primitives and a 225 kB storage.

7. Source: Terrain Generation Using Procedural Models Based on Hydrology (#DMTA8Y), Adrien Peytavie, Bedřich Beneš, Jean-David Génevaux, Éric Galin, Éric Guérin, p. 0
  Context:
    #RULAFW Terrain Generation Using Procedural Models Based on Hydrology
      #SFQZPA 1 Introduction
  Score: 0.02
  Related excerpt #X2EJNY:
      Researchers have made considerable progress toward developing efficient methods for synthetic terrain generation. Existing techniques can be roughly classified into procedural, physics-based, and sketch- or example-based. Procedural methods, as well as physics-based algorithms, often lack controllability. Sketch-based methods involve manual editing that can be tedious. Example-based algorithms are limited by the provided input. Moreover, only the physics-based algorithms provide results that are correct from the standpoint of geology. Probably the most important problem in terrain generation for the field of computer graphics is the absence of algorithms that would allow the quick generation of controllable, and geologically reliable outputs. A related problem is the scalability of existing algorithms. The generated terrains usually represent only features of a single scale that are stored in a simple regular height field that becomes the standard data representation in many terrain-modeling systems. The height field is later converted into a mesh suitable for fast visualization with varying levels of details.

8. Source: Terrain Generation Using Procedural Models Based on Hydrology (#DMTA8Y), Adrien Peytavie, Bedřich Beneš, Jean-David Génevaux, Éric Galin, Éric Guérin, p. 6
  Context:
    #RULAFW Terrain Generation Using Procedural Models Based on Hydrology
      #NDTMMW 7 Terrain Tree Definition
  Score: 0.019
  Related excerpt #UDAUV4:
      primitives describing terrain fragments, and the inner nodes combine subtrees together. In this way, the elevation of a point can be defined as a combination of a hierarchy of primitives. Our approach

9. Source: Terrain Generation Using Procedural Models Based on Hydrology (#DMTA8Y), Adrien Peytavie, Bedřich Beneš, Jean-David Génevaux, Éric Galin, Éric Guérin, p. 1
  Context:
    #RULAFW Terrain Generation Using Procedural Models Based on Hydrology
      #CZMG8P 2 Related Work
  Score: 0.018
  Related excerpt #44JWC7:
      Procedural techniques are a popular choice in computer graphics because of the simple implementation and wide range of terrains they provide when a few parameters are changed. One of the most important algorithms is the adaptive subdivision introduced by [Fournier et al. 1982], which provides an intrinsic level of detail. Noise-based procedural approaches, such as the Perlin noise [Perlin 1985], provide varying details by combining noise functions at various scales (see [Ebert et al. 1998] for an in-depth overview). Fractal-based methods produce large-scale terrains with unlimited detail, but they often lack control over the placement of terrain features, such as rivers and valleys. Furthermore, they provide terrains that look geologically fresh, whereas real terrains are usually affected by erosion and weathering.

10. Source: Physically-based analytical erosion for fast terrain generation (#DWXKYQ), Boris Gailleton, Guillaume Cordonnier, Petros Tzathas, Philippe Steer, p. 1
  Context:
    #JDHNVB Physically-based analytical erosion for fast terrain generation
      #2BWKC4 2. Previous Work
  Score: 0.015
  Related excerpt #44R764:
      Procedural generation [EMP*02] builds terrains from a combination of mathematical functions, especially multi-frequency noise that mimics the self-similarity of nature across scales [MVN68]. This mathematical foundation leads to methods that are extremely fast, parallel, and unbounded in size. These approaches are usually hard to control, although this issue has been recently alleviated, either by local editing tools such as noise brushes [dCB09], global interpolation around diffusion curves [HGA*10], or in the gradient domain [GPM*22]. It is, however, still difficult to ensure the realism and consistency of the results. One solution is to build the terrain around a procedural river network [GGG*13] which ensures hydrological consistency. Thanks to our analytical solution of the physical equations, our model ensures consistency of the hydrology network and the topography, and introduces a temporal parameter.

11. Source: Physically-based analytical erosion for fast terrain generation (#DWXKYQ), Boris Gailleton, Guillaume Cordonnier, Petros Tzathas, Philippe Steer, p. 1
  Context:
    #JDHNVB Physically-based analytical erosion for fast terrain generation
      #2BWKC4 2. Previous Work
  Score: 0.014
  Related excerpt #WAGRZH:
      Terrain generation methods are generally classified among three main categories: example-based (or data-based), procedural, and physically-based [GGP*19]. Our new analytical model - inspired by previous work in Earth sciences - is, in essence, a physically-based procedural method.

12. Source: Procedural Generation of Villages on Arbitrary Terrains (#EARFEK), Adrien Bernhardt, Adrien Peytavie, Arnaud Emilien, Eric Galin, Marie-Paule Cani, p. 2
  Context:
    #PEJ7QK Procedural Generation of Villages on Arbitrary Terrains
      #3V5J62 3 Overview and Notations
  Score: 0.017
  Related excerpt #4J2JH4:
      Our algorithm for generating villages on arbitrary terrains is summarized in Figure 2. Given \Omega , a few environment maps and a user-defined growth scenario, we first grow the village skeleton, then generate land parcels and building footprints to get the village layout, and finally create 3D geometry. These three steps are detailed in Sections 4 to 6.

13. Source: Realistic Modeling and Rendering of Plant Ecosystems (#GBXEP3), Bernd Lintermann, Matt Pharr, Oliver Deussen, Pat Hanrahan, Przemyslaw Prusinkiewicz, Radomír Měch, p. 2
  Context:
    #3286QK Realistic modeling and rendering of plant ecosystems
      #L5JV3W 3 TERRAIN SPECIFICATION
  Score: 0.016
  Related excerpt #EFSNZA:
      Terrain data may have several sources. Representations of real terrains are available, for example, from the U.S. Geological Survey [30]. Several techniques have also been developed for creating synthetic terrains. They include: hand-painted height maps [65], methods for generating fractal terrains (reviewed in [38]), and models based on the simulation of soil erosion [28, 38].

14. Source: Runtime Evaluation of Procedural Content Generation in an Endless Runner Game Using Autonomous Agents (#WZ8DHP), Rishabh Kar, p. 2
  Context:
    #MDEACB Runtime Evaluation of Procedural Content Generation in an Endless Runner Game Using Autonomous Agents
      #E3MLLW 2 Background and Related Work
        #279W7Y 2.2 Procedural Terrain Generation Techniques
  Score: 0.028
  Related excerpt #Z88PNN:
      There are several ways in which procedural terrain can be generated, and the choice usually depends on what the game is trying to create. One of the foundational approaches towards terrain generation is the use of noise functions to create fractal height maps. Earlier work used the diamond-square algorithm for midpoint displacement, and Perlin Noise and its successor forms are still widely used for creating synthetic terrains with multiple variations.

15. Source: Runtime Evaluation of Procedural Content Generation in an Endless Runner Game Using Autonomous Agents (#WZ8DHP), Rishabh Kar, p. 10
  Context:
    #MDEACB Runtime Evaluation of Procedural Content Generation in an Endless Runner Game Using Autonomous Agents
      #GL8ZA2 4 Design, Methodology, and Implementation
        #5W8C4J 4.4 Procedural Terrain Generation
  Score: 0.024
  Related excerpt #DDSAKG:
      The procedural terrain generation system in Momentum provides the player with a continuous traversable surface, while managing object spawning, navigation-mesh updates, and tile lifecycle during runtime. The system is designed to be scalable and memory-efficient. The terrain is not produced through noise-based height maps, since the game uses uniform ground tiles where height variation is minimal. Emphasis is therefore placed on continuous tile streaming, controlled object placement, navigation surface management, and incremental cleanup, rather than on topographical synthesis.

### 7. Assistant tool calls

#### Tool call: `read`

```json
{
  "blocks": [
    "https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9lbmdpbmUtYXRsYXMubWQ#content"
  ]
}
```

#### Tool call: `read`

```json
{
  "blocks": [
    "https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9wcm9qZWN0Lm9yZw#content"
  ]
}
```

### 8. Tool result: read

SOURCE FILE
Path: docs/engine-atlas.md
Resource: https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9lbmdpbmUtYXRsYXMubWQ#content
Size: 12609 bytes, 224 lines

# Moppe engine atlas

This is the reader's map of the current engine after RFC-0001. It names the
values that make up a world, the mutable state that rides it, the immutable
reading that presents a frame, and the CMake targets that carry those
boundaries. Read it before the detailed subsystem documents; the
`current-engine-refactoring` track is retained as the history of how this
shape was reached, not as the architecture reference.

## One world, one frame

The main flow is data and borrows, not a generic scene graph or an ownership
diagram for CMake:

```mermaid
flowchart LR
  recipe["WorldRecipe + TerrainProgram"] --> build["GeneratedWorld::Builder"]
  build --> world["GeneratedWorld"]
  world --> session["GameSession"]
  world --> view["FrameView"]
  session --> view
  view --> scene["world, actor, water, effect, HUD presentation"]
  scene --> renderer["render::Renderer"]
  renderer --> metal["Metal backend"]
  renderer --> webgpu["WebGPU backend"]
  app["application: loading, input, mode selection"] --> build
  app --> session
  app --> view
```

`GeneratedWorld` is the stable owner of one completed landscape.
`GameSession` is the mutable life played on that landscape. `FrameView` is a
new immutable reading composed for each visible frame; it does not own a
renderer, a platform object, or mutable actor state. The application selects
input and mode, advances the session, composes the view, and invokes the
concrete presenters in game-shaped order.

## Domains and ownership

| Domain | Owns | Does not own | Main locations |
| --- | --- | --- | --- |
| Quantity and finite-section vocabulary | `spatial::Bundle`, typed domains, and mp-units-facing section types | A terrain map, a world, or a rendering policy | `moppe/spatial/`, `moppe/quantities.hh` |
| Terrain programs | Field DAGs, terrain sources, transforms, recipes, and portable evaluators | A completed map, scene, platform, or renderer | `moppe/terrain/` |
| Completed world | Heightmap, surface, materialized analyses, water surface, and trails | Mutable player state, GPU resources, or an event loop | `moppe/map/`, `moppe/game/generated_world.*` |
| Simulation | Mutable rider, vehicle, glider, walker, camera, stars, dust, and checkpoint state | Loading, `GeneratedWorld` ownership, and platform effects | `moppe/mov/`, `moppe/game/game_session.*` |
| Frame and scene presentation | Immutable frame readings and focused terrain, water, actor, effect, and HUD presenters | Simulation mutation or an OS event loop | `moppe/game/frame_view.*`, game presentation files |
| Application and platform | Loading/activation, input adaptation, mode selection, host services, and terminal `main` | Portable terrain and simulation laws | `moppe/game/game.cc`, `moppe/game/terrain.*`, `moppe/game/terrain_lab.*`, `moppe/platform/` |
| Renderer and backend | Game-shaped draw/resource API, Metal resources, passes, command submission, and capture/timing lifecycle | Terrain policy, session state, or a generic render graph | `moppe/render/`, `moppe/render/metal/`, `moppe/shaders/metal/` |

`moppe/game/` is intentionally not one architectural layer. Its source files
belong to world construction, simulation, scene presentation, or application
composition according to what they own. The CMake targets below make that
division executable.

## World and intrinsic readings

`terrain::WorldRecipe` binds a terrain program to physical world parameters
and water datum. `GeneratedWorld::Builder` is the short-lived mutable
capability that evaluates the map, rebuilds `map::Surface`, analyzes hydrology,
and materializes derived readings. Once active, ordinary gameplay receives
const views of the completed world.

`map::SurfaceDomain` is the one finite lattice for the ground. It owns the
topology, site correspondence, spacing, and reconstruction stencil. Its
`SurfaceAtlas` groups typed 0-cochains by the named materialization boundary:

| Group | Typed sections | Valid when |
| --- | --- | --- |
| Geometry | `surface_elevation`, `surface_normal`, `snow_support` | `Surface::refresh()` |
| Hydrology | `channel_flux`, `surface_moisture`, `waterline_distance` | World hydrology/materialization |
| Geology | `erosion_exposure`, `deposition_cover` | Geological materialization |
| Ecology | `tree_habitat`, `forest_cover` | Ecological materialization |
| Use | `trail_influence`, `home_base_influence` | Trail and home-base materialization |

Geometry is always present after refresh. Later groups are individually
optional: absence means the corresponding world-building barrier has not run,
while a present all-zero section is a real reading. `map::WaterSurface` uses
the same domain but a distinct water bundle: `surface_elevation`,
`wave_amplitude`, and `water_velocity`. It is not a ground-atlas group merely
because both surfaces have matching texture dimensions.

`GeneratedWorld::Hydrology` is similarly a complete analytical value rather
than a collection of app-level optionals. It contains standing water, lake
census, drainage, fractional channels, waterways, and the river network.
`WaterSurface` and `TrailNetwork` remain optional completed-world artifacts:
a Terrain Lab preview may intentionally omit hydrology, and a terrain program
may omit trail formation. The detailed vocabulary, validity rules, and
quantity-to-texture mappings live in [Surface atlas](surface-atlas.md).

## State, lifetime, and handoff

| Value or phase | Owner and rule | Deliberately outside it |
| --- | --- | --- |
| `WorldRecipe` and `WorldParams` | Immutable construction description for a world | Live player progress and renderer history |
| `GeneratedWorld` | Non-copyable, non-movable owner of completed terrain and analyses | Platform, session, and GPU ownership |
| Loading candidate | Worker builds a fresh world; the loading preview sees copied height snapshots only | Mutation of the active world/session |
| Activation | Main thread transfers the completed owner once, retires the old session before its old world, then creates a fresh session | A half-built visible world |
| `GameSession` | Mutable run against one completed world's terrain and surface borrows | A replacement world or loading lifecycle |
| `GameState` | Copyable snapshot of mutable session systems, portable only between sessions on the same world | Terrain, water, renderer history, window state, and asynchronous loading |
| `FrameView` | Immutable per-frame snapshot of selected camera, lighting, graphics, poses, HUD, overlays, and visibility | Renderer/platform types and later simulation mutation |
| Terrain Lab transaction | Named mutable terrain borrow that restores the game's map on exit | An implicit permanent edit to the active world |

The ordinary playable step is
`advance_game_session(context, session, input, seconds_t)`. Its context lends
only the world-side readings simulation needs. Platform-side speech and other
application effects return as a small result for the application to realize.
The full checkpoint and replay boundary is described in
[Game state and replay](game-state.md); completed-world construction and
handoff are described in [Generated worlds](generated-world.md).

## Presentation and renderer boundaries

Presentation turns completed-world and frame readings into the renderer's
game-shaped API without pushing numeric packing or platform work down into the
terrain/simulation layers.

| Input | Presentation owner | Renderer-facing result |
| --- | --- | --- |
| Typed ground atlas and trails | `game::SurfacePresentation` | Terrain material/path texture lanes |
| Typed water bundle plus water datum/extent | `game::WaterPresentation` | Numeric ocean setup and water texture lanes |
| Completed-world river network | `game::RiverSurface` | Curved river ribbon mesh/data |
| `FrameView`, world, and session readings | Focused world, actor, water, effect, and HUD routines | Retained resources and `DrawList` commands in fixed frame order |
| Renderer calls | `render::Renderer` | Backend-independent resource/pass requests |
| Metal renderer state | `MetalTerrainResources`, `MetalWaterResources`, `MetalFrameTargets`, `MetalFrameEncoding` | Retained world resources, target resources, and one drawable submission |

Terrain, Water, and Scene operations share one lazy scene encoder; their
separate names do not imply a generic render graph or separate depth histories.
The Metal facade owns drawable acquisition, command-buffer lifetime, capture,
timing, and benchmark completion. See [Renderer and platform architecture]
(renderer-design.md) for resource and pass detail.

## Target graph

The source ownership above is reflected by these CMake targets. Arrows point
from a consumer to the target it consumes. Dashed Apple edges exist only in
Apple configurations; exactly one selected-platform edge is present per build.

```mermaid
flowchart LR
  spatial["moppe_spatial"] --> units["mp-units"]
  terrain["moppe_terrain"] --> spatial
  world["moppe_world"] --> terrain
  simulation["moppe_simulation"] --> world
  simulation --> render["moppe_render"]
  scene["moppe_scene"] --> simulation
  scene --> world
  scene --> render
  scene --> botany["atelier_botany"]
  scene -.-> apple["moppe_apple"]
  app["moppe_app"] --> scene
  app -.-> mac["moppe_platform_mac"]
  app -.-> ios["moppe_platform_ios"]
  app -.-> web["moppe_platform_web"]
  metal["moppe_metal"] --> render
  webgpu["moppe_webgpu"] --> render
  terrain_metal["moppe_terrain_metal"] --> terrain
  mac --> metal
  mac --> terrain_metal
  mac --> apple
  ios --> metal
  ios --> apple
  web --> webgpu
  desktop["moppe"] --> app
  desktop --> mac
  phone["moppe-ios"] --> app
  phone --> ios
  browser["moppe-web"] --> app
  browser --> web
  tests["moppe-tests"] --> scene
  tools["terrain tools"] --> world
```

`moppe_spatial` is deliberately header-only: its types expose mp-units
vocabulary but need no translation unit. `moppe_terrain` keeps reusable field
and hydrology algorithms free of world, scene, and platform code.
`moppe_world` adds concrete map storage, materialization, `GeneratedWorld`,
the renderer-free Terrain Lab model, and deterministic water-capture selection.

`moppe_simulation` has a real dependency on `moppe_render`: session-owned
Stars retain meshes and Stars/Dust expose their presentation operations. This
is an explicit current constraint, not a claim that physics needs Metal.
`moppe_scene` composes the completed-world and session readings, with
Apple-common asset/glyph support where available, but has no OS event loop or
renderer backend. `moppe_app` holds the two host-service callers (`Terrain`
and `TerrainLab`); terminal programs retain `game.cc` because it defines
`main` and chooses the macOS, iOS, or browser host.

The ordinary desktop game consumes the app/scene path; portable tests begin at
the testable scene target and do not link a desktop event loop. Terrain
command-line tools consume only `moppe_world`, so they do not pull in the
desktop platform merely because unrelated presentation code was compiled into
a broad archive.

## Current scope and deliberate gaps

This atlas describes the completed RFC-0001 slice. It does not claim that the
Atelier proposals have replaced Moppe, that every run is bitwise reproducible,
or that every renderer backend has visual feature parity.

- The duplicated periodic heightmap seam and implicit elevation/chart origins
  remain current-engine facts; a seam-free topology and registered frame
  projections remain Atelier-earth work.
- `GameState` makes fixed-world session replay practical, but world generation,
  renderer history, window state, and loading are not checkpoint state.
- Metal is the full-fidelity native backend. WebGPU is the supported playable
  browser backend, with a deliberately lower-cost default presentation;
  Android remains unimplemented.
- Persistent places, routes, and player traces belong to later world work, not
  to the completed-world/session boundary described here.

## Detailed maps

- [Surface atlas](surface-atlas.md) — domains, all typed sections, validity,
  and presentation lanes.
- [Terrain expressions](terrain-expressions.md) — field/program/recipe and
  evaluator design.
- [Generated worlds](generated-world.md) — construction capability and
  activation lifetime.
- [Game state and replay](game-state.md) — session checkpoint and benchmark
  boundary.
- [Refactoring seams](refactoring-seams.md) — preserved characterization and
  runtime smoke contracts.
- [Renderer and platform architecture](renderer-design.md) — Metal resources,
  frame encoding, and host implementation detail.

### 9. Tool result: read

SOURCE FILE
Path: docs/project.org
Resource: https://m.sheaf.less.rest/3CV92Z/source-files/ZG9jcy9wcm9qZWN0Lm9yZw#content
Size: 39327 bytes, 737 lines

#+title: Moppe project
#+startup: overview

* Purpose

Moppe is currently a motorcycle game and a laboratory for generated worlds.
It has several inherited or experimental modes, but the main line of work is
the random world: generate a landscape, understand how it formed, render it
convincingly, and ride through it.

The immediate goal is not yet to build a large game around that world.  It is
to make the world coherent enough that riding it produces places worth
noticing: waterways that make sense, terrain with a readable history, and
routes and obstacles that arise from the land rather than being scattered on
top of it.

The more speculative ambition is an inhabited procedural world.  The
[[file:../ideas/second-author.md][second-author notes]] explore how geology might
eventually support paths, roads, centers, and settlements.  The
[[file:../ideas/tending-the-world.md][tending-the-world essay]] develops the
related possibility that riding, interpreting, and changing the landscape
could become one continuous form of play instead of a game/editor split.  The
[[file:../ideas/structure-of-space.md][structure-of-space notes]] explore an
irregular cellular tissue between smooth terrain fields and later paths,
construction, and memory.  These are promising design directions, not current
subsystems or a settled roadmap.

* Current product

** Random world

This is the most active and interesting game mode. A =TerrainProgram= combines
a geological source, an explicit seed, and an ordered sequence of transforms.
The normal play profile evolves periodic terrain with the orogeny model,
forms a designed trail circuit, computes standing water and continuous river
alignments, chooses a safe spawn, and puts the motorcycle into the result.

The world is topologically periodic.  Terrain lookup and the newer analysis
passes respect that topology; it is not merely a rendering trick at the map
edge.

** Terrain Lab

Terrain Lab is the instrument panel for the random-world pipeline.  It edits
the terrain program, regenerates previews, and displays derived readings such
as slope, drainage area, basins, streams, standing water, and lake classes.
It is already central to development, but it is still an engineering tool
rather than a polished player-facing mode.

** Other modes

- Pico mode loads a fixed real-world heightmap.
- The renderer testbed exercises the portable rendering layer.

These modes are real and should remain healthy, but they do not currently add
up to a single designed game structure.  New world-generation work should
not be forced to justify all of them or prematurely unify them.

* What is implemented

** Terrain language and evaluation

- [X] Runtime scalar-field expression DAG and geological recipes.
- [X] First-class =TerrainProgram= with source, seed, and transforms.
- [X] CPU evaluation shared by tools and game generation.
- [X] Metal compilation for pointwise terrain fields.
- [X] Fast, play, and research generation profiles.
- [X] Periodic generation and seam-aware tests.
- [ ] Stable program serialization.
- [ ] Cross-toolchain golden terrain corpus.

Deterministic replay is tested within the current evaluator and toolchain.
Cross-machine bit identity is an aim, not yet a repository-wide guarantee.

** Water and erosion

- [X] Periodic D8 dry-surface drainage with slope, contributing area,
  basins, and sinks.
- [X] Orogeny-local D-infinity dry routing with conservative two-receiver
  accumulation over a typed unique-sample terrain bundle.
- [X] Finite-time =n=1= analytical stream-power transform with physical age,
  uplift, erodibility, drainage exponent, and routing controls.
- [X] Default shallow-continent orogeny source with a typed uplift field,
  implicit per-step incision, routing refresh, and interleaved diffusion.
- [X] Priority-flood standing-water surface and deterministic lake census.
- [X] Puddle, pond, lake, and sea classifications.
- [X] Area/depth/volume permanence policy for rendered inland water.
- [X] Standing lakes rendered in the random game world.
- [X] Depression-aware drainage through lakes with topological accumulation.
- [X] Explicit global-ocean identity and route-proven inland body spills.
- [X] Body inlet and outflow catchment ledgers for rendering and erosion.
- [X] Directed dry river reaches split at confluences and water bodies.
- [X] Dense cubic river alignments with confluence-continuous flow distance.
- [X] Multi-row river ribbons animated along the continuous alignment.
- [X] Standing-water sheets that accept river current through each mouth.
- [X] Clustered high-flow knickpoint candidates with physical drop and slope.
- [X] Finite-time stream-power orogeny in the world generation program.
- [ ] Erosion coupled to lake infill and spillway incision.

The dry drainage reference still describes strict descent on bare terrain.
Terrain Lab now interprets the =FloodField= as a wet drainage surface: strict
downhill D8 routes on slopes and one deterministic route through each level
water body.  The largest connected below-sea component is the explicit ocean;
enclosed low basins fill to their own spills.  Inland bodies expose exact
spills, inlets, and accumulated outflow. River rendering consumes the wet
graph without mutating the terrain.

** Riding and presentation

- [X] Metal renderer on macOS and iOS.
- [X] Terrain LOD, vegetation, atmosphere, water, shadows, post-processing,
  and vehicle effects.
- [X] Motorcycle physics and generated-world spawn selection.
- [X] Desktop, simulator, and physical-phone workflows.
- [ ] A clear game loop built specifically around discovering a generated
  world.
- [ ] Persistent places, routes, or player traces in generated worlds.

* Active work

** DONE Keep periodic rivers on the ground and inside the frame budget

Reach alignments are locally continuous on the torus, but the renderer used
to join a reach to the downstream reach's canonical coordinate.  At a world
seam that produced a map-wide translucent triangle: the apparent aerial
waterways in wide views, and a large source of river/ocean overdraw.  Junctions
now select the downstream endpoint's nearest periodic image, with a regression
test that bounds every generated triangle edge.

Rivers are also an independent hot graphics feature and benchmark block.  The
standing-water pass writes depth before ribbons, and fully fogged ribbon
fragments exit before procedural flow, reflection, and shadow work.  On the
seed-123 aerial benchmark the all-features median improved from 25.35 ms to
16.50 ms after the geometry repair and fog rejection; normal gameplay
profiling returns to a steady 60 Hz, with occasional view-dependent spikes
still worth addressing through spatial river-mesh partitioning.

Acceptance evidence:

- [X] A synthetic seam-crossing junction contains no map-wide triangle.
- [X] Wide cinematic and feature-targeted river/mouth captures contain no
  aerial sheets and retain clean mouth layering.
- [X] The 32-case GPU partition measures ocean and river ribbons separately.
- [X] Full build and test suite pass with the Metal river shader compiled.

** DONE Make continuous rivers the rendering authority

The game and Terrain Lab build retained multi-row ribbons from dense
=RiverAlignment= values. They follow damped cubic trajectories, widen with
physical catchment laws, carry a flow coordinate continuously through
confluences, derive depth against the orogeny terrain, and dissolve beneath
standing water at mouths. The shader orients two-phase advected detail along
the curved surface. The standing-water painter now carries only real water
bodies and mouth currents; raster channel carving and droplet erosion are
retired.

Acceptance evidence:

- [X] Seed 123 completes wet routing and renders in both Lab and gameplay.
- [X] Width increases with catchment and animation follows a globally
  continuous downstream distance.
- [X] Seven-row cross-sections feather at banks and remain above sampled
  terrain without visible z-fight.
- [X] Mouths blend into their water body and continue current into its sheet.
- [X] Rendering consumes derived readings and does not edit terrain.

This is not finished river morphology. Confluences still use overlapping soft
coverage, standing-water shores expose their grid, and a steep reach is shaded
as a rapid rather than turned into a vertical fall or spray system.

** TODO Make channels read as watercourses rather than routed ribbons

- [X] Resample reach centerlines with bounded cubic tangents while preserving
  exact source/downstream endpoints, periodic continuity, and terrain contact.
- [X] Replace raster channel beds with bank-limited cross-sections derived
  directly from the continuous alignment and orogeny terrain.
- [X] Replace plane-wave streaks with flow-advected value noise, restrained
  churn/cascade foam, a bank contact line, and Fresnel sky reflection.
- [X] Fade lake/ocean mouths into standing water, extending the current only
  when the next wet receiver is an adjacent D8 cell rather than a body-level
  routing shortcut.
- [ ] Build a non-overlapping junction mesh. A blended fan was rejected after
  feature-targeted captures showed that it darkened the already overlapping
  reach strips.
- [X] Add deterministic clean captures for a river, confluence, mouth,
  waterfall candidate, or lake selected from the hydrology itself.
- [X] Cluster steep visible-channel steps into deterministic fall candidates,
  expose them in FALLS and TRACE, and intensify cascade foam from that reading.
- [ ] Distinguish free-falling lips from steep continuous cascades using a
  longer longitudinal profile or explicit channel morphology.
- [ ] Render a curved falling sheet and soft foot spray only after a candidate
  has an actual lip/face; a vertical quad over the continuous heightfield was
  tested and rejected because it intersected terrain and broke the river.
- [ ] Give the rider water contact, crossing, and depth feedback after the visual
  surface is stable.

** TODO Improve lake identity and inspection

- [X] Distinguish the global ocean from enclosed below-sea basins.
- [X] Add mean depth and an exact per-body spill contract.
- [X] Show body class, mean depth, inlet count, and catchment in TRACE.
- [ ] Add lake-size distribution export.
- [ ] Make =WaterPermanence= editable program data rather than a default C++
  policy at the rendering boundary.

** DONE Establish the first global stream-power comparison

The first global pass implements the finite-time characteristic solution from
Tzathas et al. for =n=1=.  It evaluates initial elevation and uplift along the
depression-aware drainage trees, fixes ocean cells, and optionally recomputes
routing with relaxed fixed-point passes.  It is a first analytical slice, not
the paper's complete multigrid solver.

Terrain Lab exposes =+AGE= independently from =+DROP= and =+TALUS=.  The
=terrain-stream-power-experiment= tool replays source, analytical, droplets,
and their combinations from one checkpoint.  On seed 123 at 257 square, the
200 ky / four-pass / 30K-drop combined-plus-talus result reduced dry sinks
from 515 in the source and 416 after droplets to 311, and reduced ponds from
46 after droplets to 13.  It retained 98 persistent-channel cells versus 132
after droplets alone.  The analytical-only result creates many one-cell
discontinuities, confirming the paper's warning that hillslope treatment is
part of a usable method rather than optional polish.

* Near horizon

** NEXT Couple erosion to standing water

Once wet routing is trustworthy, droplets can deposit on entering still
water, transfer discharge to a classified outlet, and incise spillways under
the basin's full flow.  This should allow ponds to fill, outlets to retreat,
and drainage networks to mature instead of treating every sink as a terminal
error.

** NEXT Complete the analytical erosion method

Keep the new finite-time transform as the drainage-scale stage and droplets as
the detailed finishing stage.  Next, add the paper's coarse-to-fine routing
acceleration and slope/hillslope correction, then repeat the comparison across
several fixed seeds and at rider resolution.  FastFlow-style GPU routing
remains a possible backend for the same graph contract rather than a different
erosion meaning.

** NEXT Let hydrology drive water rendering

Build rendering inputs from the same structured water account used by
erosion: surface level, depth, body identity, flow direction, discharge,
surface slope, shore distance, and turbulence.  Use body scale to distinguish
calm ponds and lakes from ocean swell; extract high-discharge routes as river
ribbons with flow-aligned detail; derive rapids, falls, foam, and spray from
discharge and changes in the longitudinal bed profile.  Rivers should first
be an inspectable rendering layer, before any channel-carving transform.

** NEXT Make the random world a more legible ride

Hydrology should pay off in play.  Lakes can become boundaries, spill points
can become gates, valleys can guide motion, and regenerated worlds can offer
recognizable destinations.  The first experiments should use overlays or
temporary markers and remain reversible; they do not require committing to a
settlement simulation.

** NEXT Define a repeatable ride-and-judge loop

The project has fast deterministic captures and analytical readings.  It also
needs a small human evaluation routine: generate a named seed/profile, inspect
its readings, ride it, and record what was memorable or broken.  This is the
bridge between terrain metrics and the actual game.

* Later / ideas under consideration

** LATER Centers and routes

The strongest part of the second-author proposal is its first small step:
derive candidate places from terrain readings, show why they were selected,
and test whether they feel meaningful from the motorcycle.  A later route
network could connect accepted places under different movement costs before
any terrain carving occurs.

This direction should begin as observation and overlays.  =CenterSet= and
=RouteNetwork= are names from a design essay, not existing types or promised
architecture.

** LATER Roads, settlements, and world memory

Road carving, settlement formation, traffic ledgers, and player-made desire
paths are compelling possible consequences of good terrain and routing.
They are deliberately not decomposed into implementation tasks yet.  The
project does not know enough about its places or movement networks to specify
them honestly.

* Working rules

- Keep generated-world behavior reproducible and seeds reportable.
- Make derived knowledge inspectable before making it authoritative.
- Keep readings non-mutating; make terrain edits explicit transforms.
- Prefer small experiments with a visible or numerical acceptance test.
- Treat negative experimental results as progress when they narrow the model.
- Keep important policies as named values rather than hidden thresholds.
- Judge changes both in Terrain Lab and from the motorcycle.

Detailed engineering guidance remains in
[[file:working-practices.md][working-practices.md]].

* Log

Entries below are a chronological experiment record. They intentionally
describe implementations that may since have been replaced; the Current
product and What is implemented sections above are authoritative.

** 2026-07-16 Rivers become continuous geometry

- Retired particle droplets, raster channel carving, their Terrain Lab
  controls, dedicated experiments, program variants, and active tests.
- Made dense cubic =RiverAlignment= values the shared geometric reading for
  every reach, with physical width/depth and globally continuous flow distance.
- Rebuilt running water as a seven-row soft-edged ribbon, with bank-limited
  levels, curve-oriented two-phase advection, and standing-water mouth fades.
- Restricted lattice water sheets to standing bodies and the river currents
  that enter them. Orogeny remains the sole terrain-forming world model.

** 2026-07-13 Uplift and erosion can grow the mountain range together

- Added an opt-in shallow-continent source whose typed uplift field reuses the
  geological recipe without treating tectonic velocity as initial elevation.
- Implemented deterministic backward-Euler =n=1= stream-power evolution with
  priority-flood routing refreshed each step, fixed ocean base level, and
  interleaved hillslope diffusion.
- Added Orogeny Lab controls, age comparison, convergence and process-volume
  reports, a pipeline option, and Fast/Play/Research duration profiles.
- At 1025 square, seed 123's 20-step Research run took about 6.2 seconds on an
  M2 Pro and produced coherent coast-scale dendritic relief; the ordinary
  world source remains unchanged while the new look is compared explicitly.

** 2026-07-11 Swash at the waterline, grass in hillside shade

Rider feedback pass on the new mesh-shader surfaces.

- The lattice waterline no longer stands still: a value-noise-phased
  swash term breathes the effective water column across the shallow
  shelf, the foam surge follows the run-up, and the edge alpha
  feathers over the last centimeters instead of ending at the discard
  cliff.
- Grass blades now inherit their hillside's light: a per-blade ground
  shade from the terrain normal against the sun keeps swards on
  sun-averted slopes dark instead of glowing against shaded terrain.
  A distance floor on blade width stops sub-pixel shimmer.

Agreed next milestone: retire the river ribbons onto the lattice
water machinery — splat reach surface levels and flow vectors into
rasters so the wet-tile mesh pipeline renders rivers too, with
world-space flow-map advection replacing the ribbon uv streaks.

** 2026-07-11 Mesh shaders arrive: grass patches, lattice water, moisture

The first Metal mesh pipelines (gated on =MTLGPUFamilyMetal3=, with
fallbacks), plus the hydrology feeding vegetation directly.

- Grass: blade construction factored into shared per-blade functions;
  an object stage culls 4x2-cell patches (distance, terrain band,
  frustum) and a mesh stage emits surviving blades as indexed
  triangles, 32 per meshlet at 8 vertices / 6 primitives.  The
  instanced vertex path remains as fallback and shares all styling.
- Moisture: =terrain/moisture.cc= derives ground moisture from the
  flood census and drainage (multi-source BFS to standing water plus a
  drainage term, torus-aware, unit-tested).  Grass samples it for
  height, dryness color, and density: lush banks, bleached ridges, and
  a few FPS back because dry ground grows fewer blades.
- Lattice water: near standing water renders through a mesh pipeline
  on the terrain's own sample grid — an object stage walks a 700 m
  window of 15x15-cell tiles, probes wetness from the same RG water
  raster, and culls dry or unseen tiles; the mesh stage emits 16x16
  vertex lattices sharing the ocean fragment shader.  The coarse 300
  grid keeps the horizon; both passes discard on the same radius so
  they partition exactly.  Near shorelines now resolve at terrain
  resolution.
- The lake checkerboard from the paused shoreline investigation is
  solved, and it was never grid aliasing: the fragment ripple normals
  were crossed plane-wave sines interfering into a plaid — the third
  appearance of that failure (ocean foam, grass patches, now ripples).
  Drifting value noise replaced them; swell amplitude also averages a
  five-tap footprint so shallow shelves stop flickering per cell.

Seed-123 captures: lakes are continuous organic water with shorelines
that hug the banks; the mouth bay reads clean turquoise.  Rider capture
93 FPS with grass, lattice water, and moisture all on.  Remaining known
seams: the fine/coarse water boundary can show a subtle tone shift at
700 m, and shore foam still blobs at mouth aprons.

** 2026-07-11 GPU grass loses its jitter, terraces, and stripes

Three defects in the new procedural grass shared one theme: derived
data where exact data was available.

1. Blade seeds recovered the window's integer origin by dividing floats
   (=uint(origin_world / spacing)= with an unrepresentable spacing), so
   the truncation flickered by one cell as the camera moved and re-rolled
   every seed in the field — the full-field jitter.  The uniforms now
   carry the origin as exact integer cell indices and both seeds and
   world positions derive from them.
2. Roots sampled terrain height and normal nearest-neighbor, so every
   blade in a terrain cell snapped to one height (terraced rows on
   slopes) and one normal (per-cell shading patchwork).  Both samples
   are now bilinear.
3. The patchiness field was plane-wave sines, which band into stripes —
   the same plaid failure the ocean foam had.  It is now two octaves of
   =moppe_value_noise=.

Also in this pass: whole blades reject early (radius, terrain band,
frustum with sway margin) before any styling math and clip out with a
degenerate position, valid per-blade since every vertex agrees; the
outer density LOD starts earlier; blades lean slightly downhill with
the ground normal; and the grass fragment shadow dropped from five PCF
taps to one — per-blade color and occlusion variation hides the
penumbra completely.  Rider capture 88 FPS at the twin-lake spawn.

** 2026-07-11 Water becomes transparent over ridable channels

Design rule from riding the world: anything worth rendering as water gets
a real channel, and water transparency follows its actual column.

- Channel carving no longer scales depth down for sub-cell streams; every
  visible reach earns its full 0.4-2.5 m bed, so the motorcycle physically
  drops into any stream it crosses (the carve writes the authoritative
  heightmap).  The shared width law widened to =clamp(0.012 sqrt(A),
  1.5, 24)= so trunk rivers read as rivers inside their AGE-scale valleys.
- Ribbons now pack the true water column into the green vertex channel
  (span constant shared with the shader).  Transparency, deep-water color,
  and the bank contact line all key on real depth: a hand-deep stream is
  glass over its bed, a meter reads as a body, and shallow streams carry
  no bank foam at all.
- Dropping opacity exposed strip self-overlap as dark wedges at bends.  A
  curvature-clamped width was tried and rejected (D8 splines pinch
  everywhere); the real fix is a stencil plane on the scene depth target
  (=Depth32Float_Stencil8=): the river pass blends first-fragment-wins
  (NotEqual 1 / Replace), so bends and confluence overlaps never
  double-blend.  Confluences still show a seam where strips meet — the
  junction-mesh item remains open — but no darkening.
- The standing-water grid is now RG32F: level plus a per-body wave
  amplitude from the lake census classification (sea 1.0, lake 0.10, pond
  0.04, puddle 0).  Only the ocean carries the full Gerstner swells, which
  removes the "waving sheet lifting off the shore" artifact on lakes and
  calms mountain tarns.

Seed-123 captures: rivers are translucent glass in incised channels with
clean waterlines; the cascade keeps its foam; the hanging tarn sits calm;
rider-spawn lakes lie flat and mirror-like against their shores.  The
rider capture reads 60 FPS (vsync-flat graph).  Not done here: rider
water-contact feedback when crossing channels, and the visible confluence
seam.

** 2026-07-11 Rivers fill their carved channels

The rendering pass that carving was for.  Ribbon cross-sections are now
level and ride at 0.75 of the shared =channel_depth_m= law above the carved
bed, so the water plane meets the stamped banks and the depth test cuts a
clean waterline; sides are no longer draped onto terrain, and each section's
normal is the water plane tilted by the downstream drop.  The river shader
was rewritten around two value-noise layers advected downstream at different
speeds: normal ripple from their gradients, churn foam gated by the rapid
signal, cascade foam on waterfall strength, a thin bank contact line, and
the same Fresnel-to-haze sky reflection the ocean uses (without it the
channel read as a black trench).  The ocean's foam breakup switched from a
plane-wave product (plaid moire, polka-dot surge rings) to drifting value
noise, computed only inside the shore band.  =moppe_value_noise= lives in
the shared shader header.

Two erosion corrections fell out of inspecting the results:

1. The carved bed now respects a backwater floor.  Beds are clamped above
   the surface level of the water body each path eventually enters
   (propagated upstream through the reach DAG), with only the final mouth
   step dipping under the surface.  Without this, channels crossing flat
   lowland dug below their lake's level kilometres early and priority-flood
   turned whole reaches into standing-water arms.
2. The naive AGE hookup tripled the standing-water census (1231 water
   bodies without it, 5539 with; the paper's warning about one-cell
   discontinuities at work).  A thermal pass interposed between the
   analytical stage and droplets, four fixed-point passes on every profile,
   and droplet budgets raised to 100k/300k/500k bring seed 123 at 1025
   square to 1734 bodies.  World generation logs a one-line standing-water
   census so pond explosions from future erosion changes show up at load.

One build-system trap cost this session an hour of false theories: bundled
shaders were only copied into moppe.app by a POST_BUILD step on the
executable, so shader-only edits silently tested the previous shader.  A
=moppe_bundle_shaders= target now refreshes the bundle on every build.
When a capture contradicts a shader edit, suspect staleness first.

Verification: seed-123 river, mouth, waterfall, and lake captures.  Rivers
sit visibly below grade with real banks; the waterfall candidate renders as
a bright coherent cascade from a hanging tarn; the mouth widens and fades
into its lake.  The rider capture reads 59 FPS at its new twin-lake spawn
against 98 on the previous terrain — suspected vsync/scene difference
rather than shader cost (the foam noise is shore-band-only), but it needs a
proper perf pass.  Lake shorelines keep their coarse-grid sawtooth and
checkerboard; that remains the paused fine-boundary-band project.

** 2026-07-11 The world program ages valleys and carves river channels

The random world now runs the finite-time analytical stream-power transform
and a new channel-carving stage.  The world program is source, power,
=AnalyticalErosion= (200 ky, two fixed-point passes on the fast profile and
four on play/research), droplets, thermal, and finally =ChannelCarving=.
Aging runs before droplets as the drainage-scale stage; carving runs last so
smoothing cannot refill the beds.

Carving is deterministic stamping, not simulation.  It recomputes the flood
field, wet drainage, and river network on the eroded terrain — the same
account the renderer consumes — then cuts a channel cross-section along each
reach centerline.  Bed depth follows catchment area (clamped 0.4-2.5 m,
scaled down for channels narrower than a cell), widths share the renderer's
area-to-width law, banks blend over six meters, and beds are propagated
monotone downstream through reach junctions (Kahn order over the reach DAG),
so every carved channel drains to its mouth by construction.  Reaches also
carve one receiver step into standing water so mouths pass under the lake
surface instead of ending in a wall.

Verification: unit tests cover trunk lowering, monotone beds, determinism,
never-raising, and torus stamping; the seed-123 water captures show incised
grooves under the ribbons and matured branched valleys, and the ordinary
rider capture holds 98 FPS.  Two fixed-point aging passes at 1025 square
cost about 1.5 s, so fast-profile captures remain quick.  Terrain caches
key on the executable hash and invalidated automatically.

Known limits, deliberately left for the rendering pass: ribbons still draw
their surface 0.06-0.10 m above the carved bed, so channels read as grooves
under translucent strips rather than filled watercourses; flow-aligned
surface detail, depth-based absorption, and foam keyed to the carved bed
are the natural next steps.  Lake shorelines are untouched by carving and
still need the planned fine boundary band.  Terrain Lab has no =+CARVE=
stage control yet; the pipeline demo accepts =carve= and
=carve=area_cells[,depth_scale,min_depth,max_depth,sea,blend]=.

** 2026-07-11 Shoreline rendering investigation paused

*** Current situation

The hydrology is supplying the right standing-water bodies and levels, but the
shared ocean/lake renderer is not yet presenting their boundaries convincingly.
Close =lake=, =mouth=, and =river= inspection shots show bright, sawtooth shore
edges and occasional triangular skirts where the water surface meets terrain.
The problem is especially visible around small islands, narrow inlets, and the
foreground edge of a lake. It is a rendering artifact, not evidence that the
lake census or body routing changed.

The current renderer draws one regular 300 by 300 water grid across an
11-kilometre square, so its vertices are about 36.7 metres apart. The hydrology
and terrain rasters are sampled at roughly 5-metre spacing. The vertex shader
therefore displaces a coarse triangle using much finer water-level data, while
the fragment shader reconstructs depth and discards dry fragments. Shallow
foam makes the resulting coarse/masked boundary particularly bright. This
scale mismatch is now the leading explanation for the visible skirts and
facets.

*** How it is being tested

Use the hydrology-targeted capture tool rather than the ordinary spawn camera:

#+begin_src sh
MOPPE_SEED=123 tools/capture-water /tmp/water-lake.png lake
MOPPE_SEED=123 tools/capture-water /tmp/water-mouth.png mouth
MOPPE_SEED=123 tools/capture-water /tmp/water-river.png river
MOPPE_SEED=123 tools/capture-water /tmp/water-fall.png waterfall
MOPPE_SEED=123 tools/capture-water /tmp/water-join.png confluence
MOPPE_SEED=123 tools/capture-game /tmp/water-ride.png
#+end_src

The feature shots hide vegetation, actors, and HUD, select a deterministic
hydrology cell, and print its cell, score, eye, and target. Compare images in
pairs from the same feature/seed; do not treat a normal rider shot that merely
has water in the distance as shoreline evidence. Run the ordinary rider shot
as the separate performance/regression check. The accepted 300-cell renderer
records about 115 FPS in that seed-123 capture.

*** Experiments rejected in this pass

1. The shader was changed to interpolate wet occupancy separately from surface
   elevation and to normalize elevation over wet corners only. This avoided
   mathematically mixing a real lake level with the dry-cell zero sentinel, but
   paired lake, mouth, and river captures were materially unchanged. The coarse
   geometry, rather than that interpolation alone, is the limiting factor. The
   shader change was reverted.
2. The global water grid was increased from 300 to 600 cells. Shore silhouettes
   became somewhat finer, but the same bright facets remained and the ordinary
   rider capture fell from 115 to 81 FPS. Four times the global triangle count
   is too expensive for an incomplete improvement, so this change was reverted.

*** A better next attempt

Keep the coarse grid for deep lake and ocean interiors, but stop asking it to
represent the shore. Build a separate fine boundary band from the permanent
water mask, probably with marching squares or an equivalent clipped contour at
terrain-cell resolution. Give that band stable body surface levels and a signed
shore-distance/coverage coordinate for wave suppression, transparency, and
foam. The coarse interior must be clipped back far enough that it does not
overlap and darken the boundary band. Test the extracted contour and periodic
seam deterministically on the CPU before adding backend geometry, then repeat
the exact fixed-camera comparisons above. A signed-distance texture without
finer boundary geometry may still be useful for material control, but the
failed interpolation experiment is evidence that it will not fix the shape by
itself.

Other visible water work remains separate: confluences still need a
non-overlapping strip union, and waterfall candidates still expose gaps or
steep terrain-following ribbons rather than a selected falling sheet. The
inspection cameras are doing their job by making these failures repeatable.

** 2026-07-11 Water features get deterministic inspection cameras

- Added =tools/capture-water OUTPUT FEATURE= and the corresponding
  =--water-screenshot FEATURE OUTPUT= mode for =river=, =confluence=, =mouth=,
  =waterfall=, and =lake=.
- Each shot deterministically scores the structured hydrology, reports its
  selected cell and score, frames it with a fixed inspection camera, and hides
  actors, vegetation, and HUD while retaining the final drawable composite.
- Added a D8-adjacency guard before extending inlet current through standing
  water. The first mouth capture exposed that a wet receiver may jump directly
  to a body outlet; treating it as local geometry drew a sheet across the lake.
- Added endpoint opacity to the river material so mouths dissolve into the
  standing surface and upstream reach ownership is reduced at confluences.
- Tested and rejected a blended confluence fan because overlap made a dark
  polygon. Exact endpoints remain, but a proper non-overlapping union is open.
- Seed 123 now has clean river, confluence, mouth, waterfall-candidate, and lake
  views. They expose remaining sawtooth shores, strip overlap, and the fact
  that a steep candidate is not yet a free fall; the ordinary rider capture
  returned to 115 FPS after removing the fan.

** 2026-07-11 River ribbons stop tracing cell-center corners

- Added two-sample cubic Hermite resampling per receiver edge, with horizontal
  tangents clamped to one edge length to prevent loops and overshoot.
- Resampled dry height and normals from the terrain; interpolated lake-entry
  height, width, discharge, rapid, and cascade signals along the same curve.
- Preserved exact reach endpoints so confluences and lake/ocean boundaries do
  not move away from the authoritative =RiverNetwork=.
- Rejected three samples per edge after a 59 FPS capture; two samples retained
  the visible rounding at 114 FPS versus the 115 FPS unsmoothed baseline.

** 2026-07-11 Steep river steps become inspectable cascade candidates

- Added deterministic =Waterfall= candidates derived from physical drop,
  slope, discharge threshold, and adjacency clustering on ordered reaches.
- Added FALLS markers, counts, and TRACE details in Terrain Lab.
- Fed the candidate signal into the existing river material as stronger foam
  without breaking terrain-following ribbon continuity.
- Seed 123 at 1025 square found 183 candidates across 346 source reaches and
  234 across 481 reaches after 30K droplets; one-time analysis took roughly
  262--306 ms and the ordinary rider capture remained near 115 FPS.
- Tested and rejected a free-falling quad prototype: without an actual carved
  lip or curved sheet it intersected the continuous heightfield and rendered
  as disconnected white blocks.  True waterfall geometry remains open work.

** 2026-07-11 Finite-time stream power becomes a pipeline stage

- Implemented the paper's =n=1= characteristic solution over routed river
  trees with physical age, uplift, erodibility, and drainage-area exponent.
- Used ocean cells as fixed boundaries and depression-aware routes for inland
  bodies; enforced the detachment-limited bound that terrain cannot rise
  faster than uplift.
- Added deterministic, seam, zero-age, uplift, and no-spurious-rise tests.
- Added =+AGE= controls and change ledgers to Terrain Lab and a six-mode
  fixed-seed comparison tool.
- Recorded that the global pass supplies strong dendritic structure but needs
  talus/droplet finishing to suppress fixed-graph discontinuities.

** 2026-07-11 Routed reaches become animated river surfaces

- Added a retained river-ribbon mesh and a flow-aligned Metal material shared
  by Terrain Lab and the random game.
- Made ribbon width a physical catchment reading and separated the visible
  channel cutoff from the denser analysis network.
- Fixed a large-world routing cycle by selecting a lake's final flood-tree
  departure after any dry-saddle re-entry; added a synthetic regression test.
- Verified fixed seed 123 from the motorcycle and added direct ribbon geometry
  tests for scale, widening, and finite vertices.

** 2026-07-11 Wet drainage crosses standing water

- Added a wet drainage interpretation over the priority-flood surface.
- Kept steepest D8 descent on dry slopes and used the acyclic spill forest to
  cross equal-height lake interiors.
- Switched Terrain Lab flow, stream, basin, and outlet readings to the wet
  graph while leaving erosion and geometry unchanged.

** 2026-07-11 Water bodies gain routing identity

- Chose the largest connected below-sea component as the torus's explicit
  global ocean and gave it one outlet tree.
- Replaced approximate boundary spill candidates with route-proven outlet and
  spill pairs, and forced each inland body to discharge through that pair.
- Added =WaterNetwork= inlet and outflow catchment ledgers and exposed body
  depth, inlet count, and catchment area through Terrain Lab tracing.

** 2026-07-11 Water routes become visible river reaches

- Extracted deterministic directed reaches above a physical drainage-area
  threshold, split at sources, confluences, lake inlets, and proven spills.
- Excluded standing-water and global-ocean cells so the visible stream layer
  never exposes the arbitrary bookkeeping routes across flat water.
- Switched Terrain Lab STREAMS to the reach value and added reach identity,
  discharge, slope, and destination to TRACE inspection.

** 2026-07-11 Documentation reorganization

- Separated speculative design essays into =ideas/=.
- Replaced the orientation and hydrology snapshots with this living ledger.
- Cross-checked the ledger against the terrain, drainage, flood, and game
  generation code and the July 10-11 commit sequence.

** 2026-07-11 Water becomes visible in play

- Added standing-water analysis, deterministic lake census, Terrain Lab
  overlays, and random-world lake rendering.
- Closed the hydraulic sediment ledger and recorded the droplet-lifetime
  experiment.
- Added and measured path-monotone carving; it reduces but does not eliminate
  erosion-created pits.

** 2026-07-10 Random worlds become programmable

- Introduced terrain expressions, recipes, pipelines, and =TerrainProgram=.
- Made the generated world periodic and removed special map boundaries.
- Added Terrain Lab editing, preview, capture, readings, and faster evaluation.

** 2026-07-09 Revival baseline

- Replaced the OpenGL-era platform and renderer with portable renderer APIs
  and a Metal backend.
- Brought the game to macOS and iOS while retaining city, Pico, and random
  terrain modes.

* Maintaining this file

Update this ledger when a change alters project state or priorities, not for
every commit.  Move completed active items into =What is implemented= and add
a short dated log entry.  Keep =Active work= small.  If an item has no clear
next experiment or acceptance evidence, it probably belongs under =Later= or
in an essay in =ideas/=.

### 10. Assistant tool calls

#### Tool call: `write_note`

```json
{
  "block_ids": [
    "DWXKYQ",
    "MTDKDE",
    "NV2YRW",
    "B6P8L4",
    "GY93FG"
  ],
  "text": "The Moppe code repository is synced into Sheaf as source files under document 3CV92Z. Orientation: Moppe is a C++ motorcycle game / generated-world laboratory. Key entry points: docs/engine-atlas.md (architecture map: WorldRecipe+TerrainProgram → GeneratedWorld → GameSession → FrameView → Renderer, Metal + WebGPU backends), docs/project.org (experiment ledger with acceptance evidence and working rules), docs/terrain-expressions.md (scalar-field DAG terrain language), ideas/ (second-author, tending-the-world, watersheds-of-execution, reading-map essays).\n\nDirect corpus links: the AnalyticalErosion transform implements the finite-time n=1 characteristic solution from Tzathas et al. (#DWXKYQ); standing water uses Priority-Flood (#MTDKDE); FastFlow (#NV2YRW) is named as a possible GPU routing backend; TrailFormation as a terrain transform connects to the active-walker trail papers (#B6P8L4, #GY93FG); the ideas/ essays on centers, routes, and settlements connect to the Alexander / living-structure folder. ideas/reading-map.md is the annotated ancestor of the Sheaf literature corpus.\n\nCurrent active work per the ledger: river rendering as continuous cubic alignments (ribbons), waterfall geometry, junction meshes, erosion coupled to lake infill, and making the random world a legible ride.",
  "title": "Moppe repository orientation (synced code)"
}
```

### 11. Tool result: write_note

NOTE SAVED #24KSST
IRI: https://m.sheaf.less.rest/24KSST

### 12. Assistant

In short: the repository seems healthy, thoughtfully bounded, and unusually literate — and it's tightly coupled to the literature you've collected here, which should make it easy to cite specific code artifacts (like the `AnalyticalErosion` transform or `TrailFormation`) as implementations of the papers when you write.