stemstudio-uikit

name

stemstudio-uikit

description

Create UI elements for 3D game behaviors in Studio 3D using UIKit. Use when the user asks to add UI components like health bars, score displays, menus, HUDs, buttons, text labels, or any interactive interface elements to their game. UIKit provides flexbox-based 3D UI components (Container, Text, Image, Input, Fullscreen) with pointer event support. Examples include "add a health bar", "create a score display", "make a pause menu", "add a button to the object", or "create a HUD".

Studio 3D UIKit — Creating UI in Behaviors

Guide for creating 3D user interfaces inside Studio 3D behaviors using the UIKit library.

UI is created inside behavior scripts. Behaviors are managed via the stemstudio-behaviors skill (add, update, attach, detach).

Available Globals

Three globals are exposed to behavior scripts:

Global	Description
UIKit	UIKit namespace — Container, Text, Image, Input, Fullscreen, Svg, Video, reversePainterSortStable
UIKitPointerEvents	Pointer event system — initialize, update, registerRoot, unregisterRoot, deinitialize

Behavior Lifecycle for UI

this.init = function init(game) {
    // 1. Store game reference
    this.gameManager = game;

    // 2. Initialize pointer events (reference counted)
    UIKitPointerEvents.initialize(game);

    // 3. Enable clipping and transparent sort (required for UIKit)
    game.renderer.localClippingEnabled = true;
    game.renderer.setTransparentSort(UIKit.reversePainterSortStable);

    // 4. Create Fullscreen root (attached to camera for HUD)
    this.root = new UIKit.Fullscreen(game.renderer, {
        flexDirection: 'column',
        gap: 16,
        padding: 40,
        alignItems: 'center',
        justifyContent: 'center',
    });
    game.uiCamera.add(this.root);
}

this.onStart = function onStart() {
    // Build UI tree here — add children to this.root
}

this.update = function update(deltaTime) {
    // All three calls are required every frame
    UIKitPointerEvents.update(deltaTime);
}

this.dispose = function dispose() {
    if (this.root) {
        UIKitPointerEvents.unregisterRoot(this.root);
        if (this.root.parent) {
            this.root.parent.remove(this.root);
        }
        this.root.dispose();
        this.root = null;
    }
    UIKitPointerEvents.deinitialize();
}

Key Rules

1. Create the Fullscreen root in init() — it needs game.renderer and game.uiCamera
2. Call the pointer events update every frame — UIKitPointerEvents.update(deltaTime) in your update() method
3. Set renderer properties in init() — localClippingEnabled = true and setTransparentSort(UIKit.reversePainterSortStable)
4. Add root to UI camera — game.uiCamera.add(this.root) for Fullscreen HUD
5. Clean up in dispose() — unregister root, remove from parent, dispose, deinitialize

Attaching UI to Objects Instead of Camera

To attach UI to a specific 3D object (e.g., floating above an NPC) instead of as a fullscreen HUD:

this.onStart = function onStart() {
    const panel = new UIKit.Container({
        width: 200,
        height: 60,
        backgroundColor: 0x222222,
        backgroundOpacity: 0.8,
        borderRadius: 8,
        alignItems: 'center',
        justifyContent: 'center',
    });

    // Attach to the target object (the 3D object the behavior is on)
    this.target.add(panel);
    UIKitPointerEvents.registerRoot(panel);
}

UIKit Components

Container

The main building block. Supports flexbox layout, interaction states, and event handlers.

const panel = new UIKit.Container({
    // Size
    width: 300,
    height: 200,

    // Background
    backgroundColor: 0x333333,
    backgroundOpacity: 0.9,

    // Border
    borderRadius: 12,
    borderWidth: 2,
    borderColor: 0x666666,
    // Per-corner radius
    borderTopLeftRadius: 12,
    borderTopRightRadius: 12,
    borderBottomLeftRadius: 0,
    borderBottomRightRadius: 0,
    // Shorthand: borderTopRadius, borderBottomRadius
    // Per-side width
    borderTopWidth: 1,
    borderBottomWidth: 1,

    // Padding
    padding: 16,           // All sides
    paddingX: 16,          // Left + Right
    paddingY: 20,          // Top + Bottom
    paddingTop: 20,
    paddingBottom: 20,
    paddingLeft: 16,
    : ,

    
    : ,
    : ,
    : ,
    : ,
    : ,
    : ,    

    
    : ,    
    : ,   
    : ,       
    : ,       
    : , 
    : ,
    : ,
    : ,
    : ,
    : ,           

    
    : ,         

    
    : ,   
    : ,
    : ,
    : ,
    : ,
    : ,                   
    : ,

    
    : ,

    
    : , 
    : ,

    
    : ,
    : ,      

    
    : { : , :  },
    : { :  },

    
    :  {  },
    :  {},
    :  {},
    :  {},

    
    : { :  },
});

