@holoscript/robotics-plugin 2.0.2 → 2.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 HoloScript Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @holoscript/robotics-plugin
+
+Robotics plugin for HoloScript compile-time USD/URDF generation and ROS2/Gazebo
+integration surfaces.
+
+## Public Consumption
+
+```js
+import { Parser, USDCodeGen, extractURDFFromHoloComposition } from '@holoscript/robotics-plugin';
+```
+
+The package root ships built JavaScript and declaration files. It does not
+expose TypeScript source as the public runtime entry.

package/dist/ast.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Abstract Syntax Tree (AST) node types for HoloScript robotics
+ *
+ * Extended for Isaac Lab sim-to-real interop (Path A):
+ * - Domain randomization blocks
+ * - Actuator group configurations
+ * - Delayed actuator export hints
+ */
+export type PropertyValue = string | number | boolean | number[] | PropertyValue[];
+export interface DomainRandomizationConfig {
+    /** Physics randomization: mass, friction, damping */
+    physics?: {
+        massScale?: [number, number];
+        frictionRange?: [number, number];
+        dampingRange?: [number, number];
+        armatureRange?: [number, number];
+    };
+    /** Actuator randomization */
+    actuator?: {
+        kpNoise?: number;
+        kdNoise?: number;
+        latencyNoise?: number;
+    };
+    /** Observation noise */
+    observation?: {
+        jointPosNoise?: number;
+        jointVelNoise?: number;
+        imuNoise?: number;
+    };
+    /** Initial state randomization */
+    initialState?: {
+        jointPosRange?: Record<string, [number, number]>;
+        rootPoseRange?: [number, number, number, number, number, number];
+    };
+    /** Disturbance forces */
+    disturbance?: {
+        forceRange?: [number, number];
+        intervalRange?: [number, number];
+    };
+}
+export interface ActuatorGroupConfig {
+    name: string;
+    type: 'IdealPDActuator' | 'DCMotorActuator' | 'DelayedPDActuator' | 'RemotizedPDActuator' | 'ImplicitActuator';
+    jointNames: string[];
+    stiffness?: number;
+    damping?: number;
+    friction?: number;
+    latency?: number;
+}
+export interface ObjectNode {
+    type: 'object';
+    name: string;
+    traits: string[];
+    properties: Record<string, PropertyValue>;
+    domainRandomization?: DomainRandomizationConfig;
+    actuatorGroups?: ActuatorGroupConfig[];
+    template?: string;
+    line?: number;
+    column?: number;
+}
+export interface CompositionNode {
+    type: 'composition';
+    name: string;
+    objects: ObjectNode[];
+    domainRandomization?: DomainRandomizationConfig;
+    line?: number;
+    column?: number;
+}
+export type ASTNode = CompositionNode | ObjectNode;

package/dist/ast.js

