HoloScript Video Tutorial Skill

Your Mission

You create professional animated instructional videos for HoloScript and HoloLand using Remotion (React-based programmatic video) + Code Hike (animated syntax). Every video you generate should be accurate, visually polished, and rendereable headlessly via npm run render without human intervention.

HoloScript Architecture (Always Authoritative)

Repository Structure

• Monorepo at packages/* (pnpm workspaces; verify version in root package.json packageManager field — currently pnpm@9.15.9)
• Video package: packages/video-tutorials/ (new — created by this skill)
• TypeScript 5.3.3, Vitest, tsup, ESLint

Core Types (@holoscript/core)

• HoloComposition — root scene container (verify fields in packages/core/src/types/HoloScript.ts)
• HoloObjectDecl — scene objects with traits, position, children
• HoloLight — 6 types: directional, point, spot, hemisphere, ambient, area
• HoloCamera — perspective, orthographic, cinematic
• HoloUI, HoloZone, HoloTimeline, HoloLogic
• HoloNPC, HoloQuest, HoloAbility, HoloDialogue
• HoloStateMachine, HoloAchievement, HoloTalentTree
• HoloEnvironment, HoloEffects, HoloParticleSystem

Compiler Targets (SSOT-driven)

Do not hardcode target counts in tutorial scripts. Verify target keys from the live tool surface before recording — prefer the list_export_targets MCP tool, or enumerate the compilers from source:

# Live tool surface (canonical): the list_export_targets MCP tool
# Or enumerate compilers from source:
find packages/core/src -name "*Compiler.ts"

Representative targets for tutorial coverage:

.holo File Format

scene SceneName {
  object ObjectName {
    mesh: MeshType { property: value }
    material: MaterialType { color: #hex }
    position: [x, y, z]
    rotation: [x, y, z]
    scale: [x, y, z]
    traits: [TraitName, AnotherTrait]
  }
  light: DirectionalLight { intensity: 1.0, direction: [0, -1, 0] }
  camera: PerspectiveCamera { fov: 60, position: [0, 5, 10] }
}

Video Package Structure

packages/video-tutorials/
├── package.json              (@holoscript/video-tutorials)
├── remotion.config.ts
├── tsconfig.json
├── src/
│   ├── index.ts              (registerRoot)
│   ├── Root.tsx              (all Composition registrations)
│   ├── compositions/         (one file per tutorial video)
│   ├── content/              (Code Hike markdown files)
│   ├── components/           (reusable video components)
│   └── utils/theme.ts        (brand colors, fonts)
├── scripts/
│   ├── render-all.ts         (headless renderMedia runner)
│   ├── generate-narration.ts (ElevenLabs TTS pipeline)
│   └── record-cli-demo.py    (Asciinema automation)
└── out/                      (rendered MP4 output — gitignored)

Video Generation Workflow

Step 1: Plan the storyboard

Every video follows this structure:

1. Title card (3s): video title + HoloScript logo background
2. Problem statement (5-10s): what we're building / why
3. Code walkthrough (main): step-by-step with Code Hike annotations
4. Output demo (10-15s): show the compiled result
5. Summary (5s): recap + "learn more" pointer

Step 2: Write Code Hike markdown

Create src/content/{video-slug}.md:

## !!steps Start with a scene

We define the root scene container.

```holo !
// !focus
scene VirtualGarden {
}
```

!!steps Add the first object

Objects have mesh, material, and position.

scene VirtualGarden {
  // !focus
  object FlowerBed {
    mesh: Plane { scale: [4, 1, 4] }
    material: StandardMaterial { color: #7CFC00 }
    position: [0, 0, 0]
  }
}

### Step 3: Create Remotion composition
Create `src/compositions/{VideoName}.tsx`:
- Import the parsed markdown steps
- Use `<Sequence>` for each step
- Use `interpolate(frame, ...)` for smooth transitions
- Duration: 30fps × (desired seconds) = durationInFrames

### Step 4: Register in Root.tsx
Add `<Composition id="VideoName" component={VideoName} ... />` to Root.tsx

### Step 5: Preview
```bash
cd packages/video-tutorials
npm run dev
# Open http://localhost:3000

Step 6: Render

npm run render
# Or for a single composition:
npx remotion render --composition=UnityCompilerWalkthrough
# Output: out/unity-compiler-walkthrough.mp4

Code Hike Annotation Reference

Narration Script Pattern

When creating narrated videos:

1. Write narration script alongside Code Hike markdown
2. Format: [TIMING] Narration text
3. Save to src/content/{video-slug}-narration.txt
4. Generate audio: tsx scripts/generate-narration.ts --script {video-slug}
5. Audio saved to public/narration/{video-slug}.mp3
6. Reference in Remotion: <Audio src={staticFile('narration/{video-slug}.mp3')} />

Brand Guidelines

// src/utils/theme.ts
export const theme = {
  bg: '#0d1117', // GitHub dark background
  surface: '#161b22', // Card/panel background
  accent: '#58a6ff', // HoloScript blue
  accentGlow: '#1f6feb', // Glow effect color
  text: '#e6edf3', // Primary text
  textMuted: '#8b949e', // Secondary text
  success: '#3fb950', // Green (output/success)
  warning: '#d29922', // Yellow (warning)
  font: 'JetBrains Mono, Fira Code, monospace',
  titleFont: 'Inter, system-ui, sans-serif',
};

Quality Checklist

Before marking a video complete:

• Video is 1920×1080 at 30fps
• All code shown is syntactically valid .holo
• Compiler outputs shown match actual package behavior
• Steps are evenly paced (not too fast for viewer to read)
• Title card includes video title and "HoloScript" branding
• Output renders without error: npm run render

Compiler Target Coverage Plan (15 videos)

Generate these in order of community interest:

1. unity-compiler — Most requested (game dev audience)
2. godot-compiler — Second most popular (open source community)
3. babylon-compiler — Web3D audience
4. visionos-compiler — High novelty factor
5. urdf-compiler — Robotics audience
6. vrchat-compiler — VR creator community
7. webgpu-compiler — Web performance audience
8. r3f-compiler — React developer audience
9. ios-compiler — Mobile audience
10. android-compiler — Mobile audience
11. openxr-compiler — XR enterprise
12. dtdl-compiler — IoT/digital twin audience
13. unreal-compiler — AAA game dev
14. wasm-compiler — Performance-critical web
15. sdf-compiler — Simulation/robotics

Quick Prompt Templates

"Create a compiler demo video":

"Using the holoscript-video skill, create a Code Hike walkthrough video for the [TARGET] compiler. Show: (1) a .holo scene with a mesh object, (2) the compiler invocation in TypeScript, (3) the compiled output. Use 5 !!steps. Duration: 90 seconds at 30fps. Include a narration script."

"Create a syntax tutorial":

"Using the holoscript-video skill, create a beginner syntax introduction video. Cover: scene declaration, objects, meshes, materials, lights, and camera. Use 8 !!steps. Duration: 3 minutes."

"Create a full release tutorial":

"Using the holoscript-video skill, create a comprehensive tutorial video for the v{VERSION} release. Cover all new features. Use multi-agent pattern: first plan the storyboard, then generate components, then review."