holoscript-video

name: holoscript-video description: > Generate instructional video components using Remotion and Code Hike for HoloScript and HoloLand repositories. Use when asked to: create tutorial videos, build code walkthroughs, demo compiler outputs, explain .holo syntax, showcase export targets, or produce any educational video content about HoloScript. Auto-triggers on phrases: "create a video", "make a tutorial", "walkthrough", "demo video", "instructional", "screencast". allowed-tools: Read, Write, Edit, Bash, Glob, Grep

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, pnpm@8.12.0)
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 source before recording:

grep -n "export enum ExportTarget" -A 200 packages/core/src/compiler/CircuitBreaker.ts

Representative targets for tutorial coverage:

Target	Output Type	Use Case
Unity	string (C# MonoBehaviour)	Unity game engine
Unreal	{ headerFile, sourceFile }	Unreal Engine (C++ header + source)
Godot	string (GDScript)	Godot game engine
Babylon	string (TypeScript)	Babylon.js WebGL
WebGPU	string (TypeScript)	Raw WebGPU API
VRChat	{ mainScript, avatarDescriptor, animatorController }	VRChat worlds
URDF	string (XML)	Robot description for ROS
SDF	string (XML)	Simulation Description Format
PlayCanvas	string (JS)	PlayCanvas engine
DTDL	string (JSON)	Digital Twin Definition Language
VisionOS	string (Swift)	Apple Vision Pro
iOS	{ viewFile, controllerFile }	iOS/iPadOS UIKit
Android	{ activityFile, layoutFile }	Android XML + Java
Android-XR	string	Android XR platform
OpenXR	string (C++)	OpenXR cross-platform XR
R3F	string (TypeScript)	React Three Fiber
WASM	{ wasmModule, jsBindings }	WebAssembly
USD	string	Universal Scene Description

.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:

Title card (3s): video title + HoloScript logo background
Problem statement (5-10s): what we're building / why
Code walkthrough (main): step-by-step with Code Hike annotations
Output demo (10-15s): show the compiled result
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

Annotation	Effect
`// !focus`	Dims all other lines, highlights this one
`// !mark`	Yellow highlight box around line
`// !mark[/regex/]`	Highlight matching text inline
`// !callout[/text/]` text	Speech bubble callout
`// !add`	Green "added line" diff style
`// !remove`	Red "removed line" diff style
`// !collapse`	Collapses block to single line

Narration Script Pattern

When creating narrated videos:

Write narration script alongside Code Hike markdown
Format: [TIMING] Narration text
Save to src/content/{video-slug}-narration.txt
Generate audio: tsx scripts/generate-narration.ts --script {video-slug}
Audio saved to public/narration/{video-slug}.mp3
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:

unity-compiler — Most requested (game dev audience)
godot-compiler — Second most popular (open source community)
babylon-compiler — Web3D audience
visionos-compiler — High novelty factor
urdf-compiler — Robotics audience
vrchat-compiler — VR creator community
webgpu-compiler — Web performance audience
r3f-compiler — React developer audience
ios-compiler — Mobile audience
android-compiler — Mobile audience
openxr-compiler — XR enterprise
dtdl-compiler — IoT/digital twin audience
unreal-compiler — AAA game dev
wasm-compiler — Performance-critical web
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."