Text

Renders text in 3D space.

const label = new UIKit.Text({
    text: 'Hello World',
    fontSize: 32,
    fontWeight: 'bold',        // 'normal' | 'medium' | 'semi-bold' | 'bold' | 100-900
    color: 0xffffff,           // Hex number or 'white' string
    opacity: 1,

    // Alignment
    textAlign: 'center',       // 'left' | 'center' | 'right'
    verticalAlign: 'center',   // 'top' | 'center' | 'bottom'

    // Spacing
    letterSpacing: -0.4,
    lineHeight: '150%',        // Number, percentage string, or px string ('20px')

    // Overflow
    maxLines: 2,

    // Layout (Text also supports Container layout properties)
    marginTop: 8,
    padding: 8,
    backgroundColor: 0x000000,  // Text can have a background
});

Image

Displays images from URLs.

const img = new UIKit.Image({
    src: 'https://example.com/image.jpg',
    width: 250,
    height: 330,
    objectFit: 'cover',        // 'fill' | 'contain' | 'cover'
    borderRadius: 6,
    opacity: 1,
});

Svg

Renders inline SVG graphics.

const icon = new UIKit.Svg({
    width: 24,
    height: 24,
    color: 'white',
    content: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M15 6v12a3 3 0 1 0 3-3H6a3 3 0 1 0 3 3V6a3 3 0 1 0-3 3h12a3 3 0 1 0-3-3" /></svg>',
});

Video

Plays video content in 3D space.

const video = new UIKit.Video({
    src: 'https://example.com/video.mp4',
    width: 400,
    height: 225,
    autoplay: true,
    loop: true,
    muted: true,
    borderRadius: 8,
});

Input

Text input field.

const input = new UIKit.Input({
    width: 300,
    height: 40,
    placeholder: 'Enter name...',
    defaultValue: '',
    fontSize: 16,
    color: 'white',
    backgroundColor: 0x1e293b,
    hover: { backgroundColor: 0x334155 },
    borderRadius: 8,
    borderWidth: 1,
    borderColor: 0x475569,
    paddingX: 12,

    onValueChange: (value) => {
        console.log('Input changed:', value);
    },
});

Fullscreen

Camera-facing UI that fills the viewport. The primary component for HUDs and overlay menus.

// Created in init() — requires game.renderer
this.root = new UIKit.Fullscreen(game.renderer, {
    flexDirection: 'column',
    gap: 16,
    padding: 40,
    alignItems: 'center',
    justifyContent: 'center',
});
// Must be added to UI camera
game.uiCamera.add(this.root);

Updating Properties at Runtime

// Update single property
label.setProperties({ text: 'New Text' });

// Update multiple properties at once (more efficient)
container.setProperties({
    backgroundColor: 0xff0000,
    width: 300,
    opacity: 0.5,
    hover: { backgroundColor: 0xcc0000 },
});

UIKitPointerEvents API

Method	Description
initialize(game)	Initialize with game reference (reference counted — multiple behaviors can call this)
deinitialize()	Decrement ref count, full cleanup when ref count reaches 0
registerRoot(component)	Register a UI root for pointer events
unregisterRoot(component)	Unregister a UI root
update(deltaTime)	Process pointer events (call every frame)
isActive()	Check if the system is active
isInitialized()	Check if game ref exists
getRootCount()	Number of registered roots
getInitRefCount()	Current reference count
forceDispose()	Force immediate cleanup (use sparingly)

Complete Examples

Fullscreen HUD with Click Counter

this.init = function init(game) {
  this.gameManager = game;

  //required inits
  UIKitPointerEvents.initialize(game);
  game.renderer.localClippingEnabled = true;
  game.renderer.setTransparentSort(UIKit.reversePainterSortStable);

  this.root = new UIKit.Fullscreen(game.renderer, {
    flexDirection: 'column',
    gap: 16,
    padding: 40,
    alignItems: 'center',
    justifyContent: 'center',
  });
  game.uiCamera.add(this.root);

  //required
  UIKitPointerEvents.registerRoot(this.root);
}

