feat(biology): procedural currents, habitat format 3 and moving food

Phase 2 biology. CellularFlowField generates 2-n seeded closed looping currents
inside the region, each with its own width, speed and direction, strongest at the
centreline and still at the stream edges and walls, rasterized to a Q10 grid with
integer bilinear sampling. The field digest matches across g++-14, clang-19 and
MSVC, so clients regenerate it from the configuration.

Habitat format 3 adds per-deposit induced drift, sub-micrometre carry and a merged
count, with up to 8,192 deposits. advect_cellular_deposits moves bubbles with the
flow plus drift from passing cells (falloff and decay), merges touching bubbles
into the lower id up to the merged cap, keeps pools fixed and addresses unique.
A 2,000-tick run of 1,800 bubbles conserves stock exactly and leaves nothing piled
at the walls; it costs under 0.7 ms per tick optimized. The tuned grid pitch is
capped at 10 mm. Refreshes the DEV session window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-21 16:50:45 -04:00
co-authored by Claude Opus 5.5
parent 2bffbc2095
commit 40dc2b12ad
11 changed files with 1107 additions and 12 deletions
+77
View File
@@ -0,0 +1,77 @@
#pragma once
#include "evo/biology/cellular_kinematics.hpp"
#include <compare>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <span>
#include <vector>
// Procedural currents (Cellular_Region_Changes.md, flows; ADR-0177): a fixed environmental
// condition, not stock. A seeded configuration generates 2-n closed looping routes inside the
// region, each with its own width, speed and direction, rasterized once into a Q10 velocity
// grid. Integer-only, so the client regenerates the identical field from the same
// configuration.
namespace evo::biology {
inline constexpr std::uint32_t max_cellular_current_pitch_um = 10'000;
inline constexpr std::size_t max_cellular_current_nodes = 1'048'576;
inline constexpr std::size_t cellular_current_route_points = 32;
struct CellularCurrentConfig {
std::uint64_t seed{};
std::uint32_t width_um{}, height_um{}, pitch_um{};
std::uint32_t min_count{}, max_count{};
std::uint32_t min_route_width_um{}, max_route_width_um{};
std::uint32_t min_speed_um_per_s{}, max_speed_um_per_s{};
auto operator<=>(const CellularCurrentConfig&) const = default;
};
struct CellularRoutePoint {
std::int64_t x_um{}, y_um{};
auto operator<=>(const CellularRoutePoint&) const = default;
};
// A closed loop; points are in flow order (the last joins the first).
struct CellularCurrentRoute {
std::vector<CellularRoutePoint> points;
std::uint32_t width_um{}, speed_um_per_s{};
bool clockwise{};
auto operator<=>(const CellularCurrentRoute&) const = default;
};
enum class CellularCurrentError : std::uint8_t { invalid_config, region_too_small };
class CellularFlowField {
public:
[[nodiscard]] static std::expected<CellularFlowField, CellularCurrentError>
generate(const CellularCurrentConfig& config);
// Liquid velocity at a point, clamped into the region; bilinear between grid nodes.
[[nodiscard]] CellularFlowSample sample(std::int64_t x_um, std::int64_t y_um) const noexcept;
// At the centre of a square footprint whose lower-left corner is `position`.
[[nodiscard]] CellularFlowSample at_footprint(CellularPosition position,
std::uint32_t extent_um) const noexcept;
[[nodiscard]] const CellularCurrentConfig& config() const noexcept {
return config_;
}
[[nodiscard]] std::span<const CellularCurrentRoute> routes() const noexcept {
return routes_;
}
[[nodiscard]] std::span<const CellularFlowSample> nodes() const noexcept {
return nodes_;
}
[[nodiscard]] std::size_t columns() const noexcept {
return columns_;
}
[[nodiscard]] std::size_t rows() const noexcept {
return rows_;
}
// Fingerprint of the generated grid, for comparing server and client fields.
[[nodiscard]] std::uint64_t digest() const noexcept;
private:
CellularFlowField() = default;
CellularCurrentConfig config_{};
std::vector<CellularCurrentRoute> routes_;
std::vector<CellularFlowSample> nodes_;
std::size_t columns_{}, rows_{};
};
} // namespace evo::biology
@@ -0,0 +1,50 @@
#pragma once
#include "evo/biology/cellular_currents.hpp"
#include "evo/biology/cellular_habitat.hpp"
#include <compare>
#include <cstdint>
#include <expected>
#include <span>
// Moving food (Cellular_Region_Movement_Plan.md, moving food; rules 12). After each tick's
// lives have fed against the deposits where they were, every bubble moves with the local flow
// plus the drift that passing cells induced, bubbles that touch merge (stock is summed, never
// created), and addresses are made unique again. Pools stay where they were placed.
namespace evo::biology {
// A living cell's world velocity this tick, for the drift it induces on nearby bubbles.
struct CellularWake {
CellularPosition position;
std::uint32_t extent_um{};
std::int32_t velocity_x_q10{}, velocity_y_q10{};
auto operator<=>(const CellularWake&) const = default;
};
struct CellularDepositMotionRules {
std::uint32_t drift_radius_um{}; // Cells push bubbles closer than this.
std::int32_t max_drift_q10{}; // Largest induced drift speed.
std::uint32_t drift_decay_ppm{}; // Induced drift lost per tick.
std::uint16_t merged_cap{}; // Bubbles stop merging at this many scattered ones.
std::uint32_t bubble_radius_um{}; // Radius of one unmerged bubble.
auto operator<=>(const CellularDepositMotionRules&) const = default;
};
struct CellularDepositMotionReport {
std::uint32_t moved{}, merges{}, nudged{};
auto operator<=>(const CellularDepositMotionReport&) const = default;
};
struct CellularDepositMotion {
CellularHabitatConfig config;
CellularDepositMotionReport report;
};
// Radius of a bubble holding `merged` scattered bubbles: area grows with the count.
[[nodiscard]] std::uint32_t cellular_merged_radius(std::uint32_t bubble_radius_um,
std::uint16_t merged) noexcept;
// Detached: returns the next format-3 configuration, or an error when the input is not a
// format-3 habitat matching the field's area. `wakes` must be ordered by stable life id.
[[nodiscard]] std::expected<CellularDepositMotion, CellularHabitatError>
advect_cellular_deposits(const CellularHabitatConfig& config, const CellularFlowField& field,
std::span<const CellularWake> wakes,
const CellularDepositMotionRules& rules);
} // namespace evo::biology
+14 -1
View File
@@ -21,11 +21,19 @@ inline constexpr std::uint32_t cellular_habitat_format = 1;
// ADR-0136 step A: format 2 holds deposits (pools and bubbles) at free micrometre centres,
// each with a stable id, a radius and a kind, and the next id to give a new deposit.
inline constexpr std::uint32_t cellular_habitat_deposit_format = 2;
// Format 3 (rules 12, Cellular_Region_Movement_Plan.md): format 2 deposits that move. Each
// record adds the deposit's induced drift, its sub-micrometre carry and how many scattered
// bubbles merged into it. Addresses stay unique: they change between ticks, never within one.
inline constexpr std::uint32_t cellular_habitat_liquid_format = 3;
inline constexpr std::size_t max_cellular_liquid_deposits = 8'192;
inline constexpr std::size_t cellular_habitat_header_bytes = 72;
inline constexpr std::size_t cellular_patch_record_bytes = 56;
inline constexpr std::size_t cellular_deposit_record_bytes = 64;
inline constexpr std::size_t cellular_liquid_record_bytes = cellular_deposit_record_bytes + 20;
inline constexpr std::size_t max_cellular_habitat_bytes =
cellular_habitat_header_bytes + cellular_deposit_record_bytes * max_cellular_patches + 8;
cellular_habitat_header_bytes + cellular_liquid_record_bytes * max_cellular_liquid_deposits + 8;
// Carry below one micrometre, in Q10 velocity-microseconds (as CellularMotionState).
inline constexpr std::uint32_t cellular_deposit_carry_limit = 1'024U * 1'000'000U;
// A bubble's contact radius (tunable); pools carry their own.
inline constexpr std::uint32_t cellular_mote_radius_um = 30;
inline constexpr std::uint32_t max_cellular_deposit_radius_um = 5'000;
@@ -45,6 +53,11 @@ struct CellularPatch {
accounting::Inventory stock{};
std::uint32_t id{}, radius_um{};
CellularDepositKind kind{};
// Format 3 only (zero otherwise): drift induced by passing cells (Q10 velocity), the
// sub-micrometre carry, and the scattered bubbles merged into this one (1 when unmerged).
std::int32_t drift_x_q10{}, drift_y_q10{};
std::uint32_t carry_x{}, carry_y{};
std::uint16_t merged{};
auto operator<=>(const CellularPatch&) const = default;
};
struct CellularHabitatConfig {