Galacean Effects Core

The core runtime library for Galacean Effects, responsible for asset loading, scene management, and rendering.

Basic Concepts

The Composition is the fundamental unit of animation playback in Galacean Effects. The Composition class manages the entire lifecycle from data parsing (JSON -> VFXItem -> RendererComponent) to the creation, updating, and destruction of render frames (RenderFrame) and render passes (RenderPass).

Core Architecture

Engine
  ├── Composition
  │     ├── VFXItem (Element)
  │     │     ├── Component
  │     │     │     └── RendererComponent
  │     │     └── Transform
  │     ├── RenderFrame
  │     │     └── RenderPass
  │     └── Camera
  └── Resource Management
        ├── Texture
        ├── Material
        └── Geometry

Each composition contains different types of elements (VFXItem) and their components (Component), including:

• Camera component
• Sprite (layer) component
• Particle system
• Text component
• Interactive component

When a composition is created, it completes:

1. Loading of data assets
2. Creation of elements (VFXItem) and their components
3. Loading and creation of textures (Texture)
4. Initialization of RenderFrame and RenderPass

Core Modules

1. Engine Engine

Engine is the core entry point, responsible for managing all GPU resources and the lifecycle of compositions.

import { Engine } from '@galacean/effects-core';

// Create engine
const engine = Engine.create(canvas, {
  fps: 60,
  pixelRatio: window.devicePixelRatio,
});

Main features:

• Manages the renderer (Renderer)
• Manages GPU resources (textures, materials, geometries)
• Manages creation and destruction of compositions
• Provides a ticker (Ticker) to drive the render loop
• Handles interactive events

2. Asset Management AssetManager

Responsible for loading all resources needed for effects:

import { AssetManager } from '@galacean/effects-core';

const assetManager = new AssetManager(options);

Supported features:

1. Loading JSON and binary resources
2. Loading image and video resources
3. Selective resource downloading based on render level
4. Image/text template replacement
5. Font loading (via AssetManager.loadFontFamily)

3. Composition Composition

Manages data processing and rendering for animation playback:

const composition = new Composition(props, scene);

// Playback control
composition.play();
composition.pause();
composition.resume();

// Update
composition.update(deltaTime);

// Dispose
composition.dispose();

Main properties:

• renderFrame: The rendering data object for the current frame
• rootItem: The root element of the composition
• camera: The composition camera
• speed: Playback speed

4. VFX Element VFXItem

The base class for all effect elements, supporting component-based architecture:

// Get component
const component = item.getComponent(SpriteComponent);

// Iterate children
item.children.forEach(child => {
  // ...
});

// Transform operations
item.transform.setPosition(x, y, z);

Main properties:

• transform: Position, rotation, scale transforms
• components: Component list
• children: Child element list

5. Component System Component

Components are functional units attached to VFXItem:

abstract class Component extends EffectsObject {
  item: VFXItem;           // Owner element
  enabled: boolean;        // Whether enabled
  
  onAwake() {}             // Initialization
  onEnable() {}            // On enable
  onDisable() {}           // On disable
  onStart() {}             // Before first update
  onUpdate(dt: number) {}  // Per-frame update
  onLateUpdate(dt: number) {} // Late update
  onDestroy() {}           // On destroy
}

6. Renderer Component RendererComponent

The base class for all rendering components, responsible for adding renderable objects to render passes:

class RendererComponent extends Component {
  material: Material;      // Material
  materials: Material[];   // Material list
  priority: number;        // Render priority
  
  render(renderer: Renderer): void {}  // Render method
}

When a component is enabled, it is automatically added to the default render pass of RenderFrame.

7. Render Frame RenderFrame

The rendering data object for each frame, managing render passes and global uniforms:

interface RenderFrameOptions {
  camera: Camera,
  renderer: Renderer,
  globalVolume?: PostProcessVolume,
  postProcessingEnabled?: boolean,
}

Main features:

• Manages RenderPass list
• Stores camera properties
• Manages global uniform variables (GlobalUniforms)
• Supports post-processing (Bloom, ToneMapping)

Main methods:

• addMeshToDefaultRenderPass(mesh: RendererComponent): Add renderer component to default render pass
• removeMeshFromDefaultRenderPass(mesh: RendererComponent): Remove renderer component from default render pass

8. Render Pass RenderPass

Manages a group of objects to be rendered:

interface RenderPassClearAction {
  clearColor?: vec4,
  colorAction?: TextureLoadAction,
  clearDepth?: number,
  depthAction?: TextureLoadAction,
}

Features:

• Manages render object list
• Configures color, depth, stencil attachments
• Sets clear behavior

9. Geometry Geometry

Abstract class for managing vertex and index data:

const geometry = Geometry.create(engine, {
  attributes: {
    aPosition: { size: 3, data: positions },
    aTexCoord: { size: 2, data: texCoords },
  },
  indices: { data: indices },
  mode: WebGLRenderingContext.TRIANGLES,
});

// Update data
geometry.setAttributeData('aPosition', newPositions);
geometry.setAttributeSubData('aPosition', offset, partialData);
geometry.setIndexData(newIndices);
geometry.setDrawCount(count);

10. Material Material

Abstract class for managing shaders and render states:

const material = Material.create(engine, {
  shader: shaderSource,
  uniformValues: {
    uColor: [1, 0, 0, 1],
  },
});

// Set render states
material.blending = true;
material.depthTest = true;
material.depthMask = true;

Render state properties:

• blending: Color blending switch
• blendFunction: Blend function
• depthTest: Depth test switch
• depthMask: Depth write switch
• stencilTest: Stencil test switch
• culling: Back-face culling switch

11. Texture Texture

Abstract class for managing GPU texture resources:

// From image
const texture = await Texture.fromImage(url, engine);

// From video
const texture = await Texture.fromVideo(url, engine);

// From data
const texture = Texture.create(engine, {
  sourceType: TextureSourceType.data,
  data: {
    width: 256,
    height: 256,
    data: pixelData,
  },
});

Plugin System

Supports extending functionality through plugins:

import { registerPlugin } from '@galacean/effects-core';

registerPlugin('custom', CustomLoader);

Built-in plugins:

• sprite: Layer rendering
• particle: Particle system
• text: Text rendering
• interact: Interaction handling
• camera: Camera control

Installation

npm install @galacean/effects-core

Dependencies

• @galacean/effects-specification: Data specification definitions
• @galacean/effects-math: Math library

API Documentation