IWSDK UI Panel Development Workflow

This skill teaches the efficient workflow for developing UI panels in IWSDK applications using temporary ScreenSpace positioning and backdrop techniques.

Quick Iteration Workflow

When working on a UI panel, follow these steps for rapid iteration:

1. Add Temporary ScreenSpace Component

Temporarily add the ScreenSpace component to your PanelUI entity to make it fill the 2D screen during development:

import { ScreenSpace } from '@iwsdk/core';

world
  .createTransformEntity(panelHolder)
  .addComponent(PanelUI, {
    config: '/ui/your-panel.json',
    maxWidth: 1.0,
    maxHeight: 0.5,
  })
  .addComponent(ScreenSpace, {
    width: '90vw', // Fill 90% of viewport width
    height: '90vh', // Fill 90% of viewport height
    top: '5vh', // Center with 5% margins
    left: '5vw',
  });

Important: This is temporary for development only. Remove before production.

2. Create a Clean Backdrop

Create a solid color backdrop far from your gameplay area for clean UI visibility:

const backdrop = new Mesh(
  new BoxGeometry(20, 20, 0.1),
  new MeshBasicMaterial({ color: 0x1a1a2e }),
);
backdrop.position.set(0, 0, -50); // Far from gameplay
scene.add(backdrop);

3. Position Camera Close to Backdrop

Move the camera very close to the backdrop (within 0.5m) to eliminate background distractions:

// Position camera very close to backdrop for clean UI development
camera.position.set(0, 0, -49.5); // Just 0.5m from backdrop at z=-50
camera.lookAt(0, 0, -50);

Why close? The backdrop must fill the entire field of view to block out the 3D scene. Being far away (50m) won't work - you'll still see the environment around the edges.

4. Iterate with Screenshots

Now you can rapidly iterate on your UI:

1. Make changes to your .uikitml file
2. Take a screenshot to see the result against a clean backdrop
3. The UI fills most of the screen, making it easy to see details like:
   • Border colors and thickness
   • Padding and spacing
   • Text alignment and sizing
   • Color contrast
   • Overall layout

The ScreenSpace component makes the panel "follow" the camera, so it appears as a 2D overlay on your backdrop.

5. Test in VR

When you enter VR mode:

• The ScreenSpace component automatically detaches the panel from the camera
• The panel returns to its original 3D world space position
• Your gameplay is unaffected

This dual-mode behavior is handled automatically by the ScreenSpaceUISystem.

Understanding UIKit Size Signals

UIKit components expose size information through signals. Log these to debug layout issues:

const document = PanelDocument.data.document[entity.index];

console.log('computedSize:', document.computedSize); // Intrinsic size in cm
console.log('targetSize:', document.targetSize); // Target size in meters
console.log('rootElement.size.value:', document.rootElement?.size?.value);
console.log('document.scale:', document.scale); // Applied scale

Understanding the output:

• computedSize: UIKit's rendered size in centimeters (based on your CSS)
• targetSize: The requested size in meters (from PanelUI maxWidth/maxHeight or ScreenSpace constraints)
• document.scale: Uniform scale factor applied to fit target while preserving aspect ratio

Example output:

computedSize: { width: 100, height: 50 }         // 100cm × 50cm
targetSize: { width: 0.274, height: 0.168 }      // 0.274m × 0.168m
document.scale: { x: 0.274, y: 0.274, z: 0.274 } // Scaled down by 0.274x

ScreenSpace Component Reference

The ScreenSpace component positions panels using CSS-like properties:

.addComponent(ScreenSpace, {
  width: '90vw',      // CSS size: px, vw, vh, %, auto
  height: '90vh',     // CSS size: px, vw, vh, %, auto
  top: '5vh',         // CSS position: px, %, vh, auto
  bottom: 'auto',     // CSS position: px, %, vh, auto

…