Lodur/src/Lodur.Core/Perception.cs
Meta Vens f9e302ef96 Perception: Sense refuses a gain outside [0, 1]
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-20 06:54:42 +01:00

252 lines
12 KiB
C#

using System;
namespace Lodur
{
/// <summary>
/// A game stimulus: an axis-aligned box volume with an intensity the game writes every tick. Lodur reads
/// it and decides containment and transduction; the box is never a physics body.
/// </summary>
public struct BoxStimulus
{
public float CenterX, CenterY, CenterZ;
public float HalfX, HalfY, HalfZ;
/// <summary>Noxious intensity inside the box, written by the game each tick (0..1 in the slice's scale).</summary>
public double Intensity;
public BoxStimulus(float centerX, float centerY, float centerZ, float halfX, float halfY, float halfZ, double intensity = 0.0)
{
CenterX = centerX; CenterY = centerY; CenterZ = centerZ;
HalfX = halfX; HalfY = halfY; HalfZ = halfZ;
Intensity = intensity;
}
/// <summary>True when the point is inside the box or on one of its faces.</summary>
public bool Contains(float x, float y, float z) =>
MathF.Abs(x - CenterX) <= HalfX && MathF.Abs(y - CenterY) <= HalfY && MathF.Abs(z - CenterZ) <= HalfZ;
}
/// <summary>The sensory channels a point emitter can speak on. Each has its own stimulus, sensitisation and nerve.</summary>
public enum Channel
{
Audio = 0,
Visual = 1,
Interrupt = 2,
}
/// <summary>
/// A game stimulus at a point: sound, flicker, a notification. The game writes its position and intensity every
/// tick; Lodur decides what reaches the sense region. What arrives is the intensity falling off linearly to zero
/// at the radius.
/// </summary>
public struct Emitter
{
public Channel Channel;
public float X, Y, Z;
public float Radius;
public double Intensity;
public Emitter(Channel channel, float x, float y, float z, float radius, double intensity = 0.0)
{
Channel = channel;
X = x; Y = y; Z = z;
Radius = radius;
Intensity = intensity;
}
/// <summary>Intensity * max(0, 1 - distance / Radius) at the point; zero at and beyond the radius.</summary>
public double Received(float x, float y, float z)
{
double dx = x - X, dy = y - Y, dz = z - Z;
var distance = Math.Sqrt(dx * dx + dy * dy + dz * dz);
return Radius > 0f && distance < Radius ? Intensity * (1.0 - distance / Radius) : 0.0;
}
}
/// <summary>The nerve's tunables, the transduction of any channel, noxious or sensory: threshold, sensitisation under sustained stimulus, conduction delay, and a per-character gain.</summary>
public sealed record NerveParameters
{
public double Threshold { get; init; } = 0.1;
public double SensitisationGrowth { get; init; } = 0.04;
public double SensitisationRecovery { get; init; } = 0.02;
public double SensitisationCap { get; init; } = 2.0;
public double ConductionDelaySeconds { get; init; } = 0.06;
/// <summary>Per-character gain (the consumer draws its trait spread).</summary>
public double Gain { get; init; } = 1.0;
}
/// <summary>
/// Layer 1 for one character, a fixed number of body regions. Each tick it takes one point per region and the
/// game's stimulus sources and produces, per region, the stimulus there and the afferent signal after
/// threshold, sensitisation and conduction delay. With a sensory nerve it also senses point emitters at one
/// region on three channels and combines the channels into one load. Everything is allocated in the constructor.
/// </summary>
public sealed class Perception
{
private readonly NerveParameters _p;
private readonly double _dt;
private readonly int _regions;
private readonly int _slots;
private readonly double[] _ring; // afferent signal in flight along the nerve, region-major
private readonly double[] _sens;
private readonly double[] _stimulus;
private readonly double[] _afferent;
private readonly NerveParameters? _senses;
private readonly int _senseRegion;
private readonly int _senseSlots;
private readonly double[] _senseRing; // afferent in flight per channel, channel-major
private readonly double[] _senseSens = new double[ChannelCount];
private readonly double[] _senseStimulus = new double[ChannelCount];
private readonly double[] _senseAfferent = new double[ChannelCount];
private long _tick;
private const int ChannelCount = 3;
/// <param name="senses">The nerve of the sensory channels; null for a body with no senses (the load stays zero).</param>
/// <param name="senseRegion">The region whose point the emitters are sensed at.</param>
public Perception(NerveParameters parameters, double tickSeconds, int regionCount, NerveParameters? senses = null, int senseRegion = 0)
{
_p = parameters;
_dt = tickSeconds;
_regions = regionCount;
var delayTicks = (int)Math.Round(parameters.ConductionDelaySeconds / tickSeconds);
_slots = Math.Max(1, delayTicks);
_ring = new double[regionCount * _slots];
_sens = new double[regionCount];
Array.Fill(_sens, 1.0);
_stimulus = new double[regionCount];
_afferent = new double[regionCount];
_senses = senses;
_senseRegion = senseRegion;
if (senses != null)
{
if ((uint)senseRegion >= (uint)regionCount)
{
throw new ArgumentOutOfRangeException(nameof(senseRegion), $"The sense region must be one of {regionCount} regions.");
}
_senseSlots = Math.Max(1, (int)Math.Round(senses.ConductionDelaySeconds / tickSeconds));
_senseRing = new double[ChannelCount * _senseSlots];
Array.Fill(_senseSens, 1.0);
}
else
{
_senseRing = Array.Empty<double>();
}
}
public int RegionCount => _regions;
/// <summary>The stimulus at the region's point this tick: the largest intensity among the boxes containing it.</summary>
public double Stimulus(int region) => _stimulus[region];
/// <summary>The afferent signal arriving this tick: what the nerve took in a conduction delay ago.</summary>
public double Afferent(int region) => _afferent[region];
/// <summary>The sensory signals combined: 1 - the product over channels of (1 - afferent, capped at 1), the afferents being the gated ones (see <see cref="ChannelAfferent"/>). Zero with no senses or no emitters.</summary>
public double Load { get; private set; }
/// <summary>The largest intensity of the channel's emitters at the sense region's point this tick.</summary>
public double ChannelStimulus(Channel channel) => _senseStimulus[(int)channel];
/// <summary>
/// The channel's afferent arriving this tick, after threshold, sensitisation and conduction delay, times the sensory gain
/// <see cref="Sense"/> was given (lodur:ruling:stress-bar-shows-arousal-calm-silences). <see cref="ChannelStimulus"/> stays the world's.
/// </summary>
public double ChannelAfferent(Channel channel) => _senseAfferent[(int)channel];
/// <summary>
/// Senses once per physics step. The spans are the caller's, one point per region. The sensory gain (default 1, the identity) multiplies the sense
/// channels' afferents as they leave the conduction delay, so a change of gain reaches <see cref="Load"/> on the next call it is passed to; the nociceptive region
/// afferents are never gated. A gain outside [0, 1] (NaN and infinity included) is refused.
/// </summary>
public void Sense(ReadOnlySpan<float> x, ReadOnlySpan<float> y, ReadOnlySpan<float> z, ReadOnlySpan<BoxStimulus> sources,
ReadOnlySpan<Emitter> emitters = default, double sensoryGain = 1.0)
{
if (x.Length != _regions || y.Length != _regions || z.Length != _regions)
{
throw new ArgumentException($"x, y and z need {_regions} entries, one per region.");
}
if (!(sensoryGain >= 0.0 && sensoryGain <= 1.0))
{
throw new ArgumentException("The sensory gain must be in [0, 1].", nameof(sensoryGain));
}
if (_senses != null)
{
// Refused before any state steps, so a bad emitter leaves the tick unrun.
for (var i = 0; i < emitters.Length; i++)
{
if ((uint)emitters[i].Channel >= ChannelCount)
{
throw new ArgumentException($"Emitter {i} has channel {(int)emitters[i].Channel}; the channels are Audio, Visual and Interrupt.", nameof(emitters));
}
}
}
var slot = (int)(_tick % _slots);
for (var r = 0; r < _regions; r++)
{
var stimulus = 0.0;
for (var i = 0; i < sources.Length; i++)
{
if (sources[i].Intensity > stimulus && sources[i].Contains(x[r], y[r], z[r]))
{
stimulus = sources[i].Intensity;
}
}
// Nociceptor: threshold, then sensitisation, then conduction delay.
var above = Math.Max(0.0, stimulus - _p.Threshold);
var sens = _sens[r] + _dt * (_p.SensitisationGrowth * above - _p.SensitisationRecovery * (_sens[r] - 1.0));
sens = Math.Min(Math.Max(sens, 1.0), _p.SensitisationCap);
_sens[r] = sens;
var ring = r * _slots + slot;
_afferent[r] = _ring[ring]; // written one conduction delay ago
_ring[ring] = above * sens * _p.Gain;
_stimulus[r] = stimulus;
}
if (_senses != null)
{
SenseEmitters(x[_senseRegion], y[_senseRegion], z[_senseRegion], emitters, sensoryGain);
}
_tick++;
}
private void SenseEmitters(float x, float y, float z, ReadOnlySpan<Emitter> emitters, double gain)
{
var senses = _senses!;
var slot = (int)(_tick % _senseSlots);
Array.Clear(_senseStimulus, 0, ChannelCount);
for (var i = 0; i < emitters.Length; i++)
{
var c = (int)emitters[i].Channel;
var received = emitters[i].Received(x, y, z);
if (received > _senseStimulus[c])
{
_senseStimulus[c] = received;
}
}
var quiet = 1.0;
for (var c = 0; c < ChannelCount; c++)
{
var above = Math.Max(0.0, _senseStimulus[c] - senses.Threshold);
var sens = _senseSens[c] + _dt * (senses.SensitisationGrowth * above - senses.SensitisationRecovery * (_senseSens[c] - 1.0));
sens = Math.Min(Math.Max(sens, 1.0), senses.SensitisationCap);
_senseSens[c] = sens;
var ring = c * _senseSlots + slot;
// Written one conduction delay ago; the gate sits after the ring, so sensitisation still follows the world.
_senseAfferent[c] = _senseRing[ring] * gain;
_senseRing[ring] = above * sens * senses.Gain;
quiet *= 1.0 - Math.Min(1.0, _senseAfferent[c]);
}
Load = 1.0 - quiet;
}
}
}