@rafaelaugusto/jolt 0.1.0-beta.9 → 0.1.0-rc.2

package/platforms/android/java/org/rafaelaugusto/jolt/LiveSpring.java

@@ -0,0 +1,277 @@
+package org.rafaelaugusto.jolt;
+
+import android.os.SystemClock;
+import android.view.Choreographer;
+import android.view.View;
+import java.lang.ref.WeakReference;
+import java.util.ArrayList;
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+/** Persistent native follower graph. The frame callback never enters JavaScript. */
+public final class LiveSpring {
+    private static final ArrayList<LiveSpring> nodes = new ArrayList<>();
+    private static boolean scheduled;
+    private static long previousFrame;
+    private static final Choreographer.FrameCallback clock = new Choreographer.FrameCallback() {
+        @Override public void doFrame(long nanos) {
+            scheduled = false;
+            double now = nanos / 1e6;
+            double remaining = previousFrame == 0 ? 1.0 / 120 : Math.min(.064, Math.max(0, (nanos - previousFrame) / 1e9));
+            previousFrame = nanos;
+            // Older nodes precede their followers. Substeps bound chain phase error at 60/120Hz.
+            while (remaining > 1e-9) {
+                double dt = Math.min(remaining, 1.0 / 240);
+                remaining -= dt;
+                for (int i = 0; i < nodes.size(); i++) nodes.get(i).step(now - remaining * 1000, dt);
+            }
+            boolean active = false;
+            for (int i = 0; i < nodes.size(); i++) {
+                LiveSpring node = nodes.get(i);
+                node.apply();
+                active |= node.moving || node.layersMoving(now);
+            }
+            if (active) schedule(); else previousFrame = 0;
+        }
+    };
+    private static void schedule() {
+        if (scheduled || nodes.isEmpty()) return;
+        scheduled = true;
+        Choreographer.getInstance().postFrameCallback(clock);
+    }
+
+    private final SpringState state;
+    private final double stiffness, damping, mass, restDelta, restSpeed;
+    private final ArrayList<Binding> bindings = new ArrayList<>();
+    private LiveSpring source;
+    private Mapping[] sourceMaps = new Mapping[0];
+    private SampledInput input;
+    private boolean direct = true;
+    private double targetValue;
+    private boolean moving, reduced, disposed, paused, inputHeld, sensorInput;
+
+    public LiveSpring(double initial, double stiffness, double damping, double mass,
+                      double restDelta, double restSpeed, boolean reduced) {
+        state = new SpringState(initial, 0);
+        this.stiffness = stiffness; this.damping = damping; this.mass = mass;
+        this.restDelta = restDelta; this.restSpeed = restSpeed; this.reduced = reduced;
+        targetValue = initial;
+        nodes.add(this);
+    }
+    public double getPosition() { return state.position; }
+    public double getVelocity() { return state.velocity; }
+    public boolean isMoving() { return moving; }
+    public static int activeCount() { return scheduled ? 1 : 0; }
+    public static int nodeCount() { return nodes.size(); }
+
+    public void follow(LiveSpring parent, String mappings) {
+        if (disposed || parent.disposed || nodes.indexOf(parent) >= nodes.indexOf(this))
+            throw new IllegalArgumentException("A spring can only follow an existing live node");
+        sourceMaps = maps(mappings);
+        source = parent;
+        wake();
+    }
+    public void updateInput(String snapshot) {
+        if (disposed) return;
+        try { input = new SampledInput(new JSONObject(snapshot)); }
+        catch (JSONException error) { throw new IllegalArgumentException(error); }
+        sensorInput = false; direct = false;
+        wake();
+    }
+    public void setSensorInput(double value) {
+        if (disposed || !Double.isFinite(value) || (sensorInput && inputHeld && state.position == value)) return;
+        sensorInput = true; inputHeld = true; direct = true; targetValue = value; input = null;
+        state.position = value; state.velocity = 0; moving = false;
+        schedule();
+    }
+    public void setTarget(double value) {
+        if (disposed) return;
+        sensorInput = false; direct = true; targetValue = value; input = null;
+        wake();
+    }
+    public void holdInput(double value, double velocity) {
+        if (disposed) return;
+        sensorInput = false; inputHeld = true; direct = true; targetValue = value; input = null;
+        state.position = value; state.velocity = velocity; moving = true;
+        apply(); schedule();
+    }
+    public void releaseInput(double target, double velocity) {
+        if (disposed) return;
+        inputHeld = false; state.velocity = velocity; setTarget(target);
+    }
+    public void setReduced(boolean value) { reduced = value; wake(); }
+    public void setPaused(boolean value) {
+        paused = value;
+        if (value) moving = false; else wake();
+    }
+    private void wake() {
+        // Sensor inputs are held data; policy changes must not start an endless frame clock.
+        if (disposed || paused || sensorInput) return;
+        moving = true;
+        if (reduced) { step(SystemClock.uptimeMillis(), 0); apply(); }
+        schedule();
+    }
+    private void step(double now, double dt) {
+        if (disposed || paused || inputHeld) return;
+        double target = source == null ? (direct ? targetValue : input.value(now)) : map(source.state.position, sourceMaps);
+        boolean inputMoving = source == null ? !direct && input.running(now) : source.moving;
+        if (reduced) { state.position = target; state.velocity = 0; }
+        else state.advance(target, stiffness, damping, mass, dt);
+        boolean rest = Math.abs(state.position - target) <= restDelta && Math.abs(state.velocity) <= restSpeed;
+        if (rest && !inputMoving) { state.position = target; state.velocity = 0; }
+        moving = inputMoving || !rest;
+    }
+    public Binding bind(View view, String property, String mappings) {
+        if (disposed) throw new IllegalStateException("Spring disposed");
+        Binding binding = new Binding(view, property, maps(mappings));
+        bindings.add(binding);
+        binding.apply();
+        return binding;
+    }
+    private void apply() {
+        for (int i = bindings.size() - 1; i >= 0; i--) {
+            Binding binding = bindings.get(i);
+            if (binding.view.get() == null) bindings.remove(i); else binding.apply();
+        }
+    }
+    private boolean layersMoving(double now) {
+        for (int i = 0; i < bindings.size(); i++)
+            for (SampledInput layer : bindings.get(i).layers)
+                if (layer.running(now)) return true;
+        return false;
+    }
+    public static void sync(View view) {
+        for (int i = 0; i < nodes.size(); i++) {
+            LiveSpring node = nodes.get(i);
+            for (int j = 0; j < node.bindings.size(); j++) {
+                Binding binding = node.bindings.get(j);
+                if (binding.view.get() == view) binding.apply();
+            }
+        }
+    }
+    public void dispose() {
+        if (disposed) return;
+        disposed = true; moving = false;
+        bindings.clear();
+        nodes.remove(this);
+        // A retained child continues from its own state toward the parent's last value.
+        for (int i = 0; i < nodes.size(); i++) {
+            LiveSpring child = nodes.get(i);
+            if (child.source == this) {
+                child.source = null;
+                child.setTarget(map(state.position, child.sourceMaps));
+            }
+        }
+        source = null;
+        if (nodes.isEmpty() && scheduled) {
+            Choreographer.getInstance().removeFrameCallback(clock);
+            scheduled = false; previousFrame = 0;
+        }
+    }
+
+    public final class Binding {
+        private final WeakReference<View> view;
+        private final String property;
+        private final Mapping[] mappings;
+        private final float density;
+        private boolean stopped;
+        private SampledInput[] layers = new SampledInput[0];
+        Binding(View view, String property, Mapping[] mappings) {
+            this.view = new WeakReference<>(view); this.property = property; this.mappings = mappings;
+            density = view.getResources().getDisplayMetrics().density;
+        }
+        public double getValue() { return map(state.position, mappings); }
+        public void setLayers(String inputs) {
+            try {
+                JSONArray array = new JSONArray(inputs);
+                SampledInput[] next = new SampledInput[array.length()];
+                for (int i = 0; i < next.length; i++) next[i] = new SampledInput(array.getJSONObject(i));
+                layers = next;
+            } catch (JSONException error) { throw new IllegalArgumentException(error); }
+            apply(); schedule();
+        }
+        public void cancel() { stopped = true; bindings.remove(this); }
+        private void apply() {
+            View target = view.get();
+            if (stopped || target == null || !target.isAttachedToWindow()) return;
+            double composed = getValue();
+            boolean multiply = property.equals("opacity") || property.startsWith("scale");
+            double now = SystemClock.uptimeMillis();
+            for (SampledInput layer : layers) composed = multiply ? composed * layer.value(now) : composed + layer.value(now);
+            float value = (float)composed;
+            switch (property) {
+                case "x": target.setTranslationX(value * density); break;
+                case "y": target.setTranslationY(value * density); break;
+                case "scaleX": target.setScaleX(value); break;
+                case "scaleY": target.setScaleY(value); break;
+                case "rotate": target.setRotation(value); break;
+                case "rotateX": target.setRotationX(value); break;
+                case "rotateY": target.setRotationY(value); break;
+                case "opacity": target.setAlpha(Math.max(0, Math.min(1, value))); break;
+                default: throw new IllegalArgumentException("Unsupported live property " + property);
+            }
+        }
+    }
+    private static final class Mapping {
+        final double[] input, output;
+        final boolean clamp;
+        Mapping(JSONObject json) throws JSONException {
+            input = array(json.getJSONArray("input")); output = array(json.getJSONArray("output"));
+            clamp = json.getBoolean("clamp");
+        }
+        double value(double value) {
+            if (clamp && value <= input[0]) return output[0];
+            if (clamp && value >= input[input.length - 1]) return output[output.length - 1];
+            int index = 0;
+            while (index < input.length - 2 && value > input[index + 1]) index++;
+            double span = input[index + 1] - input[index];
+            double fraction = span > 0 ? (value - input[index]) / span : value < input[index] ? 0 : 1;
+            return output[index] + (output[index + 1] - output[index]) * fraction;
+        }
+    }
+    private static Mapping[] maps(String json) {
+        try {
+            JSONArray array = new JSONArray(json);
+            Mapping[] result = new Mapping[array.length()];
+            for (int i = 0; i < result.length; i++) result[i] = new Mapping(array.getJSONObject(i));
+            return result;
+        } catch (JSONException error) { throw new IllegalArgumentException(error); }
+    }
+    private static double map(double value, Mapping[] maps) {
+        for (Mapping mapping : maps) value = mapping.value(value);
+        return value;
+    }
+    private static double[] array(JSONArray input) throws JSONException {
+        double[] result = new double[input.length()];
+        for (int i = 0; i < result.length; i++) result[i] = input.getDouble(i);
+        return result;
+    }
+    private static final class SampledInput {
+        final double value, anchor, elapsed, duration, delay, repeat, end;
+        final double[] values, times;
+        final boolean reverse, playing;
+        SampledInput(JSONObject json) throws JSONException {
+            value = json.getDouble("value");
+            anchor = SystemClock.uptimeMillis(); elapsed = json.getDouble("elapsed");
+            playing = json.getBoolean("running");
+            duration = json.getDouble("duration"); delay = json.getDouble("delay");
+            repeat = json.getDouble("repeat"); end = json.getDouble("to");
+            reverse = json.getBoolean("reverse");
+            values = array(json.getJSONArray("values")); times = array(json.getJSONArray("times"));
+        }
+        boolean running(double now) { return playing && (repeat < 0 || now - anchor + elapsed < delay + duration * (repeat + 1)); }
+        double value(double now) {
+            if (!playing || values.length < 2) return value;
+            if (!running(now)) return end;
+            double time = Math.max(0, now - anchor + elapsed - delay);
+            double iteration = Math.floor(time / Math.max(1, duration));
+            double progress = (time % Math.max(1, duration)) / Math.max(1, duration);
+            if (reverse && iteration % 2 >= 1) progress = 1 - progress;
+            int lo = 0, hi = times.length - 1;
+            while (lo + 1 < hi) { int mid = (lo + hi) / 2; if (times[mid] <= progress) lo = mid; else hi = mid; }
+            double fraction = times[hi] > times[lo] ? (progress - times[lo]) / (times[hi] - times[lo]) : 1;
+            return values[lo] + (values[hi] - values[lo]) * Math.max(0, Math.min(1, fraction));
+        }
+    }
+}

