Skip to content

OVERVIEW.md

Latest commit

 

History

History
304 lines (224 loc) · 9.7 KB

OVERVIEW.md

File metadata and controls

304 lines (224 loc) · 9.7 KB
Raw

HoloScript API Reference

Version: see repository package manifests | License: MIT | GitHub

HoloScript is a general-purpose semantic systems programming language with AI-native tooling and declarative, imperative, reactive, and compositional surfaces. Interfaces, spatial scenes, services, agents, runtimes, simulations, and device workflows are programs in the same language. Compile targets and tool inventory change over time; verify them from ExportTarget and live MCP health instead of copying a count.

Quick Navigation

Package Description Key APIs
@holoscript/core Runtime, parser, traits HoloScriptPlusParser, TraitHandler, ReactiveState
@holoscript/cli Command-line tools compile, validate, build
@holoscript/mcp-server AI agent integration handleTool, MCP protocol
@holoscript/security-sandbox VM isolation HoloScriptSandbox, executeSafely
@holoscript/ai-validator Hallucination detection AIValidator, validateAICode
@holoscript/comparative-benchmarks Performance comparison ComparativeBenchmarks, runComparativeBenchmarks
@holoscript/partner-sdk Partner integrations PartnerSDK, WebhookHandler

Core Concepts

1. HoloScript Language

HoloScript supports compiler-visible declarations and traits that define program behavior and effects. This example exercises the spatial composition surface:

sphere {
  @color(blue)           // Visual trait
  @position(0, 2, 0)    // Spatial trait
  @physics               // Physics simulation
  @grabbable             // VR interaction
  @networked             // Multi-user sync

  cube {
    @color(red)
    @scale(0.5, 0.5, 0.5)
  }
}

2. Trait System

Traits are the building blocks of HoloScript objects. Each trait:

  • Has a name (e.g., @grabbable)
  • Accepts optional parameters (e.g., @color(red))
  • Implements lifecycle hooks (onAttach, onUpdate, onEvent, onDetach)

Trait Categories:

Category Examples
Interaction @grabbable, @clickable, @hoverable, @throwable
Physics @physics, @rigidbody, @collidable, @gravity
Visual @color, @material, @glowing, @emissive, @shader
Networking @networked, @synced, @persistent, @owned
Spatial @position, @rotation, @scale, @anchor
Audio @spatial_audio, @ambient, @hrtf
AI/ML @llm_agent, @behavior_tree, @npc_brain
XR @hand_tracking, @eye_tracked, @body_tracking

3. Lifecycle Hooks

interface TraitHandler<TConfig> {
  name: VRTraitName;
  defaultConfig: TConfig;

  onAttach?: (node, config, context) => void; // Called when trait is added
  onDetach?: (node, config, context) => void; // Called when trait is removed
  onUpdate?: (node, config, context, delta) => void; // Called each frame
  onEvent?: (node, config, context, event) => void; // Called on events
}

4. Creating Custom Traits

import { TraitHandler, TraitContext } from '@holoscript/core';

const MyCustomTrait: TraitHandler<{ intensity: number }> = {
  name: '@my_custom_trait' as any,
  defaultConfig: { intensity: 1.0 },

  onAttach(node, config, context) {
    // Initialize your trait
    console.log(`Attached with intensity: ${config.intensity}`);
    context.emit('trait_attached', { traitName: '@my_custom_trait' });
  },

  onUpdate(node, config, context, delta) {
    // Update every frame (delta in seconds)
    const pulse = Math.sin(Date.now() * 0.001) * config.intensity;
    // Apply pulse effect...
  },

  onEvent(node, config, context, event) {
    if (event.type === 'grab') {
      config.intensity *= 2; // Double intensity on grab
    }
  },

  onDetach(node, config, context) {
    // Cleanup
    console.log('Trait detached');
  },
};