@@ -0,0 +1,9 @@
+/**
+ * Abstract Syntax Tree (AST) node types for HoloScript robotics
+ *
+ * Extended for Isaac Lab sim-to-real interop (Path A):
+ * - Domain randomization blocks
+ * - Actuator group configurations
+ * - Delayed actuator export hints
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @holoscript/robotics-plugin v1.0.0
+ * Complete robotics solution: Compile-time (USD/URDF) + Runtime (ROS2/Gazebo)
+ *
+ * Features:
+ * - USD codegen for NVIDIA Isaac Sim (from holoscript-compiler)
+ *   - Isaac Lab sim-to-real interop (Path A)
+ *   - PhysicsDriveAPI for PD actuator control
+ *   - PhysxJointAxisAPI for per-axis friction assumptions
+ *   - Domain randomization configuration blocks
+ * - URDF/SDF export for ROS2/Gazebo
+ * - ROS2 runtime integration (roslibjs)
+ * - VR teleoperation and digital twins
+ *
+ * @packageDocumentation
+ */
+export { USDCodeGen } from './usd-codegen.js';
+export type { IsaacLabConfig } from './usd-codegen.js';
+export { Lexer, TokenType } from './lexer.js';
+export type { Token } from './lexer.js';
+export { Parser } from './parser.js';
+export * from './ast.js';
+export type { DomainRandomizationConfig, ActuatorGroupConfig } from './ast.js';
+import type { CompositionNode, DomainRandomizationConfig, ActuatorGroupConfig } from './ast.js';
+export interface ROS2Config {
+    ros_bridge_url: string;
+    namespace?: string;
+    tf_prefix?: string;
+}
+export interface GazeboConfig {
+    world_file?: string;
+    model_sdf?: string;
+    spawn_position?: [number, number, number];
+}
+export interface RobotJoint {
+    name: string;
+    type: 'revolute' | 'prismatic' | 'fixed' | 'continuous';
+    parent_link: string;
+    child_link: string;
+    axis?: [number, number, number];
+    limits?: {
+        lower: number;
+        upper: number;
+        effort: number;
+        velocity: number;
+    };
+}
+export interface RobotLink {
+    name: string;
+    inertial?: {
+        mass: number;
+        inertia: number[];
+    };
+    visual?: {
+        geometry: string;
+        material?: string;
+    };
+    collision?: {
+        geometry: string;
+    };
+}
+export interface RobotTransmission {
+    name: string;
+    joint: string;
+    actuator: string;
+    mechanicalReduction: number;
+    hardwareInterface: 'position' | 'velocity' | 'effort';
+}
+export interface HoloTraitLike {
+    name: string;
+    properties?: Record<string, unknown>;
+}
+export interface HoloCompositionNodeLike {
+    id?: string;
+    name: string;
+    type?: string;
+    properties?: Record<string, unknown>;
+    traits?: HoloTraitLike[];
+    children?: HoloCompositionNodeLike[];
+}
+export interface HoloCompositionTreeLike {
+    name: string;
+    children?: HoloCompositionNodeLike[];
+}
+export interface ExtractedRobotModel {
+    name: string;
+    links: RobotLink[];
+    joints: RobotJoint[];
+    transmissions: RobotTransmission[];
+    xml: string;
+}
+export interface URDFExtractionOptions {
+    defaultJointType?: RobotJoint['type'];
+    defaultAxis?: [number, number, number];
+    baseLinkName?: string;
+    hardwareScale?: number;
+}
+export declare function buildURDFXML(model: Omit<ExtractedRobotModel, 'xml'>): string;
+export declare function extractURDFFromHoloComposition(composition: HoloCompositionTreeLike, options?: URDFExtractionOptions): ExtractedRobotModel;
+export * from './traits/ROS2HardwareLoopTrait.js';
+export declare const VERSION = "1.0.0";
+declare const _default: {
+    VERSION: string;
+    buildURDFXML: typeof buildURDFXML;
+    extractURDFFromHoloComposition: typeof extractURDFFromHoloComposition;
+    generateIsaacLabFeed: typeof generateIsaacLabFeed;
+};
+export default _default;
+export interface IsaacLabFeedReceipt {
+    sourceHoloHash: string;
+    usdHash: string;
+    configHash: string;
+    generatedAt: string;
+    isaacLabVersion: string;
+    readyForTraining: boolean;
+    notes: string;
+}
+export interface IsaacLabFeedBundle {
+    usd: string;
+    taskConfig: Record<string, unknown>;
+    randomization: DomainRandomizationConfig | undefined;
+    actuators: ActuatorGroupConfig[];
+    receipt: IsaacLabFeedReceipt;
+}
+export declare function generateIsaacLabFeed(ast: CompositionNode, opts?: {
+    isaacLabVersion?: string;
+}): IsaacLabFeedBundle;

package/dist/index.js

