@holoscript/core

The semantic engine at the heart of HoloScript. Traits describe any domain entity — spatial, AI, services, IoT — and the compiler fleet translates them to platform-specific code. Read the V6 Vision →

Core parser, AST, compiler infrastructure, and trait system.

Installation

npm install @holoscript/core

Usage

// Parse HoloScript+ files (.hsplus)
import { HoloScriptPlusParser } from '@holoscript/core';

const parser = new HoloScriptPlusParser();
const result = parser.parse(source);

// Parse .holo composition files
import { HoloCompositionParser } from '@holoscript/core';

const holoParser = new HoloCompositionParser();
const composition = holoParser.parse(source);

// Compile to a specific target
import { UnityCompiler } from '@holoscript/core';

const compiler = new UnityCompiler();
const output = compiler.compile(composition.ast);

Features

• Multi-format Parser - Supports .hs, .hsplus, and .holo files
• Complete AST - Full abstract syntax tree representation
• Validation - Comprehensive error checking with recovery
• Compile Targets - R3F generated TSX, Unity, Unreal, Godot, iOS, Android, Vision Pro, WebGPU, WASM, VRChat, OpenXR, URDF, DTDL, SDF, and more; verify live targets via the ExportTarget enum and MCP health.
• Traits - Modularized across category files covering VR interactions, physics, networking, AI, scripting, automation, animation, nature, magic, sci-fi, emotions, and more; pull live counts from the repository.
• AI Integration - Adapters for OpenAI, Anthropic, Gemini, Ollama, and more
• Reactive State - reactive(), computed(), effect(), bind()

Parsers

| Parser | File Types | Use Case | | ----------------------- | ---------- | --------------------------------------- | | HoloScriptPlusParser | .hsplus | Extended syntax with TypeScript modules | | HoloCompositionParser | .holo | Scene-centric composition files | | HoloScript2DParser | .hs | Basic logic and protocols | | HoloScriptParser | .hs | Standard semantic parser |

Compilers (verify live targets via health + ExportTarget enum)

| Compiler | Target | Output | | ------------------------ | ------------------------- | ------------------ | | UnityCompiler | Unity Engine | C# + Prefab | | UnrealCompiler | Unreal Engine 5 | C++ + Blueprint | | GodotCompiler | Godot 4 | GDScript + .tscn | | SceneIRCompiler + emitSceneIRTsx | React Three Fiber | SceneIR + generated TSX shell | | OpenXRCompiler | OpenXR Standard | C++ | | VRChatCompiler | VRChat | UdonSharp C# | | VisionOSCompiler | Apple Vision Pro | Swift | | AndroidXRCompiler | Android XR | Kotlin | | IOSCompiler | iOS / ARKit | Swift | | AndroidCompiler | Android / ARCore | Kotlin | | WASMCompiler | WebAssembly | .wasm + .js | | WebGPUCompiler | WebGPU Compute | WGSL + TypeScript | | URDFCompiler | Robotics (URDF) | .urdf XML | | SDFCompiler | Gazebo SDF simulation XML | .sdf XML | | DTDLCompiler | Digital Twins | JSON-LD | | StateCompiler | Reactive State | JSON | | A2AAgentCardCompiler | A2A Agent Cards | JSON | | NIRCompiler | Neuromorphic IR | JSON | | AIGlassesCompiler | AI Glasses | Kotlin Compose | | GLTFPipeline | glTF | .glb / .gltf | | NFTMarketplaceCompiler | NFT Marketplace | Solidity | | USDPhysicsCompiler | USD Physics | .usda | | TSLCompiler | Trait Shader Language | WGSL + TS pipeline | | SCMCompiler | Structural Causal Model | JSON DAG | | QuiltCompiler | Looking Glass Hologram | Multi-view PNG | | MVHEVCCompiler | MV-HEVC Hologram | Swift + .mov |

Trait System

VR traits are modularized under src/traits/constants/:

| Category | File | Traits | | --------------- | ------------------------ | --------------------------------------- | | Core VR | core-vr-interaction.ts | grabbable, throwable, pointable, ... | | Humanoid | humanoid-avatar.ts | skeleton, body, face, ... | | Game Mechanics | game-mechanics.ts | collectible, destructible, healable, .. | | Magic & Fantasy | magic-fantasy.ts | enchantable, cursed, blessed, ... | | Animals | animals.ts | cat, dog, horse, dragon, ... | | ... | 58 more categories | See src/traits/constants/index.ts |

Import individual categories or the combined set:

import { VR_TRAITS } from '@holoscript/core';
import { AUDIO_TRAITS } from '@holoscript/core'; // Just audio traits
import { MAGIC_FANTASY_TRAITS } from '@holoscript/core'; // Just magic/fantasy

Language Features

HoloScript v4.1 adds five production-ready language features. See LANGUAGE_FEATURES.md for the full reference.

Module System (@import / @export)

@import { PhysicsSystem, Gravity } from './physics.hs'
@import * as UI from './ui-components.hs'

@export PhysicsSystem

Trait Composition

// Compose multiple traits into one named trait
@HoverVehicle = @physics + @navmesh + @propulsion
@Warrior = @combat + @inventory + @stats

