Summon Core API Reference

The sigil-summon module is the core engine (or "summoner") responsible for interpreting the scene graph and managing the rendering lifecycle. It also provides SSR (Server-Side Rendering) support for screen-space effects.

Screen-Space Effects (SSR)

SigilEffectCanvas

The primary composable for rendering screen-space shader effects with SSR support.

@Composable
fun SigilEffectCanvas(
    id: String = "sigil-effect-canvas",
    width: String = "100%",
    height: String = "100%",
    config: SigilCanvasConfig = SigilCanvasConfig(),
    interactions: InteractionConfig = InteractionConfig(),
    fallback: @Composable () -> String = { "" },
    content: @Composable () -> String
): String

Parameters:

• id: Unique ID for the canvas element
• width: CSS width of the canvas
• height: CSS height of the canvas
• config: Canvas configuration (device pixel ratio, power preference, fallbacks)
• interactions: Interaction configuration (mouse tracking, etc.)
• fallback: Composable to render for noscript/no-WebGPU fallback
• content: Composable lambda containing SigilEffect() calls

Server Output: On the JVM, renders an HTML canvas with effect data embedded in the data-sigil-effects attribute as JSON.

SigilEffect

Registers a shader effect within a SigilEffectCanvas.

@Composable
fun SigilEffect(effect: ShaderEffectData): String

CustomShaderEffect

Convenience function to create and register a custom shader effect.

@Composable
fun CustomShaderEffect(
    id: String,
    fragmentShader: String,           // WGSL shader code
    name: String? = null,
    timeScale: Float = 1f,
    enableMouseInteraction: Boolean = false,
    uniforms: Map<String, UniformValue> = emptyMap()
): String

EffectSummonContext

Context registry for Sigil effect composition. Tracks registered effects during composition for serialization (server) or hydration (client).

class EffectSummonContext {
    val effects: List<ShaderEffectData>    // Collected effects
    val canvasConfig: SigilCanvasConfig
    val interactionConfig: InteractionConfig
    
    fun registerEffect(effect: ShaderEffectData)
    fun buildComposerData(id: String): EffectComposerData
    
    companion object {
        fun current(): EffectSummonContext
        fun createServerContext(): EffectSummonContext
        fun createClientContext(): EffectSummonContext
        fun <R> withContext(context: EffectSummonContext, block: () -> R): R
    }
}

3D Scene Components

SigilSummonContext

A context class that holds the current state of the engine, including the active scene, renderer, and camera.

MateriaCanvas (Core)

The platform-agnostic implementation of the canvas handling logic. It bridges the gap between the abstract scene graph and the platform-specific graphics context (JVM AWT, Android Surface, WebGL/WebGPU).

SigilText

Registers mesh text inside a MateriaCanvas scene. The browser hydrator renders this as Materia TextGeometry, not as DOM overlay text.

SigilText(
    text = "Truck A",
    position = listOf(0f, 2f, 0f),
    size = 0.4f,
    color = 0xFFFFFFFF.toInt(),
    facingMode = TextFacingMode.BILLBOARD
)

When fontUrl is omitted, Sigil loads /sigil-default-font.json from the bundled static assets. Custom fontUrl values should point to a Three.js-style typeface JSON file.

SigilScreenLayer

Renders normal Sigil primitives and text through a second orthographic Materia pass. The layer remains inside the WebGL/WebGPU canvas and receives pointer input before the world scene.

SigilScreenLayer(
    desktop = ScreenLayoutData(ScreenAnchor.TOP_RIGHT, 24f, 24f),
    mobile = ScreenLayoutData(ScreenAnchor.BOTTOM_CENTER, 0f, 16f),
    mobileBreakpoint = 640
) {
    SigilPlane(width = 280f, height = 120f, color = 0xEE111820.toInt())
    SigilText(text = "MANIFEST", size = 18f)
    SigilFrameStatsText(position = listOf(0f, -28f, 1f))
}

ScreenLayoutData supports nine anchors, inward pixel offsets, scale, and visibility. Desktop and mobile layouts switch without replacing the canvas.

Audio

SigilAudio creates buffered or procedural Materia audio. SigilSoundBus configures a named gain bus and can restore its volume from local storage or a cookie.

SigilSoundBus(bus = "ambience", volume = 0.25f, storageKey = "sound-mode")
SigilAudio(
    id = "warehouse-bed",
    procedural = ProceduralAudioData(noiseGain = 0.3f, oscillatorGain = 0.05f),
    bus = "ambience",
    loop = true
)

Audio begins after browser gesture unlock and automatically suspends while the page is hidden.

Renderer Configuration

SceneConfig accepts an explicit RendererPreference and optional AdaptiveResolutionData. Adaptive resolution reports smoothed statistics and changes the canvas backing DPR without changing its layout size.

SceneConfig(
    rendererPreference = RendererPreference.AUTO,
    adaptiveResolution = AdaptiveResolutionData(
        targetFps = 55f,
        minimumDpr = 0.75f,
        maximumDpr = 1.25f
    )
)

Scene-event bindings may include optimisticPatch, requestKey, and suppressWhilePending. This gives immediate in-canvas feedback and prevents duplicate server requests while the authoritative callback is pending.

Client-Side Hydration

SigilEffectHydrator

Handles client-side hydration of effect canvases rendered on the server.

object SigilEffectHydratorJs {
    fun hydrate(canvasId: String)
    fun isWebGPUAvailable(): Boolean
    fun isWebGLAvailable(): Boolean
    fun getAvailableRenderer(): String  // "webgpu" | "webgl" | "css"
}

The hydrator:

1. Reads effect data from the data-sigil-effects attribute
2. Parses config from data-sigil-config and data-sigil-interactions
3. Creates WebGPU effect passes (or WebGL fallback)
4. Starts the render loop with resize handling

Logic

Sigil uses a "Summon" concept where nodes are summoned into existence.

• Components: Functions that create and configure specific types of nodes (Geometry, Lights, Camera).
• Context: Manages the dependency injection and state for the rendering pipeline.