npm package: @needle-tools/needle-component-compiler
Description: Compile Editor components for Needle Engine for C# and Blender
Author: Needle
Latest version: 3.0.16

## 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`:

```bash
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

```bash
# 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
```

```ts
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.

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

**C# output:**
```csharp
[UnityEngine.Tooltip("The movement speed of the character")]
public float @speed = 5f;
```

**Blender output:**
```json
"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:

```csharp
// 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 ✒️
<b>[🌵 Needle](https://needle.tools)</b> •
[Github](https://github.com/needle-tools) •
[Twitter](https://twitter.com/NeedleTools) •
[Discord](https://discord.needle.tools) •
[Forum](https://forum.needle.tools) •
[Youtube](https://youtube.com/@needle-tools)