feat(biology): liquid-relative cellular kinematics and the Git tuning file
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (checks) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m24s
Foundation / postgres-tools (push) Successful in 27s
Foundation / server-image (push) Successful in 4m5s
Foundation / image (push) Successful in 4m17s

Phase 1 of the region and movement plan. Adds the shared integer motion step:
Q10 velocity relative to the liquid, a 16-bit heading with a rate-limited turn,
funded forward/reverse thrust (unfunded thrust coasts), braking, separate forward
and lateral drag that decays to exactly zero, local flow, and a sub-micrometre
carry with no rounding drift. A golden trajectory digest matches across g++-14,
clang-19 and MSVC, so the server and client predictor agree exactly.

Adds deploy/kubernetes/region/dev/tuning/cellular.tuning with every v0 trial value
and a strict parser (unknown, missing, duplicate, out-of-range and inconsistent
values are refused) plus founder handling derived from it. 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:30:51 -04:00
co-authored by Claude Opus 5.5
parent 816c83d68f
commit ab5df35c3f
9 changed files with 1242 additions and 2 deletions
@@ -0,0 +1,87 @@
#pragma once
#include "evo/accounting/ledger.hpp"
#include "evo/biology/cellular_motion.hpp"
#include <compare>
#include <cstdint>
#include <expected>
// Liquid-relative cellular motion (Cellular_movement_draft.md, numeric representation;
// Cellular_Region_Movement_Plan.md phase 1). Integer-only and shared by the region server
// and the client predictor, so both produce identical trajectories.
namespace evo::biology {
// Velocities are Q10: 1/1024 micrometre per second.
inline constexpr std::int64_t cellular_velocity_q10_per_um_s = 1'024;
// Relative or flow velocity components are bounded to +/- 1 m/s, so squared magnitudes fit
// comfortably in 64 bits.
inline constexpr std::int32_t cellular_velocity_limit_q10 = 1'000'000 * 1'024;
// Headings: 65,536 per turn, 0 along +x, counterclockwise.
inline constexpr std::uint32_t cellular_heading_turn = 65'536;
// Sine and cosine are Q14.
inline constexpr std::int32_t cellular_trig_one = 16'384;
// Drag rates are parts per million of velocity per tick, below one whole.
inline constexpr std::uint32_t cellular_drag_ppm_limit = 1'000'000;
// Per-cell motion state persisted with the organism.
struct CellularMotionState {
std::int32_t velocity_x_q10{}, velocity_y_q10{}; // Relative to the liquid.
std::uint16_t heading{};
// Sub-micrometre carry in 1/1024 micrometre-microseconds, below one micrometre.
std::int64_t remainder_x{}, remainder_y{};
auto operator<=>(const CellularMotionState&) const = default;
};
// Local liquid velocity at the cell, sampled by the caller from the region's flow field.
struct CellularFlowSample {
std::int32_t x_q10{}, y_q10{};
auto operator<=>(const CellularFlowSample&) const = default;
};
// An organism's handling, derived from its body; all amounts are per 50 ms tick.
struct CellularHandling {
std::uint32_t thrust_q10{}; // Velocity gained per tick at full forward throttle.
std::uint32_t reverse_thrust_q10{}; // Velocity gained per tick reversing or braking.
std::uint32_t forward_drag_ppm{}, lateral_drag_ppm{};
std::uint16_t turn{}; // Largest heading change per tick.
accounting::Picojoules thrust_cost{}, reverse_cost{}; // At full output for one tick.
auto operator<=>(const CellularHandling&) const = default;
};
// Player or controller command: a direction with throttle (the intent magnitude), or a brake.
// Braking opposes relative velocity and takes precedence over the direction.
struct CellularPropulsion {
CellularIntent direction;
bool brake{};
auto operator<=>(const CellularPropulsion&) const = default;
};
enum class CellularThrustStatus : std::uint8_t { idle, applied, unfunded };
struct CellularKinematicsResult {
CellularPosition position;
CellularMotionState state;
accounting::Picojoules cost{}; // Never more than the energy offered.
CellularThrustStatus thrust{CellularThrustStatus::idle};
std::uint64_t path_um{}; // Conservative straight-line distance travelled.
auto operator<=>(const CellularKinematicsResult&) const = default;
};
enum class CellularKinematicsError : std::uint8_t {
invalid_area,
invalid_extent,
outside_area,
invalid_intent,
invalid_state,
invalid_handling,
invalid_flow
};
[[nodiscard]] std::int32_t cellular_cos_q14(std::uint16_t heading) noexcept;
[[nodiscard]] std::int32_t cellular_sin_q14(std::uint16_t heading) noexcept;
// Integer atan2 (CORDIC); the zero vector returns 0.
[[nodiscard]] std::uint16_t cellular_heading_of(std::int64_t x, std::int64_t y) noexcept;
// One 50 ms tick: turn toward the commanded direction, apply thrust that `available_energy`
// can fund (otherwise none, and the cell coasts), apply drag toward exactly zero, add the
// local flow and carry the displacement. Region edges stop motion into them.
[[nodiscard]] std::expected<CellularKinematicsResult, CellularKinematicsError>
step_cellular_kinematics(CellularArea area, CellularPosition position, std::uint32_t extent_um,
const CellularMotionState& state, CellularPropulsion propulsion,
const CellularHandling& handling, CellularFlowSample flow,
accounting::Picojoules available_energy) noexcept;
} // namespace evo::biology
+81
View File
@@ -0,0 +1,81 @@
#pragma once
#include "evo/biology/cellular_kinematics.hpp"
#include <compare>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <string>
#include <string_view>
// Git-managed trial values (Cellular_Region_Movement_Plan.md, tuning file). The file is
// plain `key = value` lines with `#` comments and integer values; `_` may separate digits.
// Every key below is required exactly once and range-checked, so a typo fails loudly
// instead of running with a default.
namespace evo::biology {
inline constexpr std::int64_t cellular_tuning_version = 1;
inline constexpr std::size_t max_cellular_tuning_bytes = std::size_t{64} * 1'024;
struct CellularTuning {
std::int64_t version{};
// Region shape and capacity; shape applies when a region opens.
std::int64_t region_width_um{}, region_height_um{};
std::int64_t region_organism_cap{}, region_deposit_limit{}, region_perception_radius_um{};
// Founder handling.
std::int64_t founder_thrust_um_per_s2{}, founder_reverse_thrust_um_per_s2{};
std::int64_t founder_drag_ppm_per_tick{}, founder_lateral_drag_ppm_per_tick{};
std::int64_t founder_turn_heading_per_s{}; // 65,536 heading units per turn.
// Currents.
std::int64_t currents_min_count{}, currents_max_count{};
std::int64_t currents_min_width_um{}, currents_max_width_um{};
std::int64_t currents_min_speed_um_per_s{}, currents_max_speed_um_per_s{};
std::int64_t currents_grid_pitch_um{};
// Moving food.
std::int64_t food_merged_bubble_cap_multiple{}, food_visible_moving_bubbles{};
std::int64_t food_induced_drift_radius_um{}, food_induced_drift_max_um_per_s{};
std::int64_t food_induced_drift_decay_ppm_per_tick{};
// Thermal map and biology (temperatures in millikelvin).
std::int64_t thermal_ambient_min_mk{}, thermal_ambient_max_mk{};
std::int64_t founder_preferred_mk{}, founder_comfort_band_mk{}, founder_body_tau_ms{};
std::int64_t founder_lethal_cold_mk{}, founder_lethal_heat_mk{};
std::int64_t thermal_off_preference_per_mille_per_k{}, thermal_transition_per_mille_per_k{};
std::int64_t thermal_multiplier_cap_per_mille{};
// Lifecycle.
std::int64_t lifecycle_logout_delay_ms{};
// Mutation offers.
std::int64_t mutation_step_points{}, mutation_paired_points{};
std::int64_t mutation_recovery_floor_per_mille{};
std::int64_t mutation_offer_interval_ms{}, mutation_offer_options{};
auto operator<=>(const CellularTuning&) const = default;
};
enum class CellularTuningErrorKind : std::uint8_t {
too_large,
syntax,
unknown_key,
duplicate_key,
invalid_value,
out_of_range,
missing_key,
inconsistent,
unsupported_version
};
struct CellularTuningError {
CellularTuningErrorKind kind{};
std::size_t line{}; // 1-based; zero when not tied to a line.
std::string key;
auto operator<=>(const CellularTuningError&) const = default;
};
[[nodiscard]] std::expected<CellularTuning, CellularTuningError>
parse_cellular_tuning(std::string_view text);
// Canonical text: every key once, in schema order, so equal tunings encode identically.
[[nodiscard]] std::string encode_cellular_tuning(const CellularTuning& tuning);
[[nodiscard]] std::string_view describe(CellularTuningErrorKind kind) noexcept;
// Founder handling per 50 ms tick, rounded down; costs are supplied by the metabolic budget.
[[nodiscard]] CellularHandling founder_cellular_handling(const CellularTuning& tuning,
accounting::Picojoules thrust_cost,
accounting::Picojoules reverse_cost);
} // namespace evo::biology