@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 result = holoParser.parseHolo(source);

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

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

Features

• Multi-format Parser - Supports .hs, .hsplus, and .holo files
• Complete AST - Full abstract syntax tree representation
• Validation - Comprehensive error checking with recovery
• 15+ Compile Targets - Web (R3F, Babylon), Unity, Unreal, Godot, iOS, Android, Vision Pro, WebGPU, WASM, VRChat, OpenXR, URDF, DTDL, SDF
• 2,000+ Traits - Modularized across 101 category files covering VR interactions, physics, networking, AI, scripting, automation, animation, nature, magic, sci-fi, emotions, and more
• 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	Legacy parser

Compilers

Compiler	Target	Status
R3FCompiler	React Three Fiber (Web)	Production
BabylonCompiler	Babylon.js (Web)	Production
UnityCompiler	Unity Engine	Production
UnrealCompiler	Unreal Engine 5	Production
GodotCompiler	Godot 4	Production
IOSCompiler	iOS / ARKit	Production
AndroidCompiler	Android / ARCore	Production
VisionOSCompiler	Apple Vision Pro	Production
WebGPUCompiler	WebGPU Compute	Production
WASMCompiler	WebAssembly	Production
VRChatCompiler	VRChat	Alpha
OpenXRCompiler	OpenXR Standard	Production
AndroidXRCompiler	Android XR	Production
URDFCompiler	Robotics (URDF)	Production
DTDLCompiler	Digital Twins (DTDL)	Production
SDFCompiler	SDF Robotics	Production

Trait System

VR traits are modularized into 101 category files 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'; // All 2,000+ traits
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.

License

MIT