Needle Engine Component Compiler

Compiles TypeScript component definitions into Unity C# component stubs and Blender Python component schemas for Needle Engine.

Quick Start

No install required — run directly with npx:

npx @needle-tools/needle-component-compiler <target> <output_dir> <input_files...>

| Argument | Description | |---|---| | target | csharp or blender | | output_dir | Directory for generated files | | input_files | One or more .ts source files (globs supported) |

Examples

# Generate C# component stubs
npx @needle-tools/needle-component-compiler csharp ./codegen ./src/MyComponent.ts

# Generate Blender component schemas
npx @needle-tools/needle-component-compiler blender ./codegen ./src/MyComponent.ts

# Process multiple files
npx @needle-tools/needle-component-compiler csharp ./codegen ./src/**/*.ts

# Print version
npx @needle-tools/needle-component-compiler --version

Programmatic API

npm install @needle-tools/needle-component-compiler

import { Compiler, CSharpWriter, FileSink } from "@needle-tools/needle-component-compiler";

const sink = new FileSink("./output");
const writer = new CSharpWriter(sink);
const compiler = new Compiler();
compiler.compile(writer, code, "MyComponent.ts");

Supported TypeScript Features

• Classes extending Behaviour, MonoBehaviour, or implementing IComponent
• Public, protected, and private fields with type annotations
• Default values (primitives, new expressions, literals)
• Array types: T[], Array<T>
• Union types (nullable types like Object3D | null resolve to the concrete type)
• Enums (with value initialization)
• Methods with parameters and return types
• Destructured parameters (compiled as object)

Comment Directives

Use // comments above classes, fields, or methods to control code generation:

| Directive | Target | Description | |---|---|---| | @generate-component | Class | Force generation (not required, classes are generated by default) | | @dont-generate-component | Class | Skip generating this class entirely | | @type MyNamespace.MyType | Class / Field | Override the resolved C# type or base class | | @abstract | Class | Mark the generated class as abstract | | @serializeField | Field | Emit [UnityEngine.SerializeField] attribute | | @nonSerialized | Field / Method | Skip generating C# code for this member | | @tooltip "My text" | Field | Emit [UnityEngine.Tooltip("My text")] (C#) or "description" (Blender) | | @contextmenu "Label" | Method | Emit [UnityEngine.ContextMenu("Label")] | | @ifdef MY_DEFINE | Field | Wrap field in #if MY_DEFINE / #endif |

JSDoc Tooltips

JSDoc comments (/** ... */) on fields are automatically converted to tooltips. The text is sanitized (inline code, URLs, images, and JSDoc tags are stripped) to produce clean tooltip text.

export class MyComponent extends Behaviour {
    /** The movement speed of the character */
    public speed: number = 5;
}

C# output:

[UnityEngine.Tooltip("The movement speed of the character")]
public float @speed = 5f;

Blender output:

"speed": {
    "type": "float",
    "value": 5,
    "description": "The movement speed of the character"
}

An explicit // @tooltip directive takes priority over a JSDoc comment on the same field.

Codegen Fences

Generated C# files are wrapped in codegen fences:

// NEEDLE_CODEGEN_START
// auto generated code - do not edit directly

#pragma warning disable

namespace Needle.Typescript.GeneratedComponents
{
    public partial class MyComponent : UnityEngine.MonoBehaviour
    {
        public float @speed = 5f;
    }
}

// NEEDLE_CODEGEN_END

This allows you to add custom code outside the fences that will be preserved when the file is regenerated.

Contact ✒️

🌵 Needle • Github • Twitter • Discord • Forum • Youtube