import { TraitCompositionCompiler, TraitComposer } from '@holoscript/core';

// Low-level API
const compiler = new TraitCompositionCompiler();
const [hovercraft] = compiler.compile(
  [{ name: 'Hovercraft', components: ['physics', 'navmesh'], overrides: { gravity: 0.1 } }],
  (name) => registry.get(name),
  traitGraph
);

// High-level composer (with lifecycle dispatch)
const composer = new TraitComposer(graph);
const result = composer.compose('Warrior', handlers, ['combat', 'inventory', 'stats']);
// result.handler.onAttach dispatches to all in order; onDetach is reversed

Reactive State

@state {
  hp: 100,
  shield: 50,
}

import { reactive, computed, effect } from '@holoscript/core';

const state = reactive({ hp: 100 });
const isAlive = computed(() => state.hp > 0);
effect(() => console.log('HP changed:', state.hp));

LLM Agent Trait

@llm_agent {
  model: "gpt-4",
  system_prompt: "You are a game NPC",
  tools: [{ name: "move", ... }],
  bounded_autonomy: true,
  max_actions_per_turn: 3,
}

Gaussian Splat Trait

@gaussian_splat {
  source: "./assets/scene.ply",
  quality: "ultra",
  sh_degree: 3,
  sort_mode: "distance",
  streaming: true,
}

Codebase Intelligence (GraphRAG)

Built-in pipeline for semantic code analysis:

CodebaseScanner → CodebaseGraph → EmbeddingIndex → GraphRAGEngine

| Class | File | Purpose | | ----------------------- | --------------------------------- | -------------------------------------------------------------------- | | CodebaseScanner | src/codebase/CodebaseScanner.ts | Scan repositories, extract symbols/imports/calls | | CodebaseGraph | src/codebase/CodebaseGraph.ts | Graph of nodes (symbols) + edges (dependencies), community detection | | EmbeddingIndex | src/codebase/EmbeddingIndex.ts | Vector index (OpenAI/BM25/Ollama), binary cache for 42x speedup | | GraphRAGEngine | src/codebase/GraphRAGEngine.ts | Graph traversal + semantic search + LLM synthesis | | CodebaseSceneCompiler | src/codebase/visualization/ | 3D visualization of codebase graphs |

import { CodebaseScanner, CodebaseGraph, EmbeddingIndex, GraphRAGEngine } from '@holoscript/core';

const scanner = new CodebaseScanner();
const graph = await scanner.scan('./src');
const index = new EmbeddingIndex();
await index.buildIndex(graph);
const engine = new GraphRAGEngine(graph, index);
const answer = await engine.queryWithLLM('How does the parser work?');

Runtime & ECS

| Class | File | Purpose | | ----------------- | ----------------------------------------- | --------------------------------------------- | | SceneRunner | src/runtime/SceneRunner.ts | Walks AST, spawns entities, runs compositions | | HeadlessRuntime | src/runtime/profiles/HeadlessRuntime.ts | No-GUI execution for tests/CI/servers | | RuntimeBridge | src/runtime/RuntimeBridge.ts | Connects SceneRunner to renderers | | RuntimeRenderer | src/runtime/RuntimeRenderer.ts | PBR materials, particle systems, post-FX |

MCP Integration

Two MCP layers:

• External (packages/mcp-server): Exposes holo_absorb_repo, holo_query_codebase, holo_semantic_search for AI agents
• Internal (src/mcp/ + src/agents/spatial-comms/): MCPOrchestrator, Layer3MCPClient, SPATIAL_MCP_TOOLS for agent-to-agent spatial comm

Smart Assets

| Class | File | Purpose | | ------------------ | -------------------------------- | --------------------------------------------------------------------- | | SmartAssetLoader | src/assets/SmartAssetLoader.ts | Load/configure/bundle assets with load(), doLoad(), getConfig() | | LoaderConfig | src/assets/SmartAssetLoader.ts | Configuration interface for asset loading |

Extension System

| Class | File | Purpose | | -------------------- | -------------------------------------- | ----------------------------------- | | ExtensionRegistry | src/extensions/ExtensionRegistry.ts | Register and load plugin extensions | | ExtensionInterface | src/extensions/ExtensionInterface.ts | Extension lifecycle context |

Note: "Extension" has multiple meanings in the codebase — plugin extensions (ExtensionRegistry), glTF extensions (GLTFTrait), LSP file extensions (ImportResolver.EXTENSIONS), and OpenXR required extensions. See Extension System Architecture.

Package boundary & release posture

@holoscript/core is the foundational public library for external developers and agent frameworks building on HoloScript: the parser, AST, trait system, identity, physics, and the compile_to_* compiler surface. It is a library — it ships no server, no founder-local workspace, and no baked credentials. Where a compiler emits an operational default (e.g. a serving endpoint or a trace directory), that value is caller-owned: you bring your own via the compiler's config options and environment variables, and any host/path in a generated artifact is a generic reference, not the package default.

Known limitations: the compiler target set is broad but evolving; some targets are v0-preview and their emitted contracts may change before the v1 release. Validate a target's output with the package's own checks (e.g. pnpm test / the consumption gate) before depending on it in production.

License

MIT