Introduction

Illutions is an event-driven engine for interactive 3D applications in the browser. It uses Three.js to render the scene. You can build simple applications quickly and develop larger, more complex applications with components, models, controls, animation, audio, and state logic.

Why use Illutions?

• Powerful state machine:
  Use XState to coordinate events, actions, and state transitions.
• Precise animation control:
  Layer and blend clips, control loops and transitions, and use GSAP for fades and speed changes.
• Small initial download:
  Optional modules load only when their features are used.
• Modern graphics APIs:
  Render with WebGPU where supported, with automatic fallback to WebGL.
• Enhanced image quality:
  Post-processing adds anti-aliasing, ambient occlusion with SSAO/GTAO, indirect illumination with WebGPU SSGI, and screen-space reflections.
• Individual graphics to each device:
  Adaptive Graphics adjusts visual quality to the hardware's performance.
• Eco Mode:
  Reduces rendering work to lower power use and help preserve battery life.
• Complex 3D scenes:
  Load GLTF/GLB scenes with geometry, materials, textures, and animation clips.
• Fast visual startup:
  Progressive loading displays the first model level while higher-quality geometry and textures load; background maps update in stages.
• Interact with 3D:
  Users interact with scene objects and Web Components. Raycasting and events connect the scene with the page.
• Live engine tuning:
  The Inspector lets you adjust supported Illutions settings while the application runs.
• Performance at a glance:
  The Info Bar shows the renderer API, FPS, CPU/update time, and rendering statistics in real time.

How can you use Illutions?

Illutions supports three API levels. You can use one level or combine them in the same application:

• High-Level API:
  Configure common features and use ready-made methods and controls.
• Mid-Level API:
  Add custom behavior with components, lifecycle hooks, and event listeners.
• Low-Level API:
  Access public engine systems for advanced integrations and direct control.

See API Levels to choose the right level for each part of your application.

What should you know?

You need JavaScript or TypeScript to build an application. Three.js knowledge helps with advanced scene work. XState and state machine concepts are useful for state-driven behavior. Experience with a 3D creation tool such as Blender or Unity helps you prepare scenes, models, materials, and animations.

Where to go next

1. Basics explains the parts of an application.
2. First application shows a small cube example.
3. Project Structure describes the files and directories of a typical project.
4. Installation and setup shows how to prepare a project.

Use the API reference when you need details about a class, method, or setting.