Skip to content
Elucim

Quick Start

Your First Scene

Section titled “Your First Scene”

The recommended authoring path is a normalized ElucimDocument rendered with <DslRenderer>. You can write the same DSL as JSON or YAML; both parse to the same document shape with one scene, stable element IDs, explicit timelines, and a state machine that controls playback.

import { DslRenderer, type ElucimDocument } from '@elucim/dsl';


const scene: ElucimDocument = {
  version: '2.0',
  scene: {
    type: 'player',
    width: 500,
    height: 350,
    fps: 30,
    background: '$background',
    children: ['ring', 'title'],
  },
  elements: {
    ring: {
      id: 'ring',
      type: 'circle',
      role: 'hero-shape',
      props: {
        type: 'circle',
        cx: 250,
        cy: 175,
        r: 80,
        stroke: '$accent',
        strokeWidth: 3,
        fill: 'none',
        opacity: 0,
      },
    },
    title: {
      id: 'title',
      type: 'text',
      role: 'title',
      props: {
        type: 'text',
        x: 250,
        y: 180,
        fill: '$foreground',
        fontSize: 24,
        textAnchor: 'middle',
        content: 'Hello World',
        opacity: 0,
      },
    },
  },
  timelines: {
    intro: {
      id: 'intro',
      duration: 50,
      tracks: [
        { target: 'ring', property: 'opacity', keyframes: [{ frame: 0, value: 0 }, { frame: 20, value: 1 }] },
        { target: 'title', property: 'opacity', keyframes: [{ frame: 30, value: 0 }, { frame: 50, value: 1 }] },
      ],
    },
  },
  defaultStateMachine: 'main',
  stateMachines: {
    main: {
      id: 'main',
      entry: 'intro',
      states: { intro: { timeline: 'intro' } },
      transitions: [{ id: 'entry-start', from: 'entry', to: 'intro', trigger: 'onStart' }],
    },
  },
};


export function MyFirstScene() {
  return <DslRenderer dsl={scene} colorScheme="auto" />;
}

If you prefer YAML authoring, load the same shape with fromYaml():

import { fromYaml } from '@elucim/dsl';


const scene = fromYaml(yamlString);
Hello WorldYour first Elucim scene

What’s Happening

Section titled “What’s Happening”
  1. scene defines the 500×350 render surface and top-level element order.
  2. elements stores each visual by stable ID so later edits can target ring or title.
  3. timelines.intro animates opacity with explicit keyframes instead of wrapper components.
  4. stateMachines.main starts the intro timeline automatically through the Entry transition.
  5. <DslRenderer> turns the normalized document into the interactive React/SVG scene.

Key Fields

Section titled “Key Fields”
FieldDescription
scene.width / scene.heightCanvas dimensions in pixels
scene.fpsFrames per second for timeline playback
scene.childrenOrdered top-level element IDs
elementsID-keyed visual primitives and metadata
timelinesKeyframe tracks for motion
stateMachinesEntry, click/key, reset, and auto-advance behavior

Next Steps

Section titled “Next Steps”