this.onStart =  function onStart() {
  let clickCount = 0;
  const clickCountLabel = new .({
    : ,
    : ,
    : ,
  });
  ..(clickCountLabel);

   hoverButton =  .({
    : ,
    : ,
    : ,
    : { :  },
    : { :  },
    : ,
    : ,
    : ,
    : ,
    :  {
      clickCountLabel.({ :  });
    },
  });
  ..(hoverButton);

   hoverLabel =  .({
    : ,
    : ,
    : ,
  });
  hoverButton.(hoverLabel);
}

. =  () {
  
  .(deltaTime);
}

. =  () {
  
   (.) {
    .(.);
    ..();
    ..();
    . = ;
  }
  .();
}

Health Bar (Attached to Object)

let healthBar = null;
let healthFill = null;
let currentHealth = 100;
const maxHealth = 100;
const barWidth = 200;

this.init = function init(game) {
    UIKitPointerEvents.initialize(game);
}

this.onStart = function onStart() {
    healthBar = new UIKit.Container({
        width: barWidth,
        height: 20,
        backgroundColor: 0x333333,
        borderRadius: 4,
        overflow: 'hidden',
    });

    healthFill = new UIKit.Container({
        width: barWidth,
        height: '100%',
        backgroundColor: 0x44aa44,
    });

    healthBar.add(healthFill);
    this.target.add(healthBar);
    UIKitPointerEvents.registerRoot(healthBar);
}

this.update =  () {
    .(deltaTime);
}

. =  () {
     (healthBar) {
        .(healthBar);
        healthBar.();
        healthBar.();
        healthBar = ;
        healthFill = ;
    }
    .();
}

 () {
    currentHealth = .(, .(value, maxHealth));
     (healthFill) {
        healthFill.({
            : (currentHealth / maxHealth) * barWidth,
            : currentHealth >  ?  : ,
        });
    }
}

Notification Card with Expand/Collapse

this.init = function init(game) {
    this.gameManager = game;
    UIKitPointerEvents.initialize(game);
    game.renderer.localClippingEnabled = true;
    game.renderer.setTransparentSort(UIKit.reversePainterSortStable);

    this.root = new UIKit.Fullscreen(game.renderer, {
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'center',
    });
    game.uiCamera.add(this.root);

    UIKitPointerEvents.registerRoot(this.root);
}

this.onStart = function onStart() {
    let cardOpen = false;

    const wrapper = new UIKit.Container({
        flexDirection: 'column',
        width: ,
    });
    ..(wrapper);

    
     mainCard =  .({
        : ,
        : ,
        : ,
        : ,
        : ,
        :  {
            cardOpen = !cardOpen;
            detailPanel.({ : cardOpen ?  :  });
        },
    });
    wrapper.(mainCard);

    
     header =  .({
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
    });
    mainCard.(header);

    header.( .({ : , : , : , :  }));
    header.( .({ : , : , :  }));

    
     infoBar =  .({
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
    });
    mainCard.(infoBar);

    infoBar.( .({ : , : , :  }));

    
     detailPanel =  .({
        : ,
        : ,
        : ,
        : ,
        : -,
    });
    wrapper.(detailPanel);

     detailInner =  .({
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
    });
    detailPanel.(detailInner);

     items = [
        { : , :  },
        { : , :  },
        { : , :  },
    ];

    items.( {
         row =  .({ : , : , :  });
        detailInner.(row);

        row.( .({
            : , : , : ,
            : , : ,
        }));

         col =  .({ : , :  });
        row.(col);
        col.( .({ : item., : , :  }));
        col.( .({ : item., : , :  }));
    });
}

. =  () {
    .(deltaTime);
}

. =  () {
     (.) {
        .(.);
         (..) ...(.);
        ..();
        . = ;
    }
    .();
}

Scrollable List

this.onStart = function onStart() {
    const scrollContainer = new UIKit.Container({
        width: 300,
        height: 200,
        overflow: 'scroll',
        backgroundColor: 0x0f172a,
        borderRadius: 10,
        borderWidth: 1,
        borderColor: 0x334155,
        flexDirection: 'column',
        paddingY: 8,
    });
    this.root.add(scrollContainer);

    for (let i = 0; i < 20; i++) {
        const item = new UIKit.Container({
            width: '100%',
            height: 36,
            paddingX: 14,
            alignItems: 'center',
            hover: { backgroundColor: 0x1e293b },
            cursor: 'pointer',
            onClick:  .(),
        });
        scrollContainer.(item);

        item.( .({
            : ,
            : ,
            : ,
        }));
    }
}