@@ -0,0 +1,350 @@
+/**
+ * @holoscript/robotics-plugin v1.0.0
+ * Complete robotics solution: Compile-time (USD/URDF) + Runtime (ROS2/Gazebo)
+ *
+ * Features:
+ * - USD codegen for NVIDIA Isaac Sim (from holoscript-compiler)
+ *   - Isaac Lab sim-to-real interop (Path A)
+ *   - PhysicsDriveAPI for PD actuator control
+ *   - PhysxJointAxisAPI for per-axis friction assumptions
+ *   - Domain randomization configuration blocks
+ * - URDF/SDF export for ROS2/Gazebo
+ * - ROS2 runtime integration (roslibjs)
+ * - VR teleoperation and digital twins
+ *
+ * @packageDocumentation
+ */
+// Compile-time: USD/URDF codegen (from holoscript-compiler)
+export { USDCodeGen } from './usd-codegen.js';
+export { Lexer, TokenType } from './lexer.js';
+export { Parser } from './parser.js';
+export * from './ast.js';
+import { USDCodeGen } from './usd-codegen.js';
+const DEFAULT_URDF_AXIS = [0, 0, 1];
+function normalizeTraitName(name) {
+    return name.replace(/^@/, '').trim().toLowerCase();
+}
+function sanitizeRobotName(name) {
+    return name.trim().replace(/[^A-Za-z0-9_]+/g, '_') || 'robot';
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function asNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function asString(value, fallback) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : fallback;
+}
+function asVec3(value, fallback) {
+    if (Array.isArray(value) && value.length >= 3) {
+        return [
+            asNumber(value[0], fallback[0]),
+            asNumber(value[1], fallback[1]),
+            asNumber(value[2], fallback[2]),
+        ];
+    }
+    return fallback;
+}
+function asJointLimits(value, fallback) {
+    if (Array.isArray(value) && value.length >= 4) {
+        return {
+            lower: asNumber(value[0], fallback?.lower ?? -1.57),
+            upper: asNumber(value[1], fallback?.upper ?? 1.57),
+            effort: asNumber(value[2], fallback?.effort ?? 10),
+            velocity: asNumber(value[3], fallback?.velocity ?? 1),
+        };
+    }
+    const record = asRecord(value);
+    if (Object.keys(record).length > 0) {
+        return {
+            lower: asNumber(record.lower, fallback?.lower ?? -1.57),
+            upper: asNumber(record.upper, fallback?.upper ?? 1.57),
+            effort: asNumber(record.effort, fallback?.effort ?? 10),
+            velocity: asNumber(record.velocity, fallback?.velocity ?? 1),
+        };
+    }
+    return fallback;
+}
+function findTrait(node, predicate) {
+    for (const trait of node.traits ?? []) {
+        const normalizedName = normalizeTraitName(trait.name);
+        if (predicate(normalizedName)) {
+            return { normalizedName, trait };
+        }
+    }
+    return null;
+}
+function getJointTrait(node) {
+    return findTrait(node, (name) => name === 'joint' || name === 'hinge' || name === 'slider' || name.startsWith('joint_'));
+}
+function getMotorTrait(node) {
+    return findTrait(node, (name) => name === 'motor' || name === 'servo' || name === 'actuator' || name.endsWith('_motor'));
+}
+function jointTypeFromTrait(jointTrait, nodeProps, defaultJointType) {
+    const explicitType = normalizeTraitName(asString(nodeProps.joint_type ?? nodeProps.type, defaultJointType));
+    switch (explicitType) {
+        case 'revolute':
+        case 'prismatic':
+        case 'fixed':
+        case 'continuous':
+            return explicitType;
+        case 'hinge':
+            return 'revolute';
+        case 'slider':
+            return 'prismatic';
+    }
+    switch (jointTrait?.normalizedName) {
+        case 'joint_revolute':
+        case 'hinge':
+            return 'revolute';
+        case 'joint_prismatic':
+        case 'slider':
+            return 'prismatic';
+        case 'joint_continuous':
+            return 'continuous';
+        case 'joint_fixed':
+            return 'fixed';
+        default:
+            return defaultJointType;
+    }
+}
+function hardwareInterfaceFromMotor(motorProps) {
+    const commandMode = normalizeTraitName(asString(motorProps.commandMode ?? motorProps.mode, 'position'));
+    if (commandMode === 'velocity')
+        return 'velocity';
+    if (commandMode === 'effort' || commandMode === 'torque')
+        return 'effort';
+    return 'position';
+}
+function scaleMass(mass, hardwareScale) {
+    return Number((mass * Math.pow(hardwareScale, 3)).toFixed(6));
+}
+function mapNodeToRobotLink(node, hardwareScale) {
+    const props = asRecord(node.properties);
+    const baseMass = asNumber(props.mass, 1);
+    const inertia = Array.isArray(props.inertia)
+        ? props.inertia.map((value) => asNumber(value, 0))
+        : [0.01, 0.01, 0.01, 0, 0, 0];
+    const geometry = asString(props.geometry, node.type ?? 'box');
+    const material = typeof props.material === 'string' ? props.material : undefined;
+    const collisionGeometry = asString(props.collisionGeometry ?? props.geometry, geometry);
+    return {
+        name: sanitizeRobotName(node.name || node.id || 'link'),
+        inertial: {
+            mass: scaleMass(baseMass, hardwareScale),
+            inertia,
+        },
+        visual: {
+            geometry,
+            material,
+        },
+        collision: {
+            geometry: collisionGeometry,
+        },
+    };
+}
+function createTransmission(jointName, motorProps, hardwareScale) {
+    return {
+        name: sanitizeRobotName(asString(motorProps.name, `${jointName}_transmission`)),
+        joint: jointName,
+        actuator: sanitizeRobotName(asString(motorProps.actuator ?? motorProps.name, `${jointName}_motor`)),
+        mechanicalReduction: Number((asNumber(motorProps.mechanicalReduction ?? motorProps.gearRatio, 1) * hardwareScale).toFixed(6)),
+        hardwareInterface: hardwareInterfaceFromMotor(motorProps),
+    };
+}
+function buildLinkXml(link) {
+    const lines = [`  <link name="${xmlEscape(link.name)}">`];
+    if (link.inertial) {
+        const [ixx = 0.01, iyy = 0.01, izz = 0.01, ixy = 0, ixz = 0, iyz = 0] = link.inertial.inertia;
+        lines.push('    <inertial>');
+        lines.push(`      <mass value="${link.inertial.mass}"/>`);
+        lines.push(`      <inertia ixx="${ixx}" iyy="${iyy}" izz="${izz}" ixy="${ixy}" ixz="${ixz}" iyz="${iyz}"/>`);
+        lines.push('    </inertial>');
+    }
+    if (link.visual) {
+        lines.push('    <visual>');
+        lines.push(`      <geometry><mesh filename="${xmlEscape(link.visual.geometry)}"/></geometry>`);
+        if (link.visual.material) {
+            lines.push(`      <material name="${xmlEscape(link.visual.material)}"/>`);
+        }
+        lines.push('    </visual>');
+    }
+    if (link.collision) {
+        lines.push('    <collision>');
+        lines.push(`      <geometry><mesh filename="${xmlEscape(link.collision.geometry)}"/></geometry>`);
+        lines.push('    </collision>');
+    }
+    lines.push('  </link>');
+    return lines.join('\n');
+}
+function buildJointXml(joint) {
+    const lines = [`  <joint name="${xmlEscape(joint.name)}" type="${joint.type}">`];
+    lines.push(`    <parent link="${xmlEscape(joint.parent_link)}"/>`);
+    lines.push(`    <child link="${xmlEscape(joint.child_link)}"/>`);
+    if (joint.axis) {
+        lines.push(`    <axis xyz="${joint.axis.join(' ')}"/>`);
+    }
+    if (joint.limits && joint.type !== 'fixed') {
+        lines.push(`    <limit lower="${joint.limits.lower}" upper="${joint.limits.upper}" effort="${joint.limits.effort}" velocity="${joint.limits.velocity}"/>`);
+    }
+    lines.push('  </joint>');
+    return lines.join('\n');
+}
+function buildTransmissionXml(transmission) {
+    return [
+        `  <transmission name="${xmlEscape(transmission.name)}">`,
+        '    <type>transmission_interface/SimpleTransmission</type>',
+        `    <joint name="${xmlEscape(transmission.joint)}">`,
+        `      <hardwareInterface>${transmission.hardwareInterface}</hardwareInterface>`,
+        '    </joint>',
+        `    <actuator name="${xmlEscape(transmission.actuator)}">`,
+        '      <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>',
+        `      <mechanicalReduction>${transmission.mechanicalReduction}</mechanicalReduction>`,
+        '    </actuator>',
+        '  </transmission>',
+    ].join('\n');
+}
+export function buildURDFXML(model) {
+    const lines = [`<robot name="${xmlEscape(model.name)}">`];
+    lines.push(...model.links.map(buildLinkXml));
+    lines.push(...model.joints.map(buildJointXml));
+    lines.push(...model.transmissions.map(buildTransmissionXml));
+    lines.push('</robot>');
+    return lines.join('\n');
+}
+export function extractURDFFromHoloComposition(composition, options = {}) {
+    const defaultJointType = options.defaultJointType ?? 'fixed';
+    const defaultAxis = options.defaultAxis ?? DEFAULT_URDF_AXIS;
+    const hardwareScale = options.hardwareScale ?? 1;
+    const links = [];
+    const joints = [];
+    const transmissions = [];
+    const visitNode = (node, parentLinkName) => {
+        const props = asRecord(node.properties);
+        const link = mapNodeToRobotLink(node, hardwareScale);
+        links.push(link);
+        const jointTrait = getJointTrait(node);
+        const motorTrait = getMotorTrait(node);
+        const jointName = sanitizeRobotName(asString(props.jointName, `${link.name}_joint`));
+        if (parentLinkName && jointTrait) {
+            const limits = asJointLimits(props.joint_limits ?? props.limits, {
+                lower: -1.57,
+                upper: 1.57,
+                effort: 10 * hardwareScale,
+                velocity: 1 * hardwareScale,
+            });
+            const joint = {
+                name: jointName,
+                type: jointTypeFromTrait(jointTrait, props, defaultJointType),
+                parent_link: sanitizeRobotName(parentLinkName),
+                child_link: link.name,
+                axis: asVec3(props.joint_axis ?? props.axis, defaultAxis),
+                limits,
+            };
+            joints.push(joint);
+            if (motorTrait) {
+                const motorProps = {
+                    ...props,
+                    ...asRecord(motorTrait.trait.properties),
+                };
+                transmissions.push(createTransmission(joint.name, motorProps, hardwareScale));
+            }
+        }
+        for (const child of node.children ?? []) {
+            visitNode(child, link.name);
+        }
+    };
+    const baseLinkName = sanitizeRobotName(options.baseLinkName ?? `${composition.name}_base`);
+    links.push({
+        name: baseLinkName,
+        inertial: {
+            mass: scaleMass(1, hardwareScale),
+            inertia: [0.01, 0.01, 0.01, 0, 0, 0],
+        },
+        visual: {
+            geometry: 'base_link',
+        },
+        collision: {
+            geometry: 'base_link',
+        },
+    });
+    for (const child of composition.children ?? []) {
+        visitNode(child, baseLinkName);
+    }
+    const modelWithoutXml = {
+        name: sanitizeRobotName(composition.name),
+        links,
+        joints,
+        transmissions,
+    };
+    return {
+        ...modelWithoutXml,
+        xml: buildURDFXML(modelWithoutXml),
+    };
+}
+// Traits
+export * from './traits/ROS2HardwareLoopTrait.js';
+// Version
+export const VERSION = '1.0.0';
+// Re-export for convenience
+export default {
+    VERSION,
+    buildURDFXML,
+    extractURDFFromHoloComposition,
+    generateIsaacLabFeed,
+};
+export function generateIsaacLabFeed(ast, opts = {}) {
+    const version = opts.isaacLabVersion || '2.3';
+    const codegen = new USDCodeGen({ isaacLabVersion: version });
+    const usd = codegen.generate(ast);
+    // Pull randomization + actuators that the AST already carries
+    const randomization = ast.domainRandomization;
+    const actuators = [];
+    for (const obj of ast.objects ?? []) {
+        if (obj.actuatorGroups)
+            actuators.push(...obj.actuatorGroups);
+    }
+    // Minimal Isaac Lab task config stub (observations / actions / randomization ranges)
+    const taskConfig = {
+        env: 'HoloScriptRobotEnv',
+        num_envs: 4096,
+        seed: 42,
+        observations: ['joint_pos', 'joint_vel', 'imu'],
+        actions: ['joint_torques'],
+        randomization: randomization || {},
+        actuator_groups: actuators,
+        source: 'holoscript',
+        usd_prim: ast.name,
+    };
+    // Simple content hashes for the receipt (evidence loop)
+    const sourceHoloHash = `holo:${ast.name}:${ast.objects?.length || 0}`;
+    const usdHash = `usd:${usd.length}`;
+    const configHash = `cfg:${JSON.stringify(taskConfig).length}`;
+    const receipt = {
+        sourceHoloHash,
+        usdHash,
+        configHash,
+        generatedAt: new Date().toISOString(),
+        isaacLabVersion: version,
+        readyForTraining: true,
+        notes: 'Narrow feed bundle — assets + randomization + actuator config. Policy training & real-robot eval are downstream.',
+    };
+    return {
+        usd,
+        taskConfig,
+        randomization,
+        actuators,
+        receipt,
+    };
+}

