ExodeUI React SDK

The official React Runtime for the ExodeUI Animation Engine. Seamlessly render and interact with high-performance animations, physics simulations, and state machines built with ExodeUI.

Installation

npm install exodeui
# or
yarn add exodeui

Setup (Vite)

If you are using Vite, you must add the Exode Vite plugin to your vite.config.ts so Vite knows how to read .exode animation files natively:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { exodePlugin } from 'exodeui/vite-plugin'

export default defineConfig({
  plugins: [react(), exodePlugin()],
})

Basic Usage

import { ExodeUICanvas } from 'exodeui';

function App() {
  return (
    <div style={{ width: 800, height: 600 }}>
      <ExodeUICanvas 
        src="/animations/my-scene.json"
        autoPlay={true}
        fit="Contain"
        alignment="Center"
      />
    </div>
  );
}

Features

1. State Variables & Logic

ExodeUI supports complex interactive logic using a node-based State Machine. At the core of this logic are State Variables (Inputs). ExodeUI supports several types of state variables:

• Boolean: Simple true / false switches.
• Number: Float or integer values (e.g. 0 to 100).
• Trigger: Momentary pulses that auto-reset (e.g. for "Jump" or "Click").
• Array: Arrays of numbers or strings (e.g. for charts or list data).
• Random Number / Random Color: Engine-managed variables that dynamically evaluate based on seeds and time.

Setting State Variables

You can update variables to drive animations and logic from your React code:

const { setEngine, setInputBool, fireTrigger, setInputNumberArray } = useExodeUI();

// ... inside your component
<ExodeUICanvas 
  src="/player_controller.json"
  onReady={setEngine}
/>

// Setting values
<button onClick={() => setInputBool('IsRunning', true)}>Run</button>
<button onClick={() => fireTrigger('Jump')}>Jump</button>
<button onClick={() => setInputNumberArray('ChartData', [10, 20, 30])}>Update Chart</button>

Reading State Variables

You can also read the current value of any state variable at runtime using getInputValue(). This works for standard variables you set, as well as dynamic ones like Random Number and Random Color evaluated internally by the engine:

const { getInputValue } = useExodeUI();

// Read a boolean, number, array, or dynamically generated variable
const isRunning = getInputValue('IsRunning');
const randomVal = getInputValue('MyRandomNumber'); // Read engine-managed random value
console.log(`Running: ${isRunning}, Random: ${randomVal}`);

2. Physics Engine

Built-in 2D physics using Rapier.

• Dynamic Bodies: Objects that react to gravity and collisions.
• Static Bodies: Platforms and walls.
• Kinematic: Animated objects that push other bodies.
• Properties: Mass, Friction, Restitution (Bounciness), Density.

Physics is configured directly in the ExodeUI Editor.

3. Data Visualization (Line Graphs)

Render beautiful, animated line graphs with zero extra code.

• Line Graphs: Supports multiple datasets, smoothing (Catmull-Rom splines), fill areas, and points.
• Data Binding: Bind graph data to runtime inputs or variables.

4. SEO & Metadata

Automatically manage page metadata and generate semantic HTML for search engines and screen readers.

• Automatic Metadata: Updates document.title, meta description, keywords, and OpenGraph tags based on your artboard configuration.
• Semantic Overlay: Generates a visually hidden but accessible HTML structure (H1, H2, P, buttons) based on the objects in your animation.
• JSON-LD: Injects structured data (schema.org) for advanced search engine rich results.

import { ExodeUICanvas, ExodeSEO } from 'exodeui';

function MyPage({ artboard }) {
  return (
    <>
      {/* ExodeSEO handles title, meta tags, and accessibility overlay */}
      <ExodeSEO artboard={artboard} />
      <ExodeUICanvas artboard={artboard} />
    </>
  );
}

API Reference

<ExodeUICanvas />

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | - | URL to the animation JSON file. | | artboard | object | - | Direct JSON data object (if imported). | | fit | 'Contain' \| 'Cover' \| 'Fill' | 'Contain' | Scaling strategy. | | alignment | 'Center' \| 'TopLeft' ... | 'Center' | Alignment within the canvas. | | autoPlay | boolean | true | Auto-start the animation loop. | | onReady | (engine: ExodeUIEngine) => void | - | Callback when engine is initialized. | | onTrigger | (name: string, animationName: string) => void | - | Listener for outgoing triggers (events). | | onInputUpdate | (nameOrId: string, value: any) => void | - | Listener for input value changes. |

useExodeUI Hook

A helper hook for easier engine management.

import { useExodeUI, ExodeUICanvas } from 'exodeui';

function Game() {
  const { setEngine, setInputBool, fireTrigger } = useExodeUI();

  return (
    <>
      <ExodeUICanvas src="/game.json" onReady={setEngine} />
      <div className="controls">
          <button onMouseDown={() => setInputBool('Fire', true)}>Shoot</button>
      </div>
    </>
  );
}

Advanced

Logic Nodes

The engine automatically evaluates logic nodes defined in the editor.

• AND / OR / XOR / NOT gates allow for complex condition evaluation without writing code.
• Inputs are strictly typed: Boolean, Number, Trigger (momentary boolean), Text.

Custom Fonts

Ensure any custom fonts used in the ExodeUI editor are loaded in your web page (e.g., via Google Fonts or @font-face) for correct rendering.

License

MIT