Clox Odyssey

A native Expo module that renders stunning 3D particle animations for iOS and Android. The particles dynamically form shapes based on user input, with a default spherical wave animation.

Features

• 🌀 3D Particle System - High-performance particle rendering using native graphics APIs
• 🔮 Dynamic Shape Morphing - Particles can form various shapes (sphere, cube, torus, etc.)
• 🎨 Customizable Appearance - Control particle colors, sizes, and animation parameters
• ⚡ Native Performance - Built with Metal (iOS) and OpenGL/Vulkan (Android) for smooth 60fps animations
• 📱 Cross-Platform - Consistent experience on both iOS and Android

Installation

yarn add clox-odyssey

For bare React Native projects, you must ensure that you have installed and configured the expo package before continuing.

Usage

import { CloxOdysseyView } from 'clox-odyssey';

export default function App() {
  return (
    <CloxOdysseyView
      style={{ flex: 1 }}
      shape="sphere"
      particleCount={1000}
      particleColor="#00FFFF"
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | shape | 'sphere' \| 'cube' \| 'torus' \| 'wave' | 'sphere' | The shape particles will form | | particleCount | number | 1000 | Number of particles to render | | particleColor | string | '#FFFFFF' | Color of the particles (hex) | | particleSize | number | 2 | Size of individual particles | | animationSpeed | number | 1.0 | Speed multiplier for animations | | autoRotate | boolean | true | Whether the shape auto-rotates |

SiriGlowView

A native port of the iOS 18 Siri screen animation: an animated mesh gradient bleeds in from the screen edges behind a wobbly, feathered mask, with a soft white rim on the boundary and a ripple you can fire from a tap. Metal on iOS, OpenGL ES on Android, same shader math on both.

It is a transparent overlay. Mount it once above your screen (it defaults to StyleSheet.absoluteFill and pointerEvents="none"), then toggle active when voice mode / AI mode turns on. Once it has faded out it stops rendering, so leaving it mounted costs nothing.

import { SiriGlowView, type SiriGlowViewRef } from 'clox-odyssey';

function Screen() {
  const glowRef = useRef<SiriGlowViewRef>(null);
  const isVoiceMode = useVoiceMode();

  // Optional: drive it from the mic (0-100), same contract as VoiceWaveView.
  useMicLevel((level) => glowRef.current?.distort(level));

  return (
    <>
      <YourContent onTap={(x, y) => glowRef.current?.ripple(x / width, y / height)} />
      <SiriGlowView ref={glowRef} active={isVoiceMode} />
    </>
  );
}

| Prop | Type | Default | Description | |------|------|---------|-------------| | active | boolean | false | Show the glow. Eases in/out over transitionDuration, sweeping in from the edges. | | colors | string[] | Siri palette | Mesh gradient colors. 9 = full 3x3 control (row-major); fewer are laid out as a Latin square so every edge cycles the palette (pass the theme's agentColors). | | rimColor | string | '#FFFFFF' | Color of the blurred rim on the boundary. | | gradientScale | number | 1.3 | Mesh zoom. Lower = more color variety along the edges; higher = broader, calmer regions. | | cornerRadius | number | device | Outer corner radius (pt/dp). Unset = the physical display corner radius. | | edgeInset | number | 4 | Fully-opaque band width from the edge before the feather starts. | | feather | number | 18 | Width of the soft inner falloff (the reference's mask blur). | | wobble | number | 4 | Amplitude of the inner edge's slow breathing wobble. 0 disables. | | wobbleSpeed | number | 1 | Breathing rate multiplier, independent of speed (1 = ~4s per breath). | | progress | number | unset | Manual reveal 0..1; overrides the active transition while set (drive it from a gesture / shared value). | | level | number | unset | Declarative mic level 0..1; sustained, takes precedence over distort() while set. | | rippleOrigin | [number, number] | [0.5, 0.5] | Normalised origin for ripples fired via rippleTrigger. | | rippleTrigger | number | unset | Change the value (e.g. increment) to fire a ripple from rippleOrigin; the initial value does not fire. | | warpContent | boolean | true | Ripples warp the screen content under the overlay (one snapshot per ripple, sampled through the displacement for ~0.7s). false = glow-only ripples. | | rippleOnActivate | boolean | true | Fire a ripple from rippleOrigin when active turns on, so the screen warps once as the glow arrives. | | speed | number | 1 | Gradient flow + wobble speed multiplier. | | intensity | number | 1 | Peak opacity, 0..1. | | rimStrength | number | 1 | Brightness of the blurred white rim, 0..1. | | rippleStrength | number | 1 | Scale of the tap ripple. 0 disables. | | levelGain | number | 1 | How much distort() level thickens/brightens the glow. | | transitionDuration | number | 900 | In/out transition (ms). | | distortRevertDelay | number | 180 | Ms after the last distort() before the level decays. 0 sustains. |

Ref methods: ripple(x?, y?) (normalised 0..1, defaults to centre) and distort(level) (0..100, native thread).

Always on top (iOS)

SiriGlowView draws its Metal layer in its own transparent, touch-transparent UIWindow one level above the app window. Presented view controllers (native-stack presentation: 'modal' routes, Modal, alerts) and react-native-screens overlays all live inside the app window, so the glow frames every one of them no matter where the React view is mounted; mount it once, near the app root, with pointerEvents="none" and an absoluteFill style. No wrapper is needed and nothing else is re-ordered. Every touch falls through the glow window; it never becomes key, so focus, the keyboard and the status bar behave exactly as without it.

The warp snapshot is taken from the app window, so it captures whatever is on screen at activation (an open document included) and never the glow itself.

Android native-stack modals are fragments inside the root view, so a sibling mounted after the navigator already draws above them.

Development

To run the example app:

# Install dependencies
yarn

# Build TypeScript
yarn build

# Run example app
cd example
yarn ios
# or
yarn android

License

MIT