package/dist/lexer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * HoloScript Lexer (Tokenizer)
+ *
+ * Converts HoloScript source code into a stream of tokens for parsing.
+ * Supports: keywords, identifiers, traits (@trait), strings, numbers, symbols
+ */
+export declare enum TokenType {
+    KEYWORD = "KEYWORD",// composition, object, using, template, group
+    IDENTIFIER = "IDENTIFIER",// variable_name, link1, base
+    TRAIT = "TRAIT",// @joint_revolute, @force_sensor
+    STRING = "STRING",// "Base", "metal", "cylinder"
+    NUMBER = "NUMBER",// 0.1, 3.14, 100, -2.0
+    LBRACE = "LBRACE",// {
+    RBRACE = "RBRACE",// }
+    LBRACKET = "LBRACKET",// [
+    RBRACKET = "RBRACKET",// ]
+    COLON = "COLON",// :
+    COMMA = "COMMA",// ,
+    COMMENT = "COMMENT",// // comment
+    EOF = "EOF"
+}
+export interface Token {
+    type: TokenType;
+    value: string;
+    line: number;
+    column: number;
+}
+export declare class Lexer {
+    private source;
+    private position;
+    private line;
+    private column;
+    private tokens;
+    private readonly keywords;
+    constructor(source: string);
+    tokenize(): Token[];
+    private scanToken;
+    private scanTrait;
+    private scanString;
+    private scanNumber;
+    private scanIdentifierOrKeyword;
+    private scanSymbol;
+    private skipWhitespace;
+    private skipComment;
+    private currentChar;
+    private peek;
+    private advance;
+    private isWhitespace;
+    private isDigit;
+    private isAlpha;
+    private isAlphaNumericOrUnderscore;
+}