Implement M9.5 biology-derived organism rendering and inspector

Add OrganismPresentation cells derived via biology::derive_phenotype with
no controller, owner or level fields (pinned by test), so identical
biology renders identically for players and NPCs. OrganismLayer reuses
the ADR-0080 ordering/freshness semantics; death is a remnant state and
removal is absence. Rendering takes an explicit rectangle budget, falls
back to body-only detail and marks truncation instead of dropping data.
An opt-in rectangle-only hover inspector shows phenotype gauges; ImGui is
not adopted. ADR-0081 records the decision; evidence in VALIDATION.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-01 18:21:53 -04:00
co-authored by Claude Opus 5.5
parent feca07f791
commit 9bb147de82
21 changed files with 1169 additions and 33 deletions
+32
View File
@@ -0,0 +1,32 @@
#pragma once
#include "evo/client/camera.hpp"
#include "evo/client/organism_view.hpp"
#include "evo/render/frame.hpp"
#include <array>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <optional>
#include <vector>
namespace evo::client {
// Engineering debug view only: hover highlight plus a panel of normalized phenotype
// gauges. It reads biology values and nothing else; there is no ownership,
// controller or level information to show. Not final player UI.
inline constexpr std::size_t inspector_gauges = 10;
inline constexpr std::size_t inspector_rectangles = 4 + 1 + 2 * inspector_gauges;
// Gauge order: extent, total mass, membrane share, maintenance, movement speed,
// ingestion rate, conversion, realized growth, damage, thermal shortfall.
// Each is in [0, 1]; log scales are documented in ORGANISM_RENDERING.md.
[[nodiscard]] std::array<double, inspector_gauges>
inspector_gauge_values(const OrganismCell& cell) noexcept;
// Index of the topmost (last drawn) organism whose drawn body contains `pointer`.
[[nodiscard]] std::optional<std::size_t> pick_organism(const OrganismPresentation& presentation,
const Camera& camera,
ScreenPoint pointer) noexcept;
enum class InspectorError : std::uint8_t { invalid_budget };
// Appends exactly-bounded rectangles (at most inspector_rectangles, clipped).
[[nodiscard]] std::expected<void, InspectorError>
append_inspector(std::vector<render::Rectangle>& out, std::size_t budget, const OrganismCell& cell,
const Camera& camera);
} // namespace evo::client
+81
View File
@@ -0,0 +1,81 @@
#pragma once
#include "evo/biology/development.hpp"
#include "evo/client/environment_view.hpp"
#include <cstddef>
#include <cstdint>
#include <expected>
#include <optional>
#include <span>
#include <vector>
namespace evo::client {
inline constexpr std::size_t max_organism_cells = 1024;
// Authority revision an organism presentation was copied from (e.g. a community
// command watermark). Not a capability or session grant.
struct OrganismRevision {
world::WorldIdentity identity;
std::uint64_t tick{}, revision{};
auto operator<=>(const OrganismRevision&) const = default;
};
// Dead organisms remain as remnants until their terminal inventory is gone; removal
// is absence from a later presentation, never a state.
enum class OrganismState : std::uint8_t { alive, dead };
// Copied presentation values. Deliberately has no controller, owner, account,
// player/NPC, level or name field: every organism is presented by biology alone.
struct OrganismCell {
std::uint64_t id{}; // Opaque stable draw-order key; never displayed.
world::VoxelAddress voxel;
world::Micrometres x, y; // Centre offset inside the voxel, each in [0, 1e6).
biology::Phenotype phenotype;
biology::GrowthState growth;
OrganismState state{OrganismState::alive};
};
// Immutable owned copy of up to 1024 organisms in one Z slice; may be empty.
class OrganismPresentation {
public:
[[nodiscard]] static std::expected<OrganismPresentation, ViewError>
create(OrganismRevision revision, std::int64_t slice_z, std::span<const OrganismCell> cells);
[[nodiscard]] OrganismRevision revision() const noexcept {
return revision_;
}
[[nodiscard]] std::int64_t slice_z() const noexcept {
return slice_z_;
}
// Strictly ascending by id, which is also draw order.
[[nodiscard]] std::span<const OrganismCell> cells() const noexcept {
return cells_;
}
private:
OrganismPresentation(OrganismRevision revision, std::int64_t z,
std::span<const OrganismCell> cells)
: revision_{revision}, slice_z_{z}, cells_(cells.begin(), cells.end()) {}
OrganismRevision revision_;
std::int64_t slice_z_;
std::vector<OrganismCell> cells_;
};
// Derives the phenotype with the M3 contract; visual parameters never come from
// anything but the genome, growth state and environment supplied here.
[[nodiscard]] std::expected<OrganismCell, ViewError>
present_organism(std::uint64_t id, world::VoxelAddress voxel, world::Micrometres x,
world::Micrometres y, const biology::Genome& genome, biology::GrowthState growth,
const biology::EnvironmentState& environment, OrganismState state);
// Same ordering/freshness semantics as EnvironmentLayer (ADR-0080), without chunks.
class OrganismLayer {
public:
[[nodiscard]] std::expected<void, ViewError> accept(OrganismPresentation next);
[[nodiscard]] std::expected<void, ViewError> observe(OrganismRevision latest);
void mark_stale() noexcept;
void reset() noexcept;
[[nodiscard]] const OrganismPresentation* current() const noexcept {
return current_ ? &*current_ : nullptr;
}
[[nodiscard]] Freshness freshness() const noexcept;
private:
std::optional<OrganismPresentation> current_;
std::optional<OrganismRevision> latest_;
bool stale_{};
};
} // namespace evo::client
+50
View File
@@ -0,0 +1,50 @@
#pragma once
#include "evo/client/camera.hpp"
#include "evo/client/organism_view.hpp"
#include "evo/render/frame.hpp"
#include <cstddef>
#include <cstdint>
#include <expected>
#include <vector>
namespace evo::render {
// Full detail: motility ring (4), body (1), membrane (4), ingestion mark (1). Bodies
// smaller than organism_detail_side draw as a dark halo plus body (2).
inline constexpr std::size_t organism_detail_rectangles = 10;
// Freshness chip plus an explicit truncation marker.
inline constexpr std::size_t organism_status_rectangles = 2;
// Uniform minimum on-screen body side (logical units) so micrometre organisms stay
// visible when zoomed out. Below it, drawn sizes are not comparable; inspect values.
inline constexpr double organism_visibility_floor = 5;
inline constexpr double organism_detail_side = 6;
namespace organism_palette {
inline constexpr Color ring{200, 230, 240, 255};
inline constexpr Color mouth{20, 16, 24, 255};
inline constexpr Color halo{8, 8, 12, 255}; // Contrast backing for collapsed bodies.
inline constexpr Color remnant{110, 95, 80, 255};
inline constexpr Color truncated{255, 0, 200, 255};
} // namespace organism_palette
struct ScreenBox {
double left{}, top{}, right{}, bottom{};
};
// Unclipped body box in logical window units, after the visibility floor. Shared by
// rendering and picking so both agree on what is under the pointer.
[[nodiscard]] ScreenBox organism_bounds(const client::OrganismCell& cell,
const client::Camera& camera) noexcept;
// Body colour from conversion, realized growth, damage and alive/dead state only.
[[nodiscard]] Color organism_fill(const client::OrganismCell& cell) noexcept;
enum class OrganismDetail : std::uint8_t { full, body_only };
struct OrganismRenderReport {
std::size_t visible{}, drawn{};
OrganismDetail detail{OrganismDetail::full};
};
enum class OrganismRenderError : std::uint8_t { invalid_budget };
// Appends at most `budget` rectangles (>= organism_status_rectangles) in id order.
// Detail is chosen once per call: full when every visible organism fits at full
// detail, otherwise one body rectangle each (no halo); organisms beyond the budget are not
// drawn and the magenta truncation marker appears. Nothing is dropped silently.
[[nodiscard]] std::expected<OrganismRenderReport, OrganismRenderError>
append_organisms(std::vector<Rectangle>& out, std::size_t budget,
const client::OrganismPresentation* presentation, client::Freshness freshness,
const client::Camera& camera);
} // namespace evo::render