Files
aevolution/include/evo/biology/cellular_kinematics.hpp
T
dingoandClaude Opus 5.5 ab5df35c3f
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
feat(biology): liquid-relative cellular kinematics and the Git tuning file
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>
2026-10-21 16:30:51 -04:00

88 lines
4.2 KiB
C++

#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