package/platforms/android/java/org/rafaelaugusto/jolt/MotionProbe.java

@@ -0,0 +1,70 @@
+package org.rafaelaugusto.jolt;
+
+import android.os.SystemClock;
+import android.view.Choreographer;
+import android.view.View;
+import java.lang.ref.WeakReference;
+import org.json.JSONArray;
+import org.json.JSONObject;
+import org.json.JSONException;
+
+/** Optional development sampling. No callback crosses into JavaScript per frame. */
+public final class MotionProbe implements Choreographer.FrameCallback {
+    private static int activeCount;
+    private final WeakReference<View> view;
+    private final double[][] rows;
+    private final double density, interval;
+    private int head, count, dropped, samples;
+    private double last = Double.NEGATIVE_INFINITY, sampleCPU, drainCPU;
+    private boolean active = true;
+
+    public static MotionProbe start(View view, int capacity, double hertz) {
+        return new MotionProbe(view, capacity, hertz);
+    }
+    public static int activeCount() { return activeCount; }
+    private MotionProbe(View target, int capacity, double hertz) {
+        view = new WeakReference<>(target);
+        rows = new double[Math.max(8, Math.min(600, capacity))][9];
+        density = target.getResources().getDisplayMetrics().density;
+        interval = 1000 / Math.max(1, Math.min(120, hertz));
+        activeCount++; Choreographer.getInstance().postFrameCallback(this);
+    }
+    @Override public void doFrame(long frameTimeNanos) {
+        if (!active) return;
+        View target = view.get();
+        if (target == null || !target.isAttachedToWindow()) { dispose(); return; }
+        long begin = System.nanoTime();
+        double now = SystemClock.uptimeMillis();
+        if (now - last >= interval - 0.5) {
+            last = now;
+            int slot;
+            if (count == rows.length) { slot = head; head = (head + 1) % rows.length; dropped++; }
+            else { slot = (head + count) % rows.length; count++; }
+            double[] r = rows[slot];
+            r[0] = now; r[1] = target.getTranslationX()/density; r[2] = target.getTranslationY()/density;
+            r[3] = target.getScaleX(); r[4] = target.getScaleY(); r[5] = target.getRotation();
+            r[6] = target.getRotationX(); r[7] = target.getRotationY(); r[8] = target.getAlpha();
+            samples++; sampleCPU += (System.nanoTime()-begin)/1e6;
+        }
+        Choreographer.getInstance().postFrameCallback(this);
+    }
+    public String drain() {
+        long begin = System.nanoTime();
+        try {
+            JSONArray out = new JSONArray();
+            for (int i=0;i<count;i++) {
+                JSONArray row = new JSONArray();
+                for(double value:rows[(head+i)%rows.length]) row.put(Double.isFinite(value)?value:JSONObject.NULL);
+                out.put(row);
+            }
+            head=0; count=0;
+            JSONObject result=new JSONObject(); result.put("rows",out); result.put("dropped",dropped);
+            result.put("samples",samples); result.put("sampleCpuMs",sampleCPU); result.put("drainCpuMs",drainCPU); result.put("active",active);
+            String json=result.toString(); drainCPU+=(System.nanoTime()-begin)/1e6; return json;
+        } catch(JSONException error) { throw new IllegalStateException(error); }
+    }
+    public void dispose() {
+        if (!active) return;
+        active=false; activeCount--; Choreographer.getInstance().removeFrameCallback(this); view.clear();
+    }
+}

