Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ add_library(DriftEngine STATIC
Source/Engine/EngineCommandQueue.h
Source/Engine/SpatialWorld.cpp
Source/Engine/SpatialWorld.h
Source/Engine/SpeedActivityMapping.cpp
Source/Engine/SpeedActivityMapping.h
Source/Engine/TransportEngine.cpp
Source/Engine/TransportEngine.h
Source/Music/MidiSink.cpp
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,8 @@ Every collision pair has one explicit target:

New contacts are resolved in the table's stable pair order. If simultaneous contacts target the same phrase, the first accepted request wins and that phrase keeps one unambiguous pending transition until the next eligible bar.

Phrase speed also selects authored material. Native velocity magnitude is normalized against the maximum throw speed and smoothed with a deterministic 250 ms filter. Each phrase begins normal (`A`), slows into sparse (`C`), or accelerates into active (`B`). Hysteresis keeps the bands stable: normal enters sparse at `0.015` and sparse returns at `0.040`; normal enters active at `0.450` and active returns at `0.300`. Band changes take effect at the next eligible bar. Speed observation pauses during Freeze Motion and direct dragging, while audio playback continues. A collision targeting the same phrase and bar replaces a pending speed change.

## Architecture

Drift is designed as a native **JUCE** desktop application with an embedded **React** interface. **PixiJS** is the initial renderer for the spatial world.
Expand Down Expand Up @@ -98,7 +100,7 @@ Drift is in the design and initial implementation phase. The first development b
5. [Prove transport stability under simulated UI stress](https://github.com/datashaman/drift/issues/5)
6. [Validate ten-minute playback through a real MIDI device](https://github.com/datashaman/drift/issues/6)

The native shell now connects React Play, Stop, Freeze Motion, BPM, MIDI-output, and direct phrase-drag controls to a native-owned monotonic transport and a four-role composition: drums, bass, chords, and melody. Stop freezes both playback and movement; Freeze Motion pauses only autonomous movement so phrases can be caught and repositioned while MIDI continues uninterrupted. Untouched phrases retain their velocity for resume, while a phrase manipulated during the freeze is released stationary. Drift schedules every phrase from the same transport to its assigned MIDI channel and advances the phrase bodies in a bounded normalized world at a fixed 120 Hz. Validated pointer intent crosses a bounded, coalescing command queue; PixiJS follows the pointer optimistically and reconciles to latest-state native snapshots at 30 Hz. A bounded recent pointer sample window gives each release a native-owned throw velocity, while stationary releases settle and edge or corner throws reflect inside the field. Every phrase now has three compatible authored variants, and every unique phrase collision queues a deterministic target phrase advance exactly once at the next eligible unscheduled bar. Physics and input pressure remain independent of musical time, and the interface exposes motion state, every phrase's current/pending variant, all pair mappings, contacts, cooldowns, transition counts, timing, catch-up, queue, coalescing, rejection, and snapshot diagnostics.
The native shell now connects React Play, Stop, Freeze Motion, BPM, MIDI-output, and direct phrase-drag controls to a native-owned monotonic transport and a four-role composition: drums, bass, chords, and melody. Stop freezes both playback and movement; Freeze Motion pauses only autonomous movement so phrases can be caught and repositioned while MIDI continues uninterrupted. Untouched phrases retain their velocity for resume, while a phrase manipulated during the freeze is released stationary. Drift schedules every phrase from the same transport to its assigned MIDI channel and advances the phrase bodies in a bounded normalized world at a fixed 120 Hz. Validated pointer intent crosses a bounded, coalescing command queue; PixiJS follows the pointer optimistically and reconciles to latest-state native snapshots at 30 Hz. A bounded recent pointer sample window gives each release a native-owned throw velocity, while stationary releases settle and edge or corner throws reflect inside the field. Every phrase now has three compatible authored variants. Both unique phrase collisions and stable speed-band crossings queue deterministic changes at the next eligible unscheduled bar, with collisions taking priority at a shared boundary. Physics and input pressure remain independent of musical time, and the interface exposes motion state, raw and smoothed phrase speed, stable and pending activity bands, current/pending variants, pair mappings, transition counts, timing, catch-up, queue, coalescing, rejection, and snapshot diagnostics.

The native/UI bridge uses a validated protocol-versioned envelope. Invalid commands produce structured rejection events without mutating engine state, and every React load performs a fresh handshake that restores the current authoritative transport state without restarting playback.

Expand Down
26 changes: 26 additions & 0 deletions Source/App/MainComponent.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,14 @@ void MainComponent::publishState()
"collisionTransitionAppliedCount",
static_cast<juce::int64> (
state.transport.diagnostics.collisionTransitionAppliedCount));
diagnostics->setProperty ("speedBandChangeCount", static_cast<juce::int64> (
state.transport.diagnostics.speedBandChangeCount));
diagnostics->setProperty ("speedIntentQueuedCount", static_cast<juce::int64> (
state.transport.diagnostics.speedIntentQueuedCount));
diagnostics->setProperty ("speedIntentSuppressedCount", static_cast<juce::int64> (
state.transport.diagnostics.speedIntentSuppressedCount));
diagnostics->setProperty ("speedTransitionAppliedCount", static_cast<juce::int64> (
state.transport.diagnostics.speedTransitionAppliedCount));
diagnostics->setProperty (
"commandQueueDepth", static_cast<juce::int64> (state.commandQueue.queueDepth));
diagnostics->setProperty (
Expand Down Expand Up @@ -304,6 +312,16 @@ void MainComponent::publishWorldSnapshot (const drift::engine::ControllerSnapsho
phrase.pendingVariantApplyBeat
? juce::var { *phrase.pendingVariantApplyBeat }
: juce::var {});
phraseObject->setProperty ("rawNormalizedSpeed", phrase.rawNormalizedSpeed);
phraseObject->setProperty (
"smoothedNormalizedSpeed", phrase.smoothedNormalizedSpeed);
phraseObject->setProperty (
"activityBand", drift::engine::activityBandName (phrase.activityBand));
phraseObject->setProperty (
"pendingActivityBand",
phrase.pendingActivityBand
? juce::var { drift::engine::activityBandName (*phrase.pendingActivityBand) }
: juce::var {});
phraseObject->setProperty ("midiChannel", phrase.midiChannel);
phraseObject->setProperty ("playing", phrase.playing);

Expand Down Expand Up @@ -361,6 +379,14 @@ void MainComponent::publishWorldSnapshot (const drift::engine::ControllerSnapsho
"collisionTransitionAppliedCount",
static_cast<juce::int64> (
state.transport.diagnostics.collisionTransitionAppliedCount));
diagnostics->setProperty ("speedBandChangeCount", static_cast<juce::int64> (
state.transport.diagnostics.speedBandChangeCount));
diagnostics->setProperty ("speedIntentQueuedCount", static_cast<juce::int64> (
state.transport.diagnostics.speedIntentQueuedCount));
diagnostics->setProperty ("speedIntentSuppressedCount", static_cast<juce::int64> (
state.transport.diagnostics.speedIntentSuppressedCount));
diagnostics->setProperty ("speedTransitionAppliedCount", static_cast<juce::int64> (
state.transport.diagnostics.speedTransitionAppliedCount));
diagnostics->setProperty (
"droppedSnapshotCount", static_cast<juce::int64> (droppedWorldSnapshotCount));
diagnostics->setProperty (
Expand Down
89 changes: 89 additions & 0 deletions Source/Engine/SpeedActivityMapping.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
#include "Engine/SpeedActivityMapping.h"

#include "Engine/SpatialWorld.h"

#include <algorithm>
#include <cmath>

namespace drift::engine
{
const char* activityBandName (ActivityBand band) noexcept
{
switch (band)
{
case ActivityBand::sparse: return "sparse";
case ActivityBand::normal: return "normal";
case ActivityBand::active: return "active";
}

return "normal";
}

const char* variantIdForActivityBand (ActivityBand band) noexcept
{
switch (band)
{
case ActivityBand::sparse: return "C";
case ActivityBand::normal: return "A";
case ActivityBand::active: return "B";
}

return "A";
}

ActivityBand activityBandAfterObservation (ActivityBand current,
double speed) noexcept
{
speed = std::clamp (speed, 0.0, 1.0);
switch (current)
{
case ActivityBand::sparse:
return speed >= SpeedActivityTracker::sparseToNormalThreshold
? ActivityBand::normal : current;
case ActivityBand::normal:
if (speed <= SpeedActivityTracker::normalToSparseThreshold)
return ActivityBand::sparse;
if (speed >= SpeedActivityTracker::normalToActiveThreshold)
return ActivityBand::active;
return current;
case ActivityBand::active:
return speed <= SpeedActivityTracker::activeToNormalThreshold
? ActivityBand::normal : current;
}
return ActivityBand::normal;
}

std::optional<ActivityBand> SpeedActivityTracker::observe (
double normalizedSpeed,
std::size_t fixedStepCount,
bool suspended)
{
rawSpeed = std::clamp (normalizedSpeed, 0.0, 1.0);

if (! initialized)
{
smoothedSpeed = rawSpeed;
initialized = true;
}

if (suspended || fixedStepCount == 0)
return std::nullopt;

const auto alpha = 1.0 - std::exp (
-SpatialWorld::fixedStepSeconds / smoothingTimeConstantSeconds);
for (std::size_t step = 0; step < fixedStepCount; ++step)
smoothedSpeed += alpha * (rawSpeed - smoothedSpeed);

const auto nextBand = activityBandAfterObservation (band, smoothedSpeed);

if (nextBand == band)
return std::nullopt;

band = nextBand;
return band;
}

double SpeedActivityTracker::rawNormalizedSpeed() const noexcept { return rawSpeed; }
double SpeedActivityTracker::smoothedNormalizedSpeed() const noexcept { return smoothedSpeed; }
ActivityBand SpeedActivityTracker::stableBand() const noexcept { return band; }
} // namespace drift::engine
44 changes: 44 additions & 0 deletions Source/Engine/SpeedActivityMapping.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
#pragma once

#include <cstddef>
#include <optional>
#include <string>

namespace drift::engine
{
enum class ActivityBand
{
sparse,
normal,
active,
};

const char* activityBandName (ActivityBand band) noexcept;
const char* variantIdForActivityBand (ActivityBand band) noexcept;
ActivityBand activityBandAfterObservation (ActivityBand current,
double smoothedNormalizedSpeed) noexcept;

class SpeedActivityTracker
{
public:
static constexpr double smoothingTimeConstantSeconds = 0.250;
static constexpr double normalToSparseThreshold = 0.015;
static constexpr double sparseToNormalThreshold = 0.040;
static constexpr double normalToActiveThreshold = 0.450;
static constexpr double activeToNormalThreshold = 0.300;

std::optional<ActivityBand> observe (double normalizedSpeed,
std::size_t fixedStepCount,
bool suspended);

double rawNormalizedSpeed() const noexcept;
double smoothedNormalizedSpeed() const noexcept;
ActivityBand stableBand() const noexcept;

private:
double rawSpeed = 0.0;
double smoothedSpeed = 0.0;
ActivityBand band = ActivityBand::normal;
bool initialized = false;
};
} // namespace drift::engine
89 changes: 85 additions & 4 deletions Source/Engine/TransportEngine.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,18 @@ TransportEngine::TransportEngine (Clock& clockIn, music::MidiSink& sinkIn)
world (makePhraseBodies (phrases), clockIn.nowSeconds())
{
world.setMotionPaused (true);
const auto& bodies = world.bodies();
for (std::size_t index = 0; index < phrases.size(); ++index)
{
const auto& phrase = phrases[index];
speedTrackers.emplace (phrase.id, SpeedActivityTracker {});
pendingSpeedBands.emplace (phrase.id, std::nullopt);
const auto& velocity = bodies[index].velocity;
speedTrackers.at (phrase.id).observe (
std::hypot (velocity.x, velocity.y) / SpatialWorld::maximumThrowSpeed,
0,
true);
}
}

void TransportEngine::play()
Expand All @@ -88,6 +100,7 @@ void TransportEngine::stop()
{
phrase.pendingVariantId.reset();
phrase.pendingVariantApplyBeat.reset();
pendingSpeedBands[phrase.id].reset();
}
}

Expand Down Expand Up @@ -130,8 +143,12 @@ void TransportEngine::recordBridgeReconnect()
void TransportEngine::tick()
{
world.advanceTo (clock.nowSeconds());
const auto physicsStepCount = world.diagnostics().physicsStepCount;
const auto fixedSteps = physicsStepCount - observedPhysicsStepCount;
observedPhysicsStepCount = physicsStepCount;
const auto state = transport.snapshot();
processCollisionContacts (state.beatPosition);
processSpeedActivity (state.beatPosition, fixedSteps);
applyDueIntents (state.beatPosition);

if (! state.playing)
Expand Down Expand Up @@ -177,8 +194,8 @@ void TransportEngine::processCollisionContacts (double currentBeat)
continue;

++diagnostics.collisionContactBeginCount;
const auto* target = findPhrase (rule->targetPhraseId);
if (target == nullptr || target->pendingVariantId)
auto* target = findPhrase (rule->targetPhraseId);
if (target == nullptr)
continue;

const auto variantId = nextVariantId (*target);
Expand All @@ -193,11 +210,63 @@ void TransportEngine::processCollisionContacts (double currentBeat)
*variantId,
music::quantizeForward (earliestUnscheduledBeat, barLengthBeats),
};
if (queueIntent (intent))
auto& pendingSpeedBand = pendingSpeedBands[target->id];
if (target->pendingVariantId && target->pendingVariantApplyBeat
&& pendingSpeedBand
&& std::abs (*target->pendingVariantApplyBeat - intent.applyAtBeat)
<= timingToleranceSeconds)
{
target->pendingVariantId = intent.variantId;
target->pendingVariantApplyBeat = intent.applyAtBeat;
pendingSpeedBand.reset();
++diagnostics.collisionIntentQueuedCount;
}
else if (queueIntent (intent))
++diagnostics.collisionIntentQueuedCount;
}
}

void TransportEngine::processSpeedActivity (double currentBeat,
std::size_t fixedStepCount)
{
const auto& bodies = world.bodies();
for (std::size_t index = 0; index < phrases.size(); ++index)
{
auto& phrase = phrases[index];
const auto& body = bodies[index];
const auto normalizedSpeed = std::hypot (body.velocity.x, body.velocity.y)
/ SpatialWorld::maximumThrowSpeed;
auto& tracker = speedTrackers[phrase.id];
const auto change = tracker.observe (
normalizedSpeed, fixedStepCount, world.motionPaused() || body.dragged);
if (! change)
continue;

++diagnostics.speedBandChangeCount;
const auto variantId = std::string { variantIdForActivityBand (*change) };
if (variantId == phrase.currentVariantId)
continue;

const auto earliestUnscheduledBeat = std::max (currentBeat, scheduledThroughBeat)
+ timingToleranceSeconds;
const MusicalIntent intent {
phrase.id,
MusicalIntentType::changeVariant,
variantId,
music::quantizeForward (earliestUnscheduledBeat, barLengthBeats),
};
if (queueIntent (intent))
{
pendingSpeedBands[phrase.id] = *change;
++diagnostics.speedIntentQueuedCount;
}
else
{
++diagnostics.speedIntentSuppressedCount;
}
}
}

bool TransportEngine::queueIntent (const MusicalIntent& intent)
{
if (intent.type != MusicalIntentType::changeVariant)
Expand Down Expand Up @@ -227,8 +296,15 @@ void TransportEngine::applyDueIntents (double currentBeat)
}

const auto variantId = *phrase.pendingVariantId;
const auto wasSpeedIntent = pendingSpeedBands[phrase.id].has_value();
if (music::applyVariant (phrase, variantId))
++diagnostics.collisionTransitionAppliedCount;
{
if (wasSpeedIntent)
++diagnostics.speedTransitionAppliedCount;
else
++diagnostics.collisionTransitionAppliedCount;
}
pendingSpeedBands[phrase.id].reset();
}
}

Expand Down Expand Up @@ -317,13 +393,18 @@ EngineSnapshot TransportEngine::snapshot() const
{
const auto& phrase = phrases[index];
const auto& body = bodies[index];
const auto& tracker = speedTrackers.at (phrase.id);
phraseSnapshots.push_back ({
phrase.id,
phrase.name,
phrase.role,
phrase.currentVariantId,
phrase.pendingVariantId,
phrase.pendingVariantApplyBeat,
tracker.rawNormalizedSpeed(),
tracker.smoothedNormalizedSpeed(),
tracker.stableBand(),
pendingSpeedBands.at (phrase.id),
phrase.midiChannel,
body.position,
body.velocity,
Expand Down
Loading