Toggle Switch

function createToggle(onChange) {
    let isOn = false;

    const track = new UIKit.Container({
        width: 44,
        height: 24,
        borderRadius: 12,
        backgroundColor: 0xd4d4d8,
        cursor: 'pointer',
        justifyContent: 'center',
        onClick: (e) => {
            e.stopPropagation?.();
            isOn = !isOn;
            track.setProperties({ backgroundColor: isOn ? 0x18181b : 0xd4d4d8 });
            thumb.setProperties({ marginLeft: isOn ? 22 : 2 });
            if (onChange) onChange(isOn);
        },
    });

    const thumb = new UIKit.Container({
        width: 20,
        height: 20,
        borderRadius: 10,
        backgroundColor: 0xffffff,
        marginLeft: 2,
        alignSelf: 'center',
    });
    track.(thumb);

     track;
}

Stats Row

function createStatCard(title, value, change) {
    const card = new UIKit.Container({
        flexDirection: 'column',
        flexBasis: 0,
        flexGrow: 1,
        backgroundColor: 0xffffff,
        borderRadius: 8,
        borderWidth: 1,
        borderColor: 0xe4e4e7,
        padding: 24,
        gap: 4,
    });

    card.add(new UIKit.Text({ text: title, fontSize: 14, color: 0x71717a }));
    card.add(new UIKit.Text({ text: value, fontSize: 24, fontWeight: 'bold', color: 0x09090b }));
    card.add(new UIKit.Text({ text: change, fontSize: 12, color: 0x71717a }));

     card;
}


 row =  .({ : , : , :  });
..(row);

row.((, , ));
row.((, , ));
row.((, , ));

Horizontal Bar Chart

function createBarChart(data, maxValue, width, height) {
    const chart = new UIKit.Container({
        width, height,
        flexDirection: 'row',
        gap: 8,
        alignItems: 'flex-end',
    });

    data.forEach(item => {
        const col = new UIKit.Container({
            flexDirection: 'column',
            flexGrow: 1,
            alignItems: 'center',
            gap: 4,
            height: '100%',
            justifyContent: 'flex-end',
        });
        chart.add(col);

        col.add(new UIKit.Container({
            width: '100%',
            height: `${Math.min(1, item.value / maxValue) * 100}%`,
            backgroundColor: 0x18181b,
            borderTopLeftRadius: 4,
            borderTopRightRadius: 4,
        }));

        col.( .({
            : item.,
            : ,
            : ,
        }));
    });

     chart;
}

Auth Form (Login/Signup)

this.onStart = function onStart() {
    const form = new UIKit.Container({
        flexDirection: 'column',
        width: 350,
        gap: 24,
        alignItems: 'center',
    });
    this.root.add(form);

    form.add(new UIKit.Text({
        text: 'Create an account',
        fontSize: 24,
        fontWeight: 'bold',
        textAlign: 'center',
    }));

    form.add(new UIKit.Text({
        text: 'Enter your email below to create your account',
        fontSize: 14,
        color: 0x71717a,
        textAlign: 'center',
    }));

    const fields = new UIKit.Container({ flexDirection: 'column', gap: 8, :  });
    form.(fields);

    fields.( .({
        : ,
        : ,
    }));

    fields.( .({
        : ,
        : ,
        : ,
    }));

    
     submitBtn =  .({
        : ,
        : ,
        : ,
        : { :  },
        : ,
        : ,
        : ,
        : ,
        :  .(),
    });
    fields.(submitBtn);
    submitBtn.( .({ : , : , :  }));
}

Layout Patterns

Absolute Positioning

// Overlay button in top-right corner
const closeBtn = new UIKit.Container({
    positionType: 'absolute',
    positionRight: 16,
    positionTop: 16,
    width: 32,
    height: 32,
    borderRadius: 16,
    backgroundColor: 0x333333,
    alignItems: 'center',
    justifyContent: 'center',
    cursor: 'pointer',
});

Flex Push with marginLeft: 'auto'

// Push element to the right in a row
const row = new UIKit.Container({ flexDirection: 'row', width: '100%' });
row.add(new UIKit.Text({ text: 'Left' }));
row.add(new UIKit.Text({ text: 'Right', marginLeft: 'auto' }));

Two-Column Split Layout