package/platforms/android/java/org/rafaelaugusto/jolt/ParticleEmitter.java

@@ -0,0 +1,192 @@
+package org.rafaelaugusto.jolt;
+
+import android.database.ContentObserver;
+import android.graphics.Canvas;
+import android.graphics.ColorFilter;
+import android.graphics.Paint;
+import android.graphics.PixelFormat;
+import android.graphics.drawable.Drawable;
+import android.os.Handler;
+import android.os.Looper;
+import android.os.SystemClock;
+import android.provider.Settings;
+import android.view.Choreographer;
+import android.view.View;
+import android.view.ViewParent;
+
+/** A visual-only ViewOverlay drawable: all integration, deadlines and drawing stay in Java. */
+public final class ParticleEmitter extends Drawable implements Choreographer.FrameCallback, View.OnAttachStateChangeListener {
+    public interface Listener { void onEnd(); }
+    private static int activeCount;
+    private View target, host;
+    private final boolean overlay;
+    private final float density;
+    private final ParticleSimulation simulation;
+    private final Paint paint = new Paint(Paint.ANTI_ALIAS_FLAG);
+    private final Choreographer choreographer = Choreographer.getInstance();
+    private final Handler handler = new Handler(Looper.getMainLooper());
+    private final float[] point = new float[2];
+    private final int[] location = new int[2];
+    private final long[] intervals = new long[512];
+    private final ContentObserver scaleObserver = new ContentObserver(handler) {
+        @Override public void onChange(boolean selfChange) { if (disabled()) stop(); }
+    };
+    private Listener listener;
+    private boolean started, stopped, observing;
+    private long began, lastFrame, frames, draws, workNanos, drawNanos;
+    private float originX, originY, corner;
+    private final Runnable expire = new Runnable() { @Override public void run() { stop(); } };
+    private final long deadline;
+
+    public ParticleEmitter(View target, boolean overlay, int[] colors, int shape, int source,
+            double rate, double lifetimeMs, float size, float velocity, float velocityRange,
+            float angle, float spread, float gravity, float spin, float spinRange,
+            boolean fade, double durationMs, Listener listener) {
+        this.target = target; this.host = overlay ? target.getRootView() : target; this.overlay = overlay;
+        this.listener = listener;
+        density = target.getResources().getDisplayMetrics().density;
+        simulation = new ParticleSimulation(colors, shape, source, rate, lifetimeMs, size,
+                velocity, velocityRange, angle, spread, gravity, spin, spinRange, fade, durationMs, System.nanoTime());
+        deadline = durationMs < 0 ? -1 : (long)Math.ceil(durationMs + lifetimeMs);
+    }
+
+    private boolean disabled() {
+        return target != null && Settings.Global.getFloat(target.getContext().getContentResolver(),
+                Settings.Global.ANIMATOR_DURATION_SCALE, 1) == 0;
+    }
+    private boolean valid() {
+        return target != null && target.isAttachedToWindow() && target.getWindowVisibility() == View.VISIBLE
+                && target.isShown() && target.getWidth() > 0 && target.getHeight() > 0
+                && host.getWindowToken() != null && host.getWindowToken() == target.getWindowToken()
+                && (!overlay || host == target.getRootView());
+    }
+    public void start() {
+        if (started || stopped) return;
+        if (!valid() || disabled()) { stop(); return; }
+        started = true; activeCount++;
+        began = SystemClock.uptimeMillis();
+        if (overlay) {
+            // Convert the center through transforms and parent scrolling into root-overlay coordinates.
+            point[0] = target.getWidth() * .5f; point[1] = target.getHeight() * .5f;
+            View current = target;
+            while (current != host) {
+                current.getMatrix().mapPoints(point);
+                point[0] += current.getLeft(); point[1] += current.getTop();
+                ViewParent parent = current.getParent();
+                if (!(parent instanceof View)) { stop(); return; }
+                current = (View)parent;
+                point[0] -= current.getScrollX(); point[1] -= current.getScrollY();
+            }
+            originX = point[0]; originY = point[1];
+        }
+        target.addOnAttachStateChangeListener(this);
+        target.getContext().getContentResolver().registerContentObserver(
+                Settings.Global.getUriFor(Settings.Global.ANIMATOR_DURATION_SCALE), false, scaleObserver);
+        observing = true;
+        setBounds(0, 0, host.getWidth(), host.getHeight());
+        host.getOverlay().add(this);
+        if (deadline >= 0) handler.postDelayed(expire, deadline);
+        choreographer.postFrameCallback(this);
+    }
+
+    /** Layout/identity checks at JS boundaries; moving views otherwise stay in their native overlay. */
+    public void refresh(float cornerPixels) {
+        corner = Math.max(0, cornerPixels);
+        if (!stopped && started && !valid()) stop();
+    }
+    @Override public void doFrame(long frameTimeNanos) {
+        if (stopped) return;
+        long workStart = System.nanoTime();
+        if (!valid()) { stop(); return; }
+        if (lastFrame != 0) intervals[(int)((frames - 1) % intervals.length)] = frameTimeNanos - lastFrame;
+        lastFrame = frameTimeNanos; frames++;
+        // Deliberately use monotonic wall time: UI stalls cannot extend emission/lifetime deadlines.
+        simulation.advance((SystemClock.uptimeMillis() - began) / 1000d,
+                overlay ? 0 : target.getWidth() / density, overlay ? 0 : target.getHeight() / density);
+        if (simulation.finished()) { stop(); return; }
+        if (getBounds().width() != host.getWidth() || getBounds().height() != host.getHeight())
+            setBounds(0, 0, host.getWidth(), host.getHeight());
+        invalidateSelf();
+        workNanos += System.nanoTime() - workStart;
+        choreographer.postFrameCallback(this);
+    }
+
+    @Override public void draw(Canvas canvas) {
+        if (stopped) return;
+        long drawStart = System.nanoTime(); draws++;
+        int save = canvas.save();
+        // The overlay is above this host's content, bounded by the host/window viewport.
+        canvas.clipRect(getBounds());
+        if (!overlay && corner > 0) {
+            // A retained path avoids allocating rounded clips per frame.
+            clip.rewind();
+            rect.set(getBounds());
+            clip.addRoundRect(rect, corner, corner, android.graphics.Path.Direction.CW);
+            canvas.clipPath(clip);
+        }
+        if (overlay) canvas.translate(originX, originY);
+        canvas.scale(density, density);
+        float size = simulation.size, radius = size * .5f;
+        paint.setStyle(simulation.shape == 2 ? Paint.Style.STROKE : Paint.Style.FILL);
+        paint.setStrokeWidth(size * (3f / 32));
+        for (int i = 0, count = simulation.live(); i < count; i++) {
+            paint.setColor(simulation.color(i));
+            float x = simulation.x(i), y = simulation.y(i);
+            if (simulation.shape == 1) {
+                int particleSave = canvas.save();
+                canvas.rotate(simulation.rotation(i), x, y);
+                canvas.drawRect(x - radius, y - size * (9f / 32), x + radius, y + size * (9f / 32), paint);
+                canvas.restoreToCount(particleSave);
+            } else canvas.drawCircle(x, y, simulation.shape == 2 ? size * (14f / 32) : radius, paint);
+        }
+        canvas.restoreToCount(save);
+        drawNanos += System.nanoTime() - drawStart;
+    }
+    private final android.graphics.Path clip = new android.graphics.Path();
+    private final android.graphics.RectF rect = new android.graphics.RectF();
+
+    public void stop() {
+        if (stopped) return;
+        stopped = true;
+        choreographer.removeFrameCallback(this);
+        handler.removeCallbacks(expire);
+        if (observing) target.getContext().getContentResolver().unregisterContentObserver(scaleObserver);
+        observing = false;
+        if (started) { activeCount--; target.removeOnAttachStateChangeListener(this); host.getOverlay().remove(this); }
+        simulation.clear();
+        setCallback(null);
+        target = host = null;
+        Listener done = listener; listener = null;
+        if (done != null) done.onEnd();
+    }
+    @Override public void onViewAttachedToWindow(View view) { }
+    @Override public void onViewDetachedFromWindow(View view) { stop(); }
+    @Override public void setAlpha(int alpha) { }
+    @Override public void setColorFilter(ColorFilter filter) { paint.setColorFilter(filter); }
+    @Override public int getOpacity() { return PixelFormat.TRANSLUCENT; }
+
+    // Native conformance/diagnostics. Reads allocate only when explicitly requested, never per frame.
+    public static int getActiveCount() { return activeCount; }
+    public boolean isStopped() { return stopped; }
+    public int getLiveCount() { return simulation.live(); }
+    public int getPeakCount() { return simulation.peak(); }
+    public int getCapacity() { return simulation.capacity(); }
+    public long getEmittedCount() { return simulation.emitted(); }
+    public long getSkippedCount() { return simulation.skipped(); }
+    public long getFrameCount() { return frames; }
+    public long getDrawCount() { return draws; }
+    public long getWorkNanos() { return workNanos; }
+    public long getDrawNanos() { return drawNanos; }
+    public float getDensity() { return density; }
+    public double getTimeSeconds() { return simulation.time(); }
+    public boolean isObserving() { return observing; }
+    public float[] getOriginInWindow() {
+        if (host != null) host.getLocationInWindow(location);
+        return new float[] { originX + location[0], originY + location[1] };
+    }
+    public float[] getParticle(int index) { return new float[] { simulation.x(index), simulation.y(index), simulation.rotation(index), simulation.color(index) }; }
+    public long[] getFrameIntervals() {
+        int count = (int)Math.min(Math.max(0, frames - 1), intervals.length);
+        return java.util.Arrays.copyOf(intervals, count);
+    }
+}

