@holoscript/core

@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