Core Package (@holoscript/core) {#core}

Parser API

import { HoloScriptPlusParser, parseHolo, parseHoloStrict } from '@holoscript/core';

// Quick parse (lenient)
const ast = parseHolo(holoScriptCode);

// Strict parse (throws on any error)
const strictAst = parseHoloStrict(holoScriptCode);

// Parser instance (for custom options)
const parser = new HoloScriptPlusParser();
const result = parser.parse(code, { strict: true });

Runtime API

import { HoloScriptPlusRuntimeImpl } from '@holoscript/core';

const runtime = new HoloScriptPlusRuntimeImpl(ast, {
  renderer: myRenderer,
  vrEnabled: true,
  companions: { robot: robotAPI },
});

// Mount the scene
await runtime.mount(document.getElementById('scene'));

// Lifecycle
runtime.update(deltaTime);
runtime.unmount();

Reactive State API

import { createState, ReactiveState } from '@holoscript/core';

const state = createState({ score: 0, lives: 3 });

// Subscribe to changes
state.subscribe('score', (newValue) => {
  console.log('Score changed:', newValue);
});

// Update state
state.set('score', state.get('score') + 100);

Security Sandbox (@holoscript/security-sandbox) {#security-sandbox}

Provides isolated VM execution for untrusted code.

import { HoloScriptSandbox, executeSafely } from '@holoscript/security-sandbox';

const sandbox = new HoloScriptSandbox({
  timeout: 3000, // 3 second limit
  memoryLimit: 64, // 64 MB limit
  enableLogging: true, // Audit trail
});

// Execute AI-generated code safely
const result = await sandbox.executeHoloScript(aiCode, {
  source: 'ai-generated',
});

if (!result.success) {
  console.error(`[${result.error.type}] ${result.error.message}`);
}

// Review security logs
const stats = sandbox.getSecurityStats();
console.log(`Executed: ${stats.executed}, Rejected: ${stats.rejected}`);

AI Validator (@holoscript/ai-validator) {#ai-validator}

Validates AI-generated HoloScript for hallucinations and syntax errors.

import { AIValidator, validateAICode } from '@holoscript/ai-validator';

const validator = new AIValidator({
  provider: 'anthropic',
  hallucinationThreshold: 50,
  strict: false,
});

const result = await validator.validate(aiGeneratedCode);

if (!result.valid) {
  // Use errors to regenerate with LLM
  const feedback = result.errors.map((e) => `${e.message}\n  Fix: ${e.suggestion}`);
  console.log('Feedback for LLM:', feedback.join('\n'));
}

// Hallucination score: 0-100 (higher = more suspicious)
console.log(`Hallucination score: ${result.metadata.hallucinationScore}`);

Comparative Benchmarks (@holoscript/comparative-benchmarks) {#benchmarks}

Performance comparison against Unity and glTF runtimes.

import { runComparativeBenchmarks } from '@holoscript/comparative-benchmarks';

const { results, report } = await runComparativeBenchmarks({
  iterations: 1000,
  targets: ['holoscript', 'unity', 'gltf'],
});

// Inspect the generated report before quoting benchmark results.
// Do not reuse cached win counts or speedup claims in public copy.
console.log(report);

MCP Server (@holoscript/mcp-server) {#mcp-server}

Model Context Protocol server for AI agent integration (tool inventory is live; verify via /health).

// MCP tools available:
// parse_hs, parse_holo, validate_holoscript
// list_traits, explain_trait, suggest_traits
// generate_object, generate_scene
// get_syntax_reference, get_examples
// explain_code, analyze_code
// compile_target, list_targets
// Discover the current list with tools/list or the /health endpoint.

Configuration: Add to Claude/Cursor MCP config:

{
  "mcpServers": {
    "holoscript": {
      "command": "npx",
      "args": ["-y", "@holoscript/mcp-server"]
    }
  }
}

Export Targets

HoloScript compiles to registered platforms (see ExportTarget for canonical keys):

Platform Package Use Case
WebXR @holoscript/adapter-webxr Browser VR/AR
Unity @holoscript/adapter-unity Unity Engine
Unreal @holoscript/adapter-unreal Unreal Engine
Godot @holoscript/adapter-godot Godot Engine
Three.js @holoscript/adapter-threejs Web 3D
Babylon.js @holoscript/adapter-babylonjs WebGL
URDF @holoscript/adapter-urdf ROS Robotics
SDF @holoscript/adapter-sdf Gazebo Sim
glTF @holoscript/adapter-gltf 3D Interchange
FBX @holoscript/adapter-fbx Autodesk
OBJ @holoscript/adapter-obj Universal 3D

Getting Help

API reference generated with TypeDoc. HoloScript package versions live in the repository manifests.