package/platforms/android/java/org/rafaelaugusto/jolt/ParticleSimulation.java

@@ -0,0 +1,114 @@
+package org.rafaelaugusto.jolt;
+
+/** Bounded, allocation-free particle state. Units are DIPs, seconds and degrees.
+ * Android supplies elapsed wall time; the same engine runs in deterministic JVM tests. */
+public final class ParticleSimulation {
+    public static final int MAX_PARTICLES = 10000;
+    public final int shape, source;
+    public final float size;
+    private final int[] palette;
+    private final double rate, lifetime, duration;
+    private final float velocity, velocityRange, angle, spread, gravity, spin, spinRange;
+    private final boolean fade;
+    private double[] births;
+    private float[] xs, ys, vxs, vys, rotations, spins;
+    private int[] colors;
+    private int live, peak;
+    private long scheduled, emitted, skipped;
+    private long random;
+    private double time;
+
+    public ParticleSimulation(int[] palette, int shape, int source, double rate,
+            double lifetimeMs, float size, float velocity, float velocityRange,
+            float angle, float spread, float gravity, float spin, float spinRange,
+            boolean fade, double durationMs, long seed) {
+        if (palette == null || palette.length == 0 || palette.length > 32 || shape < 0 || shape > 2 || source < 0 || source > 2)
+            throw new IllegalArgumentException("Invalid particle colors, shape or source");
+        if (!finite(rate) || rate <= 0 || rate > 50000 || !finite(lifetimeMs) || lifetimeMs < 1 || lifetimeMs > 60000
+                || !finite(durationMs) || (durationMs != -1 && (durationMs < 1 || durationMs > Integer.MAX_VALUE - lifetimeMs - 50))
+                || !finite(size) || size < 1 || size > 128 || !finite(velocity) || velocity < 0 || velocity > 10000
+                || !finite(velocityRange) || velocityRange < 0 || velocityRange > 10000
+                || !finite(angle) || Math.abs(angle) > 360 || !finite(spread) || spread < 0 || spread > 360
+                || !finite(gravity) || Math.abs(gravity) > 10000 || !finite(spin) || Math.abs(spin) > 3600
+                || !finite(spinRange) || spinRange < 0 || spinRange > 3600)
+            throw new IllegalArgumentException("Invalid particle settings");
+        this.palette = palette.clone();
+        this.shape = shape; this.source = source; this.rate = rate;
+        lifetime = lifetimeMs / 1000; duration = durationMs < 0 ? Double.POSITIVE_INFINITY : durationMs / 1000;
+        this.size = size; this.velocity = velocity; this.velocityRange = velocityRange;
+        this.angle = angle; this.spread = spread; this.gravity = gravity;
+        this.spin = spin; this.spinRange = spinRange; this.fade = fade;
+        random = seed == 0 ? 1 : seed;
+        double population = rate * Math.min(lifetime, duration);
+        if (population > MAX_PARTICLES + 0.000001) throw new IllegalArgumentException("Particle population exceeds 10000");
+        int capacity = Math.max(1, Math.min(MAX_PARTICLES, (int)Math.ceil(population)));
+        births = new double[capacity]; xs = new float[capacity]; ys = new float[capacity];
+        vxs = new float[capacity]; vys = new float[capacity]; rotations = new float[capacity];
+        spins = new float[capacity]; colors = new int[capacity];
+    }
+
+    private static boolean finite(double value) { return !Double.isNaN(value) && !Double.isInfinite(value); }
+    private float unit() {
+        // xorshift64*: deterministic internal seed, never part of the public JS contract.
+        random ^= random >>> 12; random ^= random << 25; random ^= random >>> 27;
+        return ((random * 2685821657736338717L) >>> 40) / 16777216f;
+    }
+    private float variation(float range) { return (unit() * 2 - 1) * range; }
+
+    /** Advance directly to the current time, skipping already-dead births after a stall.
+     * No backlog of expired particles and no integration steps proportional to missed frames. */
+    public void advance(double elapsedSeconds, float width, float height) {
+        if (births == null || !finite(elapsedSeconds)) return;
+        time = Math.max(time, Math.max(0, elapsedSeconds));
+        for (int i = live - 1; i >= 0; i--) {
+            if (time - births[i] >= lifetime - 0.000000001) {
+                int last = --live;
+                births[i] = births[last]; xs[i] = xs[last]; ys[i] = ys[last];
+                vxs[i] = vxs[last]; vys[i] = vys[last]; rotations[i] = rotations[last];
+                spins[i] = spins[last]; colors[i] = colors[last];
+            }
+        }
+        long until = (long)Math.floor(Math.min(time, duration) * rate + 0.0000001);
+        long dead = Math.min(until, (long)Math.floor(Math.max(0, time - lifetime) * rate + 0.0000001));
+        if (dead > scheduled) { skipped += dead - scheduled; scheduled = dead; }
+        // scheduled is monotonic; at most capacity particles can be alive in this interval.
+        while (scheduled < until) {
+            long index = ++scheduled;
+            if (live >= births.length) { skipped++; continue; }
+            int i = live++;
+            births[i] = index / rate;
+            xs[i] = source == 0 ? width * .5f : unit() * width;
+            ys[i] = source == 1 ? 0 : source == 2 ? height : height * .5f;
+            double direction = Math.toRadians(angle + variation(spread * .5f));
+            float speed = velocity + variation(velocityRange);
+            vxs[i] = (float)Math.cos(direction) * speed;
+            vys[i] = (float)Math.sin(direction) * speed;
+            rotations[i] = shape == 1 ? unit() * 360 : 0;
+            spins[i] = spin + variation(spinRange);
+            colors[i] = palette[(int)((index - 1) % palette.length)];
+            emitted++;
+        }
+        peak = Math.max(peak, live);
+    }
+
+    public float x(int i) { return xs[i] + vxs[i] * (float)(time - births[i]); }
+    public float y(int i) { float age = (float)(time - births[i]); return ys[i] + vys[i] * age + gravity * age * age * .5f; }
+    public float rotation(int i) { return rotations[i] + spins[i] * (float)(time - births[i]); }
+    public int color(int i) {
+        int color = colors[i];
+        if (!fade) return color;
+        int alpha = Math.round((color >>> 24) * (float)Math.max(0, 1 - (time - births[i]) / lifetime));
+        return (color & 0x00ffffff) | (alpha << 24);
+    }
+    public boolean finished() { return time >= duration + lifetime || (time >= duration && live == 0); }
+    public int live() { return live; }
+    public int peak() { return peak; }
+    public int capacity() { return births == null ? 0 : births.length; }
+    public long emitted() { return emitted; }
+    public long skipped() { return skipped; }
+    public double time() { return time; }
+    public void clear() {
+        live = 0;
+        births = null; xs = ys = vxs = vys = rotations = spins = null; colors = null;
+    }
+}