const page = new UIKit.Container({
    width: '100%',
    height: '100%',
    flexDirection: 'row',
});

const leftPanel = new UIKit.Container({
    flexGrow: 1,
    flexBasis: 0,
    height: '100%',
    backgroundColor: 0x18181b,
    padding: 40,
    '*': { color: 'white' },
});
page.add(leftPanel);

const rightPanel = new UIKit.Container({
    flexGrow: 1,
    flexBasis: 0,
    height: '100%',
    padding: 40,
    alignItems: 'center',
    justifyContent: 'center',
});
page.add(rightPanel);

Scrollable Content Area

const scrollWrapper = new UIKit.Container({
    flexDirection: 'column',
    width: '100%',
    height: '100%',
    overflow: 'scroll',
});

Icon Grid with Wrapping

const grid = new UIKit.Container({
    width: '100%',
    flexGrow: 1,
    overflow: 'scroll',
    flexDirection: 'row',
    flexWrap: 'wrap',
    gap: 4,
    alignContent: 'flex-start',
});

Best Practices

1. Always set renderer properties — localClippingEnabled = true and setTransparentSort(UIKit.reversePainterSortStable) in init()
2. Update pointer events per frame — UIKitPointerEvents.update(deltaTime) in update()
3. Use cursor: 'pointer' on clickable elements
4. Use e.stopPropagation?.() in nested onClick handlers to prevent event bubbling
5. Batch updates — setProperties() with multiple properties at once
6. Use pointerEvents: 'none' on decorative elements to skip hit testing
7. Use overflow: 'hidden' for containers with fill bars
8. Clean up in dispose() — unregister roots, remove from parent, dispose, clear references
9. Colors — use hex numbers (0x2563eb) or strings ('white') — CSS color names work too

Troubleshooting

UI Not Visible

1. Did you call game.renderer.localClippingEnabled = true?
2. Did you call game.renderer.setTransparentSort(UIKit.reversePainterSortStable)?
3. Is the Fullscreen root added to game.uiCamera?
4. Is 'visibility' set to 'visible'?

Interactions Not Working

1. Is UIKitPointerEvents.initialize(game) called in init()?
2. Is UIKitPointerEvents.update(deltaTime) called every frame?
3. Is UIKitPointerEvents.registerRoot(root) called for each root?
4. Is the cursor: 'pointer' set on clickable elements?
5. Is pointerEvents not set to 'none' on the element?

Animations / Expand-Collapse

• Animate by changing height (e.g., 0 to 300) with overflow: 'hidden'
• Use visibility property with values "visible" or "hidden" to show/hide elements
• Use setProperties() to update at runtime

Verification

• Confirm UI visible: Check that localClippingEnabled = true and setTransparentSort are set in init()
• Confirm interactions work: Check that UIKitPointerEvents.initialize(game), registerRoot(), and update(deltaTime) are all called
• Test in play mode: UI only renders during play mode. Enter play mode to see the UI.
• Check component tree: Add console.log in onStart to verify components are created and added to root

When Things Go Wrong

• "UI not visible" → Check all 3 required init steps: localClippingEnabled, setTransparentSort, and root added to game.uiCamera
• "Clicks not working" → Verify UIKitPointerEvents.initialize(game) in init(), registerRoot(root) after creating root, and update(deltaTime) called every frame
• "UI overlaps incorrectly" → Use zIndex to control layer order. Fullscreen roots render in creation order.
• "Text not showing" → Ensure color is set (defaults may be transparent). Use hex numbers (0xffffff) or strings ('white').
• "Scroll not working" → Set overflow: 'scroll' on the container. Content must exceed container height/width.
• "Memory leak" → Ensure dispose() calls unregisterRoot, removeFromParent, dispose() on root, and deinitialize().
• Never retry the same failing approach — check initialization order and required calls first.

Safety Guardrails

• Always clean up in dispose() — unregister roots, remove from parent, dispose, clear references
• Use e.stopPropagation?.() in nested onClick handlers to prevent unintended event bubbling
• Set pointerEvents: 'none' on decorative/non-interactive elements
• Keep UI behavior code focused — complex game logic should be in separate behaviors that communicate via game.behaviorManager.sendEventToObjectBehaviors

See Also

• stemstudio-behaviors — UIKit code lives inside behavior scripts
• stemstudio-audio — Sound feedback on UI interactions
• stemstudio-game-design — HUD and menu design patterns for different game genres